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ésultat | Ce qu’il dit |
|---|---|
verified | La source officielle nommée indique ce qui est renvoyé, dans la règle de fraîcheur |
partial | Une partie de la réponse repose sur la source ; les raisons disent ce qui manque |
unverified | La source a répondu mais ne le confirme pas (par exemple, l’entreprise est cessée) |
status_unknown | L’entreprise figure dans la source, qui n’indique aucun statut actuel |
not_found | Identifiant valide, dans la couverture, aucune fiche |
not_covered | Le pays, le type d’identifiant, la donnée ou la période ne sont pas couverts |
ambiguous | Plusieurs entreprises pourraient correspondre |
stale | Une copie stockée plus ancienne que la règle, faute d’avoir pu rafraîchir la source |
source_unavailable | La 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 parRetry-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_unknownoupartial, 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
Ce guide décrit des choix de conception, pas des obligations légales. Une API de vérification d’entreprises répond à ce qu’indiquent les registres officiels ; ce n’est ni un KYB complet, ni une recherche de qui détient l’entreprise, ni un filtrage des sanctions, ni une analyse de crédit. La couverture, les noms de champs et les résultats varient d’un fournisseur à l’autre : lisez la documentation du vôtre. Fuentio couvre la France, l’Espagne et le Royaume-Uni ; voir la page Couverture.
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
- Résultats de Fuentio, sens et limites : api.fuentio.com/docs/outcomes
- Référence des erreurs de Fuentio : api.fuentio.com/docs/errors
- Licence Ouverte 2.0 (Etalab) : etalab.gouv.fr
- Open Government Licence v3.0 : nationalarchives.gov.uk
- Companies House Public Data API : developer.company-information.service.gov.uk
