De la consulta a la decisión de verificación: un recorrido por la API de Fuentio

Un recorrido real por la API de Fuentio: cobertura, búsqueda por nombre, consulta, resultados de verificación, códigos de prueba y recibos, con Python probado.

· Actualizado el 17 de octubre de 2026 · Por el equipo de Fuentio · 7 min de lectura

Imagen para compartir: «De la consulta a la decisión de verificación: un recorrido por la API de Fuentio» sobre el fondo de papel de Fuentio, con la etiqueta Tutorial.

Este recorrido sigue una comprobación de empresa de principio a fin con la API REST de Fuentio: encontrar la empresa, consultarla, verificarla, guardar la prueba y convertir el resultado en una decisión en tu propio código. Cada respuesta que se muestra es real, grabada de la API en producción y recortada, y el Python del final se ejecutó contra la API antes de publicar este artículo.

Lo que vas a aprender

  • Cómo consultar la cobertura, buscar por nombre y consultar una empresa por su número
  • Qué devuelve una verificación: resultado, motivos, comprobaciones, señales y código de prueba
  • Cómo recuperar el resultado después, como página de prueba o como recibo
  • Cómo traducir los resultados en aprobar, revisar y rechazar, con Python que funciona

En resumen: busca por nombre si no tienes el número oficial (2 unidades), consulta la empresa por su número (1 unidad) y después llama a POST /v1/verifications (5 unidades) para obtener un resultado con sus motivos y un código de prueba. Asocia verified, partial y unverified a tus propias acciones y guarda el código de prueba con tu decisión. No hace falta clave para probarlo: la prueba sin clave da 20 unidades al día.

Antes de empezar

La dirección base es https://api.fuentio.com. Todas las respuestas tienen el mismo sobre: data, meta (fuente, frescura, unidades cobradas) y error. Sin clave usas la prueba sin clave, limitada a 20 unidades al día y 1 petición por segundo; con clave, envíala como X-API-Key o como Authorization: Bearer. Una clave gratuita da 100 unidades al mes. Si es tu primera llamada, la guía rápida de la API explica las unidades, los errores y los reintentos.

Paso 1: comprobar qué está cubierto

GET /v1/countries es gratuito e indica qué países, tipos de identificador y fuentes están disponibles. Para el Reino Unido responde, entre otras cosas, que la cobertura es el registro de Companies House, con la ficha actual de cada sociedad, disueltas incluidas, sus procedimientos de insolvencia, sus cargas y sus últimos depósitos, y sin administradores ni otras personas. Francia y España también están cubiertas; la página de cobertura muestra lo mismo de forma legible.

Paso 2: encontrar la empresa por su nombre

Si solo tienes un nombre, busca primero. Una búsqueda real de «mercadona» en España, grabada el 12 de octubre de 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}
}

Una sola candidata, idéntica tras normalizar. Con un nombre común obtendrías muchas: la misma búsqueda de «telefonica» devolvió 251. Elige la candidata por su identificador, nunca solo por la puntuación más alta; cómo encontrar una sociedad española por su nombre y leer su hoja explica el proceso completo.

Paso 3: consultar la empresa

Con el número oficial, una consulta devuelve la ficha. Una respuesta real para DANONE, SIREN 552032534, grabada el 12 de octubre de 2026 y recortada:

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"}
}

Cada valor conserva la redacción del registro (original_label) junto a un valor normalizado, y la procedencia dice de dónde sale el dato y cuándo se comprobó por última vez. Una consulta cuesta 1 unidad. Te dice lo que indica la ficha; no te da una decisión.

Paso 4: verificar la empresa

Una verificación lee la ficha, ejecuta una serie fija de comprobaciones y devuelve un resultado. Una verificación real de TESCO PLC, hecha el 16 de octubre de 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}}
}

Para la verificación de una empresa, el resultado es uno de tres: verified, partial o unverified. Los motivos dicen por qué con códigos legibles por una máquina, las comprobaciones muestran cada paso y las señales informan de lo encontrado sobre cese, disolución e insolvencia.

Cómo es un resultado «unverified»

La misma llamada para APPLETREE FARM CRESSING LIMITED (número 12401266), el mismo día:

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

