Construire une API de vérification d’entreprises : ce que les développeurs doivent réussir

Recherche, rapprochement, résultats, attribution des sources, erreurs, cache et données incomplètes : les choix qui rendent fiable une API de vérification.

· Par l’équipe Fuentio · 8 min de lecture

Image de partage : « Construire une API de vérification d’entreprises : ce que les développeurs doivent réussir » sur le fond papier de Fuentio, avec l’étiquette Guide.

Appeler un registre d’entreprises est la partie facile. Le plus dur est tout ce qui entoure l’appel : savoir de quelle entreprise on parle, dire à quel point on est sûr, indiquer d’où vient chaque fait, échouer d’une façon dont l’appelant peut tirer parti, et ne jamais présenter la copie d’hier comme la vérité du jour. Ce guide passe en revue les choix qu’une équipe technique doit réussir, qu’elle construise l’API elle-même ou qu’elle en évalue une.

Ce que vous allez apprendre

  • Pourquoi une recherche doit partir de l’identifiant, et comment le contrôler
  • Comment gérer le rapprochement par nom sans choisir en silence la mauvaise entreprise
  • Pourquoi une liste fermée de résultats vaut mieux qu’un vrai/faux
  • Comment attribuer les sources, gérer les erreurs, mettre en cache sans tromper et dire « nous ne savons pas »

En bref : identifiez les entreprises par leur numéro officiel, jamais par le seul nom ; renvoyez un résultat tiré d’une liste fixe, avec des raisons lisibles par une machine ; mettez la source, la licence et la date de vérification sur chaque réponse ; utilisez une liste fermée de codes d’erreur qui indiquent l’étape suivante ; et mettez en cache selon une règle de fraîcheur explicite, pour qu’une copie ancienne soit signalée comme telle.

La recherche : partir de l’identifiant

Un registre est indexé par un numéro officiel ; votre API doit l’être aussi. Contrôlez le format avant de dépenser un appel. Un SIREN compte 9 chiffres et une clé de contrôle ; un SIRET en compte 14. Un numéro de société britannique compte 8 caractères (00445790, SC123456). Une société espagnole se trouve par sa feuille du Registro Mercantil (V-5581).

Trois cas méritent leur propre réponse plutôt qu’un 404 générique :

  • Invalide : le numéro échoue au contrôle de format ou de clé. Rien n’a été recherché.
  • Identifiant ambigu : une même chaîne correspond à plusieurs types d’identifiants dans un pays. Demandez à l’appelant de préciser, par exemple avec un paramètre id_scheme.
  • Introuvable : le numéro est valide et couvert, mais le registre n’a aucune fiche. C’est une vraie réponse ; en France, elle ne prouve pas que l’entreprise n’a jamais existé, car certaines unités ont refusé la diffusion publique.

Le rapprochement : un nom ne décide jamais seul

La plupart des formulaires commencent par un nom. Les noms se répètent, changent et s’abrègent : une recherche par nom doit donc renvoyer des candidates, chacune avec un score et ses raisons, jamais une « meilleure correspondance » silencieuse. Quand plusieurs entreprises conviennent, la réponse honnête est « ambiguë », avec les candidates, pour qu’une personne ou le système appelant choisisse par le numéro officiel.

Expliquez chaque rapprochement en termes que l’appelant peut journaliser : même identifiant, même code postal, nom identique une fois la forme juridique retirée. Un rapprochement sans raisons ne peut pas être relu.

Les résultats : pas de booléen

"verified": true cache tout ce qui compte. L’entreprise est-elle active, ou simplement présente ? La source répondait-elle ? Le pays est-il seulement couvert ? Une liste fermée de résultats, chacun au sens précis, permet aux appelants d’écrire des règles fiables. Fuentio en utilise neuf, et documente aussi ce que chacun ne signifie pas :

RésultatCe qu’il dit
verifiedLa source officielle nommée indique ce qui est renvoyé, dans la règle de fraîcheur
partialUne partie de la réponse repose sur la source ; les raisons disent ce qui manque
unverifiedLa source a répondu mais ne le confirme pas (par exemple, l’entreprise est cessée)
status_unknownL’entreprise figure dans la source, qui n’indique aucun statut actuel
not_foundIdentifiant valide, dans la couverture, aucune fiche
not_coveredLe pays, le type d’identifiant, la donnée ou la période ne sont pas couverts
ambiguousPlusieurs entreprises pourraient correspondre
staleUne copie stockée plus ancienne que la règle, faute d’avoir pu rafraîchir la source
source_unavailableLa source n’a pas répondu et rien d’exploitable n’est disponible

Quand plusieurs s’appliquent, définissez lequel l’emporte. Fuentio les applique dans un ordre fixe, de source_unavailable à verified, pour renvoyer le plus prudent.

Chaque résultat a besoin de raisons lisibles par une machine (company_active, company_inactive, status_unknown, insolvency_administration…) et, idéalement, du détail des contrôles. Voici la liste des contrôles d’une vraie vérification de TESCO PLC, enregistrée le 16 octobre 2026 :

