Verificar una empresa por API, con código de prueba

Una consulta te dice lo que contiene el registro. Una verificación lo convierte en una decisión sobre la que actuar y que podrás justificar después: un resultado, sus motivos, las comprobaciones hechas y un código de prueba que cualquiera con quien lo compartas puede comprobar, sin clave. Este tutorial muestra la llamada, dos respuestas reales (una francesa y una española), cómo traducir los resultados en decisiones dentro de tu proceso de alta y cómo funcionan los códigos de prueba.

Lo que vas a aprender

Cómo llamar a POST /v1/verifications y cuánto cuesta
Cómo leer el resultado, los motivos, las comprobaciones y las señales
Por qué la misma llamada responde «verified» para una empresa francesa y «partial» para una española
Cómo convertir los resultados en decisiones de alta
Cómo funcionan los códigos de prueba y quién ve qué

La llamada

Envía el país y el identificador oficial. Añade tu propia reference (un número de expediente o de cliente, hasta 200 caracteres) para encontrar la verificación después:

curl -X POST https://api.fuentio.com/v1/verifications \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"country": "ES", "identifier": "V-5581", "reference": "onboarding-0042"}'

En Python:

import httpx

r = httpx.post("https://api.fuentio.com/v1/verifications",
               headers={"X-API-Key": "YOUR_API_KEY"},
               json={"country": "ES", "identifier": "V-5581", "reference": "onboarding-0042"},
               timeout=30)
v = r.json()["data"]
print(v["result"]["outcome"], v["result"]["reasons"], v["proof_code"])

Coste: 5 unidades, o 1 unidad cuando un identificador bien formado no se encuentra; los errores no cuestan nada. En España, el identificador es la hoja del Registro Mercantil (encuéntrala primero por el nombre: consulta cómo encontrar una empresa por su nombre y leer su hoja registral); en Francia, un SIREN o un SIRET.

Una respuesta española real: MERCADONA, «partial»

Grabada desde la API el 12 de octubre de 2026 (algunos campos omitidos):

{
  "proof_code": "FUE-ES-20261012-966W7X",
  "checked_at": "2026-10-12T11:26:45.068984+00:00",
  "identifier": { "scheme": "ES_RM_HOJA", "value": "V-5581" },
  "result": {
    "outcome": "partial",
    "reasons": ["status_unknown", "events_only_coverage"],
    "summary": "MERCADONA SA (ES, Registro Mercantil sheet (hoja) V-5581): partial, status unknown (no dissolution act; latest act 2026-10-07) per BORME — Boletín Oficial del Registro Mercantil (Sección A), checked 2026-10-12. Proof FUE-ES-20261012-966W7X."
  },
  "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": "unknown", "detail": "Register status: unknown." },
    { "check": "address_present", "result": "pass", "detail": "Registered address published." },
    { "check": "fresh", "result": "pass", "detail": "Checked against the source within its refresh window." }
  ],
  "receipt": {
    "request_id": "req_BzRsH1XiDMLqTP1M",
    "served_at": "2026-10-12T11:26:45.068984+00:00",
    "data_sha256": "62059589322f32ee16a355ab813a92024d7900367879eb9c1eed1f7c8b87b95b"
  }
}

«Partial» no es una alerta sobre Mercadona. Refleja la fuente: el BORME publica eventos (los actos inscritos desde el 2 de enero de 2009), no un indicador «activa» actualizado. Sin acto de disolución y con un acto reciente, el estado sigue siendo «desconocido», y el resultado lo dice con honestidad en lugar de adivinar.

Una respuesta francesa real: DANONE, «verified»

La misma llamada para DANONE, SIREN 552032534, grabada el mismo día:

{
  "proof_code": "FUE-FR-20261012-ABAT38",
  "result": {
    "outcome": "verified",
    "reasons": ["company_active"],
    "summary": "DANONE (FR, SIREN 552032534): verified, active per Annuaire des Entreprises (API Recherche d'entreprises), checked 2026-10-12. Proof FUE-FR-20261012-ABAT38."
  }
}

En Francia, el directorio Sirene publica un estado actualizado (activa o cesada), así que la verificación puede confirmar que la empresa está activa.

Cómo leer la respuesta

result.outcome: verified, partial, unverified o insufficient_data.
result.reasons: códigos cortos que explican el resultado (company_active, status_unknown, events_only_coverage…). Guárdalos: es lo primero que lee un revisor.
result.summary: una frase clara (en inglés) que termina con la fuente, la fecha de comprobación y el código de prueba. Se puede mostrar tal cual o pegar en una nota del expediente.
checks: cada comprobación hecha, con pass, fail o unknown y una línea de detalle.
signals: lo que la fuente dice sobre cierre, disolución, extinción y concurso: present, none_found o not_covered. «No cubierto» significa que la fuente no puede responder, nunca «todo correcto».
receipt: el request_id, la hora de la respuesta y una huella SHA-256 de los datos. Permite demostrar después que eso es exactamente lo que se sirvió.

Del resultado a la decisión

Fuentio te da hechos y un resultado; la decisión es tuya. Un punto de partida para un proceso de alta:

Resultado	Tratamiento sugerido
`verified`	Seguir. Guardar el código de prueba con la ficha del cliente o proveedor.
`partial`	Leer los motivos. En España, `status_unknown` con `events_only_coverage` es el caso normal: añade tus propias comprobaciones si el importe lo justifica.
`unverified`	Parar y preguntar. Leer las comprobaciones fallidas: una sociedad cerrada, una ficha inexistente.
`insufficient_data`	Pedir un identificador mejor (la hoja correcta, un SIREN en vez de un nombre).

Decidas lo que decidas, guarda cuatro cosas con la ficha: el proof_code, el outcome, los reasons y la fecha checked_at. Es tu rastro de auditoría. Para la visión de conjunto, consulta un control de alta de proveedores para Francia y España.

Los códigos de prueba: quién ve qué

Cada verificación se guarda con su código de prueba (FUE- + país + fecha + seis caracteres), conservado 24 meses por defecto.

Tú, como propietario, puedes recuperar la verificación completa cuando quieras con tu clave, por su identificador o por su código de prueba, por 0 unidades:

curl https://api.fuentio.com/v1/verifications/FUE-ES-20261012-966W7X -H "X-API-Key: YOUR_API_KEY"

Cualquiera con quien compartas el código puede comprobarlo públicamente, sin clave y por 0 unidades:

curl https://api.fuentio.com/v1/public/proofs/FUE-ES-20261012-966W7X

o simplemente abrir la página de pruebas y pegar el código. La respuesta pública muestra el resultado, los motivos, la empresa (nombre, identificador, país), las comprobaciones, las fuentes con sus enlaces, la hora de la respuesta, la huella de los datos y si los datos guardados siguen intactos. Nunca muestra quién hizo la comprobación: ni clave, ni correo, ni referencia, ni identificador interno. Así que puedes ponerla en un correo a un banco, un auditor o un cliente.

Las consultas públicas tienen un límite (30 por minuto y dirección), y un código desconocido responde con un 404 limpio.

Pruébalo sin escribir código

La comprobación gratuita tiene un botón «Obtener un código de prueba» bajo cada ficha (3 comprobaciones al día, sin cuenta).
La comprobación de listas gratuita devuelve un código de prueba para cada una de hasta 20 empresas, con un archivo CSV.
En un agente de IA, la misma verificación es la herramienta verify_company: conéctate por MCP.

Cuando estés listo, una clave API gratuita da 100 unidades al mes, es decir, 20 verificaciones. Empieza por los primeros pasos con la API si aún no has hecho una primera llamada. Mira lo que cubrimos.

Las preguntas de los revisores, y dónde está la respuesta

Cuando las verificaciones llegan a un revisor de cumplimiento o de finanzas, vuelven las mismas preguntas. Cada una tiene su campo.

«¿Está actualizado?» La comprobación fresh se supera cuando la respuesta se contrastó con la fuente dentro de su plazo de actualización, y checked_at da la hora exacta. Una verificación es una foto: para una decisión posterior, haz otra.
«¿Qué habéis comprobado exactamente?» La lista checks responde, una línea por comprobación, con su resultado. Muéstrala tal cual en lugar de resumirla.
«¿Por qué no se señaló la disolución?» Lee signals: not_covered significa que la fuente no puede responder, que no es lo mismo que none_found. Tu política debe decir qué hacer en cada caso.
«¿Para qué expediente era?» Para eso está reference. Usa tu propio número de cliente o expediente y encontrarás todas las verificaciones asociadas.
«¿Podéis demostrar que los datos no han cambiado desde entonces?» La prueba pública indica unchanged, calculado a partir de los datos guardados y su huella SHA-256.

Una regla práctica que adoptan muchos equipos: verificar en el alta y de nuevo antes de cualquier pedido grande, anticipo o decisión de crédito, y archivar cada código de prueba nuevo junto a los anteriores.

Límites. Una verificación comprueba lo que dice la fuente oficial ese día; no es una evaluación de solvencia, ni un cribado de sanciones, ni asesoramiento jurídico, y Fuentio nunca emite sellos. En Francia, el estado viene del directorio Sirene y los procedimientos concursales de los anuncios del BODACC desde 2008. En España, el estado es desconocido salvo que un acto del BORME diga otra cosa. Los ejemplos se grabaron el 12 de octubre de 2026.

Preguntas frecuentes

¿Cuánto cuesta una verificación?

5 unidades, o 1 unidad cuando un identificador bien formado no se encuentra. Los errores no cuestan nada. Recuperar una verificación guardada o consultar una prueba pública cuesta 0.

¿Qué significa «partial» para una empresa española?

Que la fuente no puede confirmar un estado activo: el BORME publica actos, no un estado actualizado. Es el resultado normal para muchas sociedades españolas, explicado por los motivos status_unknown y events_only_coverage.

¿Se puede saber quién hizo una verificación a partir de su código?

No. La prueba pública muestra la empresa, el resultado, las comprobaciones y las fuentes, nunca la clave, el correo, la referencia ni el identificador interno de quien la hizo.

¿Cuánto tiempo se guardan las verificaciones?

24 meses por defecto.

Fuentes

Referencia de la API de Fuentio: documentación y el archivo OpenAPI
Los ejemplos: MERCADONA y DANONE, grabados 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