De la consultation à la décision de vérification : parcours complet de l’API Fuentio

Un parcours réel de l’API Fuentio : couverture, recherche par nom, consultation, résultats de vérification, codes de preuve et reçus, avec du Python testé.

· Mis à jour le 17 octobre 2026 · Par l’équipe Fuentio · 7 min de lecture

Image de partage : « De la consultation à la décision de vérification : parcours complet de l’API Fuentio » sur le fond papier de Fuentio, avec l’étiquette Tutoriel.

Ce parcours suit une vérification d’entreprise du début à la fin avec l’API REST de Fuentio : trouver l’entreprise, la consulter, la vérifier, garder la preuve, puis transformer le résultat en décision dans votre propre code. Chaque réponse montrée est réelle, enregistrée depuis l’API en production et raccourcie, et le Python de la fin a été exécuté contre l’API avant la publication de cet article.

Ce que vous allez apprendre

  • Comment vérifier la couverture, chercher par nom et consulter une entreprise par son numéro
  • Ce que renvoie une vérification : résultat, raisons, contrôles, signaux et code de preuve
  • Comment retrouver le résultat plus tard, sous forme de page de preuve ou de reçu
  • Comment faire correspondre les résultats à accepter, revoir et refuser, en Python fonctionnel

En bref : cherchez par nom si vous n’avez pas le numéro officiel (2 unités), consultez l’entreprise par son numéro (1 unité), puis appelez POST /v1/verifications (5 unités) pour obtenir un résultat avec ses raisons et un code de preuve. Associez verified, partial et unverified à vos propres actions, et gardez le code de preuve avec votre décision. Aucune clé n’est nécessaire pour essayer : l’essai sans clé donne 20 unités par jour.

Avant de commencer

L’adresse de base est https://api.fuentio.com. Chaque réponse a la même enveloppe : data, meta (source, fraîcheur, unités facturées) et error. Sans clé, vous utilisez l’essai sans clé, limité à 20 unités par jour et 1 requête par seconde ; avec une clé, envoyez-la en X-API-Key ou en Authorization: Bearer. Une clé gratuite donne 100 unités par mois. S’il s’agit de votre tout premier appel, le démarrage rapide de l’API explique les unités, les erreurs et les nouvelles tentatives.

Étape 1 : vérifier ce qui est couvert

GET /v1/countries est gratuit et indique les pays, les types d’identifiants et les sources disponibles. Pour le Royaume-Uni, il répond notamment que la couverture est le registre de Companies House, avec la fiche actuelle de chaque société, dissoutes comprises, ses procédures d’insolvabilité, ses sûretés et ses derniers dépôts, sans dirigeants ni autres personnes. La France et l’Espagne sont aussi couvertes ; la page Couverture présente la même chose, en clair.

Étape 2 : trouver l’entreprise par son nom

Si vous n’avez qu’un nom, commencez par chercher. Une vraie recherche sur « mercadona » en Espagne, enregistrée le 12 octobre 2026 :

curl "https://api.fuentio.com/v1/companies/search?country=ES&q=mercadona"
{
  "data": [{
    "id": "ES-RMHOJA-V-5581",
    "name": {"original": "MERCADONA SA"},
    "identifiers": [{"scheme": "ES_RM_HOJA", "value": "V-5581", "primary": true}],
    "registered_address": {"original": "C/ ALFONSO ROIG ALFONSO S/N (ALBALAT DELS SORELLS)", "region": "VALENCIA/VALÈNCIA"},
    "match": {"score": 0.95, "reasons": ["name_normalized_exact"]}
  }],
  "meta": {"total": 1}
}

Une seule candidate, identique après normalisation. Avec un nom courant, vous en obtiendriez beaucoup : la même recherche sur « telefonica » en a renvoyé 251. Retenez la candidate par son identifiant, jamais par le seul meilleur score ; comment trouver une société espagnole par son nom et lire sa feuille détaille la démarche.

Étape 3 : consulter l’entreprise

Avec le numéro officiel, une consultation renvoie la fiche. Une vraie réponse pour DANONE, SIREN 552032534, enregistrée le 12 octobre 2026 et raccourcie :