La sociedad sigue inscrita, pero tiene abierta una administración, así que no queda verificada. Por qué importa esta diferencia: una empresa activa no siempre es una empresa segura.

Y uno «partial»

Para MERCADONA SA, grabada el 12 de octubre de 2026, el resultado fue partial, con los motivos status_unknown y events_only_coverage: el BORME publica actos, y ninguno indica el estado actual de la sociedad. La comprobación status_active devolvió unknown, no fail.

Paso 5: guardar y recuperar la prueba

Cada verificación tiene un código de prueba. Guárdalo con tu decisión; puedes recuperar el resultado cuando quieras, sin coste:

  • GET /v1/verifications/{id or proof code} devuelve la verificación guardada.
  • GET /v1/public/proofs/{proof_code} devuelve la versión pública, sin clave, y cualquiera puede abrirla en nuestra página de prueba: FUE-GB-20261016-5QBDT2.
  • GET /v1/receipts/{request_id} devuelve el recibo de una respuesta: la copia guardada, con su huella y su referencia de instantánea.

Los códigos de prueba se conservan 24 meses. Qué debe contener un expediente completo, y por qué un recibo no es un documento certificado, se explica en qué debe contener el expediente verificable de una comprobación.

Paso 6: convertir el resultado en una decisión

La API informa; tu código decide. Este Python solo usa la biblioteca estándar y asocia los resultados a acciones. Lo inesperado va a revisión:

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: el resultado, los motivos y un código de prueba (5 unidades)."""
    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:  # las respuestas 4xx y 5xx tienen el mismo cuerpo {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"))

Ejecutado sin clave el 16 de octubre de 2026, mostró:

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

Esa ejecución generó su propio código de prueba, que cualquiera puede abrir: FUE-GB-20261016-VY43F6.

Gestionar los errores

Los errores salen de una lista cerrada, cada uno con una pista. Los primeros que debes tratar:

  • invalid_identifier (400): el número está mal formado; pide al usuario que lo corrija.
  • not_found (404): número válido, sin ficha. Cuesta 1 unidad.
  • rate_limited (429): demasiadas peticiones por segundo; espera lo que indique Retry-After.
  • quota_exceeded (402): unidades agotadas. La prueba sin clave se reinicia al día siguiente (UTC).
  • upstream_unavailable (503): la fuente oficial no responde; reintenta más tarde.

Para más opciones de verificación, como enviar tu propia reference con la petición, consulta cómo verificar una empresa y obtener un código de prueba.

Cuánto cuesta y cómo pagar

Una búsqueda cuesta 2 unidades, una consulta 1 y una verificación 5; los recibos, las verificaciones guardadas y la cobertura son gratuitos. Cuando la prueba y la clave gratuita se quedan cortas, los planes empiezan con Starter a 49 € al mes por 2.000 unidades. Pagas con tarjeta desde la página de precios (cómo pagar Fuentio: pago seguro con Creem), y la clave de pago se envía por correo en cuanto se confirma el pago. Los precios no incluyen el IVA y no se cobra nada adicional: al llegar al límite, la API responde quota_exceeded. Todos los planes están en la página de precios.

Límites

Preguntas frecuentes

¿Necesito una clave API para seguir este recorrido?

No. La prueba sin clave da 20 unidades al día, suficiente para una búsqueda, una consulta y dos verificaciones. Una clave gratuita da 100 unidades al mes.

¿Qué diferencia hay entre una consulta y una verificación?

Una consulta devuelve la ficha de la empresa (1 unidad). Una verificación ejecuta comprobaciones sobre ella y devuelve un resultado, motivos y un código de prueba (5 unidades).

¿Cómo recupero después el resultado de una verificación?

Llama a GET /v1/verifications/{id or proof code}, sin coste, o abre el código de prueba en fuentio.com/es/proof/. Los códigos se conservan 24 meses.

¿Qué resultado debe bloquear el alta?

Depende de tu política. Una opción habitual: aprobar verified, revisar partial, rechazar o escalar unverified y revisar todo lo demás.

Fuentes

← Todos los artículos · Canal RSS