Démarrer avec l’API Fuentio : premier appel, unités, erreurs et nouvelles tentatives

Ce guide vous mène de zéro à une intégration qui fonctionne avec l’API REST de Fuentio : une première consultation d’entreprise française, la forme de chaque réponse, le décompte des unités et la gestion des erreurs sans surcharger l’API. Chaque exemple utilise une vraie entreprise et une vraie réponse enregistrée depuis l’API.

Rien n’est nécessaire pour commencer : l’essai sans clé donne 20 unités par jour. Pour aller plus loin, une clé gratuite donne 100 unités par mois.

Ce que vous allez apprendre

• Commencer sans clé, puis créer une clé gratuite
• Votre premier appel en curl, Python et JavaScript
• Les trois parties de chaque réponse : data, meta, error
• Le décompte des unités, et où lire ce qu’il vous reste
• Quelles erreurs corriger, lesquelles relancer, et combien attendre

Étape 1 : commencer sans clé, ou créer une clé gratuite

Tous les appels qui lisent des données d’entreprise fonctionnent sans clé, avec l’essai gratuit : 20 unités par jour et par connexion. De quoi faire quelques essais.

Pour votre application, créez une clé gratuite. Un seul appel, avec votre e-mail (une clé gratuite par personne ; la clé ne s’affiche qu’une fois, enregistrez-la tout de suite) :

curl -X POST https://api.fuentio.com/v1/keys -H "Content-Type: application/json" -d '{"email": "YOUR_EMAIL"}'

Vous pouvez aussi l’obtenir sur la page des tarifs. Envoyez la clé dans l’en-tête X-API-Key à chaque appel (ou en Authorization: Bearer YOUR_API_KEY). Ne la mettez jamais dans le code du navigateur : appelez l’API depuis votre serveur.

Étape 2 : votre premier appel

Consultez RENAULT avec son SIREN, le numéro à 9 chiffres de chaque entreprise française :

curl https://api.fuentio.com/v1/companies/FR/441639465 -H "X-API-Key: YOUR_API_KEY"

Le même appel en Python, avec httpx :

import httpx

r = httpx.get("https://api.fuentio.com/v1/companies/FR/441639465",
              headers={"X-API-Key": "YOUR_API_KEY"}, timeout=30)
body = r.json()
if body["error"]:
    print(body["error"]["code"], body["error"]["message"], body["error"]["hint"])
else:
    company = body["data"]
    print(company["name"]["original"], company["status"]["value"], body["meta"]["source"])

Et en JavaScript (Node 18 ou tout environnement avec fetch) :

const res = await fetch("https://api.fuentio.com/v1/companies/FR/441639465", {
  headers: { "X-API-Key": process.env.FUENTIO_API_KEY },
});
const body = await res.json();
if (body.error) console.log(body.error.code, body.error.message);
else console.log(body.data.name.original, body.data.status.value, body.meta.source);

Pour la France, l’identifiant peut être un SIREN, un SIRET (14 chiffres), un numéro de TVA français ou un LEI ; les espaces, points et tirets sont ignorés. Pour l’Espagne, c’est la feuille du Registro Mercantil (par exemple V-5581) ou un LEI. L’Espagne ne se consulte pas par numéro fiscal : cherchez d’abord par nom (voir trouver une société espagnole par son nom).

Étape 3 : lire la réponse

Chaque réponse a les mêmes trois parties.

• data : la fiche de l’entreprise (ou une liste, pour une recherche). Les valeurs gardent la formulation du registre, avec des codes normalisés et des libellés anglais à côté.
• meta : d’où vient la réponse et ce qu’elle a coûté : source, fetched_at (quand nous avons lu la source), last_verified_at (quand nous l’avons vérifiée pour la dernière fois), stale (true si la source était indisponible et que vous recevez notre dernière copie), le coût en unités et un request_id.
• error : null, ou un objet avec un code, un message et un hint qui indique quoi faire ensuite.

Voici une partie de la vraie réponse pour RENAULT, enregistrée depuis l’API le 12 octobre 2026 :

{
  "data": {
    "id": "FR-SIREN-441639465",
    "name": { "original": "RENAULT" },
    "legal_form": { "original_code": "5510", "original_label": "SA nationale à conseil d'administration", "elf_code": "1NF1" },
    "status": { "value": "active", "original_label": "Active", "as_of": "2025-12-06" },
    "incorporation_date": "2002-04-01",
    "registered_address": { "original": "122-122 122 B AVENUE DU GENERAL LECLERC 92100 BOULOGNE-BILLANCOURT", "postal_code": "92100" },
    "activity": { "original_code": "64.20Z", "original_label": "Activités des sociétés holding", "label_en": "Activities of holding companies" }
  },
  "meta": {
    "source": "fr_recherche_entreprises",
    "stale": false,
    "cost": { "units": 1 },
    "request_id": "req_3geNJDKcO50j4-ke"
  },
  "error": null
}

Deux habitudes qui servent plus tard :

1. Enregistrez meta.source et meta.last_verified_at avec chaque valeur que vous gardez. Quand on vous demandera « d’où vient ce chiffre ? », vous aurez la réponse.
2. Gardez le request_id. Si une réponse vous semble fausse, citez-le en nous écrivant, ou signalez-la avec POST /v1/issues.