curl https://api.fuentio.com/v1/companies/FR/552032534
{
  "id": "FR-SIREN-552032534",
  "name": {"original": "DANONE"},
  "legal_form": {"original_label": "SA à conseil d'administration (s.a.i.)", "elf_code": "K65D"},
  "status": {"value": "active", "original_label": "Active", "as_of": "2026-09-10"},
  "registered_address": {"original": "59-61 RUE LA FAYETTE 75009 PARIS"},
  "activity": {"original_code": "70.10Z", "original_label": "Activités des sièges sociaux", "nace_rev2": "70.10"},
  "identifiers": [
    {"scheme": "FR_SIREN", "value": "552032534", "primary": true},
    {"scheme": "FR_SIRET", "value": "55203253400703", "primary": false},
    {"scheme": "EU_VAT", "value": "FR27552032534", "primary": false}
  ],
  "provenance": {"source": "fr_recherche_entreprises", "last_verified_at": "2026-10-11T22:06:01.689264Z"}
}

Chaque valeur garde la formulation du registre (original_label) à côté d’une valeur normalisée, et la provenance dit d’où vient la donnée et quand elle a été vérifiée pour la dernière fois. Une consultation coûte 1 unité. Elle dit ce qu’indique la fiche ; elle ne donne pas de décision.

Étape 4 : vérifier l’entreprise

Une vérification lit la fiche, exécute une série fixe de contrôles et renvoie un résultat. Une vraie vérification de TESCO PLC, lancée le 16 octobre 2026 :

curl -X POST https://api.fuentio.com/v1/verifications \
  -H "Content-Type: application/json" \
  -d '{"country": "GB", "identifier": "00445790"}'
{
  "data": {
    "proof_code": "FUE-GB-20261016-5QBDT2",
    "checked_at": "2026-10-16T08:41:27.492024+00:00",
    "checks": [
      {"check": "identifier_valid", "result": "pass"},
      {"check": "record_found", "result": "pass"},
      {"check": "status_active", "result": "pass"},
      {"check": "address_present", "result": "pass"},
      {"check": "fresh", "result": "pass"}
    ],
    "signals": {"insolvency": {"value": "none_found", "note": "Companies House insolvency record checked (the company's whole life); none found"}},
    "result": {"outcome": "verified", "reasons": ["company_active"],
      "summary": "TESCO PLC (GB, Companies House company number 00445790): verified, active per Companies House Public Data API, checked 2026-10-16. Proof FUE-GB-20261016-5QBDT2."}
  },
  "meta": {"cost": {"units": 5}}
}

Pour une vérification d’entreprise, le résultat est l’un de trois : verified, partial ou unverified. Les raisons disent pourquoi, en codes lisibles par une machine ; les contrôles montrent chaque étape, et les signaux rapportent ce qui a été trouvé en matière de cessation, de dissolution et d’insolvabilité.

À quoi ressemble un résultat « unverified »

Le même appel pour APPLETREE FARM CRESSING LIMITED (numéro 12401266), le même jour :

"checks": [{"check": "no_open_insolvency", "result": "fail", "detail": "Companies House: status 'In Administration' (administration open)."}],
"result": {"outcome": "unverified", "reasons": ["insolvency_administration"]}

La société est toujours inscrite, mais une administration est ouverte : elle n’est donc pas vérifiée. Pourquoi cette distinction compte : une entreprise active n’est pas toujours une entreprise sûre.

Et un résultat « partial »

Pour MERCADONA SA en Espagne, enregistrée le 12 octobre 2026, le résultat était partial, avec les raisons status_unknown et events_only_coverage : le BORME publie des actes, et aucun n’indique le statut actuel de la société. Le contrôle status_active a renvoyé unknown, pas fail.

Étape 5 : garder et retrouver la preuve

Chaque vérification a un code de preuve. Gardez-le avec votre décision ; vous pouvez retrouver le résultat à tout moment, gratuitement :

  • GET /v1/verifications/{id or proof code} renvoie la vérification stockée.
  • GET /v1/public/proofs/{proof_code} renvoie la version publique, sans clé, et chacun peut l’ouvrir sur notre page de preuve : FUE-GB-20261016-5QBDT2.
  • GET /v1/receipts/{request_id} renvoie le reçu d’une réponse : la copie stockée, avec son empreinte et sa référence d’instantané.