"checks": [
  {"check": "identifier_valid", "result": "pass", "detail": "The ID has a valid format."},
  {"check": "record_found", "result": "pass", "detail": "Found in the official source."},
  {"check": "status_active", "result": "pass", "detail": "Register status: active."},
  {"check": "address_present", "result": "pass", "detail": "Registered address published."},
  {"check": "fresh", "result": "pass", "detail": "Checked against the source within its refresh window."}
]

La source sur chaque réponse

Chaque réponse doit nommer sa source, sa licence et sa date de lecture, pas seulement dans la documentation mais dans la réponse elle-même. Les registres ouverts imposent une attribution : la Licence Ouverte demande de citer la source et la date de mise à jour ; les données de Companies House relèvent de l’Open Government Licence v3.0, qui demande sa propre mention. Voir aussi la provenance sur chaque réponse.

Distinguez trois dates souvent confondues : quand la source a publié la donnée, quand vous l’avez récupérée, et quand vous l’avez vérifiée pour la dernière fois auprès de la source.

Des erreurs exploitables par l’appelant

Une liste fermée de codes d’erreur, chacun avec un statut HTTP et une indication, transforme les échecs en décisions. Quelques-uns comptent en pratique :

  • invalid_identifier (400) : corriger la saisie ; réessayer ne sert à rien.
  • not_found (404) : une vraie réponse sur l’entreprise, pas une panne.
  • rate_limited (429) : attendre la durée indiquée par Retry-After.
  • quota_exceeded (402) : les unités de l’appelant sont épuisées.
  • upstream_unavailable (503) : la source officielle ne répond pas ; réessayer plus tard.

Rendez aussi le corps de l’erreur prévisible. En voici un vrai, renvoyé par l’essai sans clé de Fuentio une fois les unités du jour consommées :

{"data": null, "meta": {"request_id": "req_IeGVSzl1UrGq9C6C"},
 "error": {"code": "quota_exceeded", "message": "Quota used up: 20 of 20 units today.",
  "hint": "The keyless trial starts again tomorrow (UTC). For more now, get a free key (100 units a month) with POST /v1/keys."}}

Notre démarrage rapide détaille les nouvelles tentatives : premier appel, unités, erreurs et nouvelles tentatives.

Mettre en cache sans tromper

Les registres changent lentement et répondent parfois lentement : vous mettrez en cache. La règle est de le dire. Donnez à chaque source une fenêtre de fraîcheur, renvoyez retrieved_at et last_verified_at, signalez les réponses servies depuis le cache et, quand la source est indisponible, renvoyez la copie stockée comme stale plutôt que comme actuelle. Laissez les appelants demander des données plus fraîches quand ils en ont besoin (Fuentio accepte un max_age en secondes).

Gardez un instantané de ce que vous avez servi, avec une empreinte, pour prouver ensuite quelle était la réponse. C’est l’idée des reçus et des codes de preuve.

Savoir dire « nous ne savons pas »

Les informations incomplètes sont normales ; le rôle de l’API est de les rendre visibles :

  • Espagne : le BORME publie des actes, pas un statut. Une société sans acte sur son statut depuis 2009 n’a pas de statut indiqué ; le résultat honnête est status_unknown ou partial, jamais « active ».
  • France : « cessée » dans Sirene désigne une unité fermée, pas la preuve d’une dissolution juridique. Dites « cessée », pas « dissoute ».
  • Royaume-Uni : les chiffres ne viennent que des comptes déposés par voie électronique, et les petites sociétés déposent rarement le montant de leurs ventes. Un champ vide signifie « non déposé », pas « zéro ».

Données personnelles et texte non fiable

Les fiches d’entreprises contiennent des personnes : dirigeants, associés, entrepreneurs individuels. Décidez tôt de ce que vous ne servez jamais, et retirez-le à l’ingestion plutôt qu’à l’affichage. Et traitez chaque champ de texte copié d’un registre comme une donnée, jamais comme une instruction, surtout si des agents IA lisent vos réponses.

Limites

Questions fréquentes

Une API de vérification d’entreprises doit-elle renvoyer vrai ou faux ?

Non. Un booléen ne distingue pas « cessée », « non couverte », « source indisponible » et « statut non indiqué ». Renvoyez un résultat tiré d’une liste fermée, avec ses raisons.

Comment une API doit-elle traiter une entreprise introuvable ?

En distinguant un identifiant invalide, un identifiant valide hors couverture, et un identifiant valide sans fiche. Chacun mène à une étape suivante différente.

Combien de temps peut-on garder des données d’entreprises en cache ?

Autant que le permettent le rythme de mise à jour de la source et votre usage, à condition que la réponse indique sa dernière vérification et soit signalée comme ancienne au-delà de la règle.

Faut-il citer la source dans les réponses de l’API ?

Les licences des registres ouverts l’exigent en général, et cela permet à vos utilisateurs de prouver d’où vient un fait. Mettez-la dans chaque réponse, pas seulement dans la documentation.

Sources

← Tous les articles · Flux RSS