Étape 4 : comprendre les unités

Chaque appel coûte un nombre fixe d’unités. Les plus courants :

Les règles à connaître :

• Les erreurs ne coûtent rien, sauf not_found sur un identifiant bien formé (1 unité) : c’est une vraie réponse du registre.
• Les unités repartent à zéro chaque mois (chaque jour pour l’essai sans clé). Au-delà du quota, vous recevez quota_exceeded, jamais un dépassement facturé.
• Chaque réponse porte meta.cost : les unités de l’appel (units) et celles qu’il vous reste (remaining). L’en-tête de réponse X-Request-ID reprend le request_id.
• GET /v1/usage (gratuit) renvoie votre offre, les unités utilisées sur la période et celles qui restent. La page compte affiche la même chose dans un navigateur.

Étape 5 : gérer les erreurs, et ne relancer que ce qui vaut la peine

La liste des codes d’erreur est fermée : vous pouvez traiter chaque cas. Classez-les selon ce que votre code doit faire :

Une petite fonction de relance en Python qui suit ces règles :

import time
import httpx

RETRY = {"rate_limited", "upstream_unavailable", "internal_error"}

def fuentio_get(path, key, attempts=4):
    for attempt in range(attempts):
        r = httpx.get("https://api.fuentio.com" + path, headers={"X-API-Key": key}, timeout=30)
        body = r.json()
        error = body.get("error")
        if not error or error["code"] not in RETRY or attempt == attempts - 1:
            return body
        wait = int(r.headers.get("Retry-After", 2 ** attempt))
        time.sleep(wait)

Elle ne relance que les trois erreurs temporaires, respecte Retry-After quand l’API l’envoie, et espace les essais sinon. Tout le reste revient directement à votre code, où le hint dit quoi faire.

Étape 6 : la suite

• Une décision, pas seulement des données : POST /v1/verifications renvoie un résultat avec ses raisons et un code de preuve vérifiable par tous. Voir vérifier une entreprise et obtenir un code de preuve par API.
• Procédures collectives et TVA : voir procédures collectives et TVA par API.
• Une liste d’entreprises : voir vérifier une liste de SIREN en masse, ou essayez d’abord la vérification de liste gratuite.
• Un agent IA : les mêmes données et unités sont disponibles en MCP : connectez votre agent.

La référence complète est dans la documentation, avec le fichier OpenAPI et la documentation interactive. Voyez ce que nous couvrons pays par pays.

Parcourir les pages d’une recherche

Une recherche renvoie une page à la fois et vous dit où vous en êtes. La meta de la recherche enregistrée pour MERCADONA montre les champs à lire : page, page_size (10 par défaut), total (le nombre d’entreprises trouvées) et next_page, qui vaut null sur la dernière page. Chaque page coûte 2 unités : ne demandez que celles dont vous avez besoin. Si le premier résultat a un match.score élevé et la bonne commune, arrêtez-vous là. Quand il vous faut tous les résultats, bouclez tant que next_page est renseigné, avec un plafond de pages pour qu’un nom très courant ne consomme pas vos unités du mois.

Deux habitudes de plus pour les recherches. Affinez avec postal_code ou locality dès que vous les avez : moins de pages, un meilleur classement. Et ne prenez jamais le premier résultat pour l’entreprise voulue : une recherche classe des noms, et sa meta.uncertainty le rappelle. Quand la décision compte, confirmez avec un identifiant, ou appelez POST /v1/resolve, qui explique pourquoi un candidat est lié, possible ou écarté.

Limites. France : toutes les entreprises du répertoire Sirene public, lues dans l’Annuaire des Entreprises de l’État ; annonces de procédures collectives du BODACC depuis 2008. Espagne : les sociétés ayant un acte publié au BORME depuis le 2 janvier 2009, des événements seulement, avec un statut inconnu sauf si un acte dit autre chose ; pas de consultation par numéro fiscal. Aucun nom de personne n’est jamais renvoyé. L’exemple de réponse a été enregistré le 12 octobre 2026 ; les réponses en direct changent avec les registres.

Questions fréquentes

Faut-il une clé API pour essayer l’API Fuentio ?

Non. Tous les appels qui lisent des données d’entreprise fonctionnent avec l’essai sans clé, 20 unités par jour. Une clé gratuite donne 100 unités par mois.

Comment envoyer ma clé API ?

Dans l’en-tête X-API-Key, ou en Authorization: Bearer YOUR_API_KEY. Appelez l’API depuis votre serveur, jamais depuis le navigateur.

Quelles erreurs faut-il relancer ?

Seulement rate_limited (après Retry-After), upstream_unavailable et internal_error. Les autres demandent de corriger la requête, la clé ou l’offre, ou sont une vraie réponse (not_found).

Comment savoir combien d’unités il me reste ?

Lisez meta.cost.remaining dans n’importe quelle réponse, ou appelez GET /v1/usage, qui est gratuit.

Sources

• Référence de l’API Fuentio : documentation, le fichier OpenAPI et la documentation interactive
• L’exemple de réponse : RENAULT, enregistré depuis l’API le 12 octobre 2026 (site/data/api-examples dans le dépôt du site)
• Les sources officielles des données : sources