Les codes de preuve sont conservés 24 mois. Ce que doit contenir un enregistrement complet, et pourquoi un reçu n’est pas un document certifié : que doit contenir un enregistrement vérifiable de vérification d’entreprise.

Étape 6 : transformer le résultat en décision

L’API rapporte ; votre code décide. Ce Python n’utilise que la bibliothèque standard et associe les résultats à des actions. Tout ce qui est inattendu part en revue :

import json
import urllib.error
import urllib.request

API = "https://api.fuentio.com"
DECISION = {"verified": "approve", "partial": "manual_review", "unverified": "decline"}


def verify(country, identifier, key=None):
    """POST /v1/verifications : le résultat, les raisons et un code de preuve (5 unités)."""
    headers = {"Content-Type": "application/json", "Accept": "application/json"}
    if key:
        headers["X-API-Key"] = key
    req = urllib.request.Request(f"{API}/v1/verifications", method="POST", headers=headers,
                                 data=json.dumps({"country": country, "identifier": identifier}).encode())
    try:
        with urllib.request.urlopen(req, timeout=30) as r:
            return json.load(r)
    except urllib.error.HTTPError as e:  # les réponses 4xx et 5xx ont le même corps {data, meta, error}
        return json.load(e)


body = verify("GB", "00445790")
if body.get("error"):
    print("error:", body["error"]["code"], "-", body["error"].get("hint", ""))
else:
    v = body["data"]
    outcome = v["result"]["outcome"]
    print(outcome, v["result"]["reasons"], v["proof_code"])
    print("decision:", DECISION.get(outcome, "manual_review"))

Exécuté sans clé le 16 octobre 2026, il a affiché :

verified ['company_active'] FUE-GB-20261016-VY43F6
decision: approve

Cette exécution a créé son propre code de preuve, que chacun peut ouvrir : FUE-GB-20261016-VY43F6.

Gérer les erreurs

Les erreurs viennent d’une liste fermée, chacune avec une indication. Celles à traiter en premier :

  • invalid_identifier (400) : le numéro est mal formé ; demandez à l’utilisateur de le corriger.
  • not_found (404) : numéro valide, aucune fiche. Cela coûte 1 unité.
  • rate_limited (429) : trop de requêtes par seconde ; attendez la durée indiquée par Retry-After.
  • quota_exceeded (402) : unités épuisées. L’essai sans clé repart le lendemain (UTC).
  • upstream_unavailable (503) : la source officielle ne répond pas ; réessayez plus tard.

Pour d’autres options de vérification, comme transmettre votre propre reference avec la requête, voir comment vérifier une entreprise et obtenir un code de preuve.

Combien cela coûte, et comment payer

Une recherche coûte 2 unités, une consultation 1 et une vérification 5 ; les reçus, les vérifications stockées et la couverture sont gratuits. Quand l’essai et la clé gratuite ne suffisent plus, les offres commencent avec Starter à 49 € par mois pour 2 000 unités. Vous payez par carte depuis la page Tarifs (comment payer Fuentio : paiement sécurisé avec Creem), et la clé payante est envoyée par e-mail dès que le paiement est validé. Les prix s’entendent hors TVA, et rien n’est facturé au-delà : à la limite, l’API répond quota_exceeded. Plus de détails dans la tarification d’une API de données d’entreprises expliquée.

Limites

Questions fréquentes

Faut-il une clé API pour suivre ce parcours ?

Non. L’essai sans clé donne 20 unités par jour, de quoi faire une recherche, une consultation et deux vérifications. Une clé gratuite donne 100 unités par mois.

Quelle différence entre une consultation et une vérification ?

Une consultation renvoie la fiche de l’entreprise (1 unité). Une vérification exécute des contrôles sur cette fiche et renvoie un résultat, des raisons et un code de preuve (5 unités).

Comment retrouver plus tard le résultat d’une vérification ?

Appelez GET /v1/verifications/{id or proof code}, gratuitement, ou ouvrez le code de preuve sur fuentio.com/fr/proof/. Les codes sont conservés 24 mois.

Quel résultat doit bloquer l’entrée en relation ?

C’est votre politique. Un choix courant : accepter verified, revoir partial, refuser ou faire remonter unverified, et revoir tout le reste.

Sources

← Tous les articles · Flux RSS