Primeros pasos con la API de Fuentio: primera llamada, unidades, errores y reintentos

Esta guía te lleva de cero a una integración que funciona con la API REST de Fuentio: una primera consulta de una empresa francesa, la forma de cada respuesta, cómo se cuentan las unidades y cómo gestionar los errores sin saturar la API. Cada ejemplo usa una empresa real y una respuesta real grabada desde la API.

No necesitas nada para empezar: la prueba sin clave da 20 unidades al día. Para ir más allá, una clave gratuita da 100 unidades al mes.

Lo que vas a aprender

• Empezar sin clave y crear una clave gratuita
• Tu primera llamada en curl, Python y JavaScript
• Las tres partes de cada respuesta: data, meta, error
• Cómo se cuentan las unidades y dónde ver las que te quedan
• Qué errores corregir, cuáles reintentar y cuánto esperar

Paso 1: empieza sin clave o crea una clave gratuita

Todas las llamadas que leen datos de empresas funcionan sin clave, con la prueba gratuita: 20 unidades al día por conexión. Suficiente para unas cuantas pruebas.

Para tu aplicación, crea una clave gratuita. Una sola llamada con tu correo (una clave gratuita por persona; la clave se muestra una sola vez, así que guárdala enseguida):

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

También puedes conseguirla en la página de precios. Envía la clave en la cabecera X-API-Key en cada llamada (o como Authorization: Bearer YOUR_API_KEY). Nunca la pongas en el código del navegador: llama a la API desde tu servidor.

Paso 2: tu primera llamada

Consulta RENAULT con su SIREN, el número de 9 cifras de toda empresa francesa:

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

La misma llamada en Python, con 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"])

Y en JavaScript (Node 18 o cualquier entorno con 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);

En Francia, el identificador puede ser un SIREN, un SIRET (14 cifras), un número de IVA francés o un LEI; los espacios, puntos y guiones se ignoran. En España, es la hoja del Registro Mercantil (por ejemplo V-5581) o un LEI. Una sociedad española no se consulta por su número fiscal: busca primero por nombre (consulta cómo encontrar una empresa por su nombre y leer su hoja registral).

Paso 3: lee la respuesta

Cada respuesta tiene las mismas tres partes.

• data: la ficha de la empresa (o una lista, en una búsqueda). Los valores conservan la redacción del registro, con códigos normalizados y etiquetas en inglés al lado.
• meta: de dónde viene la respuesta y cuánto ha costado: source, fetched_at (cuándo leímos la fuente), last_verified_at (cuándo la comprobamos por última vez), stale (true si la fuente estaba caída y recibes nuestra última copia), el coste en unidades y un request_id.
• error: null, o un objeto con un code, un message y un hint que te dice el siguiente paso.

Esta es una parte de la respuesta real para RENAULT, grabada desde la API el 12 de octubre de 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
}

Dos costumbres que luego se agradecen:

1. Guarda meta.source y meta.last_verified_at con cada valor que conserves. Cuando alguien pregunte «¿de dónde sale esto?», tendrás la respuesta.
2. Conserva el request_id. Si una respuesta te parece errónea, cítalo al escribirnos o comunícala con POST /v1/issues.

Paso 4: entiende las unidades

Cada llamada cuesta un número fijo de unidades. Las más habituales:

Reglas que conviene conocer:

• Los errores no cuestan nada, salvo not_found con un identificador bien formado (1 unidad): es una respuesta real del registro.
• Las unidades se renuevan cada mes (cada día en la prueba sin clave). Si superas la cuota recibes quota_exceeded, nunca un cargo extra.
• Cada respuesta incluye meta.cost: las unidades de la llamada (units) y las que te quedan (remaining). La cabecera de respuesta X-Request-ID repite el request_id.
• GET /v1/usage (gratis) devuelve tu plan, las unidades usadas en el periodo y las que quedan. La página de cuenta muestra lo mismo en el navegador.

Paso 5: gestiona los errores y reintenta solo lo que merece la pena

La lista de códigos de error es cerrada, así que puedes tratar cada caso. Agrúpalos según lo que debe hacer tu código:

Una pequeña función de reintento en Python que sigue esas reglas:

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)

Solo reintenta los tres errores temporales, respeta Retry-After cuando la API lo envía y espacia los intentos en los demás casos. Todo lo demás vuelve directamente a tu código, donde el hint te dice qué hacer.

Paso 6: qué construir después

• Una decisión, no solo datos: POST /v1/verifications devuelve un resultado con sus motivos y un código de prueba que cualquiera puede comprobar. Consulta verificar una empresa y obtener un código de prueba por API.
• Concurso e IVA: consulta comprobar concurso e IVA por API.
• Una lista de empresas: prueba primero la comprobación de listas gratuita, con hasta 20 empresas a la vez.
• Un agente de IA: los mismos datos y unidades están disponibles por MCP: conecta tu agente.

La referencia completa está en la documentación, con el archivo OpenAPI y la documentación interactiva. Mira lo que cubrimos país por país.

Recorrer las páginas de una búsqueda

Una búsqueda devuelve una página cada vez y te dice dónde estás. La meta de la búsqueda grabada de MERCADONA muestra los campos que hay que leer: page, page_size (10 por defecto), total (cuántas empresas coinciden) y next_page, que es null en la última página. Cada página cuesta 2 unidades, así que pide solo las que necesites: si el primer resultado tiene un match.score alto y el municipio correcto, para ahí. Cuando necesites todos los resultados, repite mientras next_page tenga valor, con un límite de páginas para que un nombre muy común no se coma tus unidades del mes.

Dos costumbres más con las búsquedas. Afínalas con postal_code o locality siempre que los tengas: menos páginas y mejor orden. Y nunca tomes el primer resultado por la empresa que buscabas: una búsqueda ordena nombres, y su meta.uncertainty lo recuerda. Cuando la decisión importa, confírmalo con un identificador o llama a POST /v1/resolve, que explica por qué un candidato está vinculado, es posible o se descarta.

Límites. Francia: todas las empresas del directorio público Sirene, leídas en el Annuaire des Entreprises del Estado francés; anuncios de procedimientos concursales del BODACC desde 2008. España: las sociedades con un acto publicado en el BORME desde el 2 de enero de 2009, solo eventos, con un estado desconocido salvo que un acto diga otra cosa; no hay consulta por número fiscal. Nunca se devuelve el nombre de una persona. La respuesta de ejemplo se grabó el 12 de octubre de 2026; las respuestas en directo cambian con los registros.

Preguntas frecuentes

¿Necesito una clave para probar la API de Fuentio?

No. Todas las llamadas que leen datos de empresas funcionan con la prueba sin clave, 20 unidades al día. Una clave gratuita da 100 unidades al mes.

¿Cómo envío mi clave API?

En la cabecera X-API-Key, o como Authorization: Bearer YOUR_API_KEY. Llama a la API desde tu servidor, nunca desde el navegador.

¿Qué errores debo reintentar?

Solo rate_limited (después de Retry-After), upstream_unavailable e internal_error. Los demás piden corregir la petición, la clave o el plan, o son una respuesta real (not_found).

¿Cómo sé cuántas unidades me quedan?

Lee meta.cost.remaining en cualquier respuesta o llama a GET /v1/usage, que es gratis.

Fuentes

• Referencia de la API de Fuentio: documentación, el archivo OpenAPI y la documentación interactiva
• La respuesta de ejemplo: RENAULT, grabada desde la API el 12 de octubre de 2026 (site/data/api-examples en el repositorio del sitio web)
• Las fuentes oficiales de los datos: fuentes