Llamar a un registro de empresas es la parte fácil. Lo difícil es todo lo que rodea a la llamada: saber de qué empresa hablas, decir cuánta seguridad tienes, indicar de dónde sale cada dato, fallar de una forma que el cliente pueda aprovechar y no presentar nunca la copia de ayer como la verdad de hoy. Esta guía repasa las decisiones que un equipo técnico tiene que acertar, tanto si construye la API como si evalúa una.
Lo que vas a aprender
- Por qué las búsquedas deben partir del identificador, y cómo validarlo
- Cómo gestionar el emparejamiento por nombre sin elegir en silencio la empresa equivocada
- Por qué una lista cerrada de resultados es mejor que un verdadero o falso
- Cómo atribuir fuentes, gestionar errores, usar caché sin engañar y decir «no lo sabemos»
En resumen: identifica las empresas por su número oficial, nunca solo por el nombre; devuelve un resultado de una lista fija, con motivos legibles por una máquina; pon la fuente, la licencia y la fecha de comprobación en cada respuesta; usa una lista cerrada de códigos de error que indiquen el siguiente paso; y usa caché con una regla de frescura explícita, para que una copia antigua se marque como tal.
La búsqueda: empezar por el identificador
Un registro está indexado por un número oficial, y tu API también debería estarlo. Valida el formato antes de gastar una llamada. Un SIREN francés tiene 9 cifras y un dígito de control; un SIRET tiene 14. Un número de sociedad británico tiene 8 caracteres (00445790, SC123456). Una sociedad española se encuentra por su hoja del Registro Mercantil (V-5581).
Tres casos merecen su propia respuesta en lugar de un 404 genérico:
- Inválido: el número no supera el control de formato o el dígito de control. No se ha buscado nada.
- Identificador ambiguo: una misma cadena encaja con varios tipos de identificador en un país. Pide al cliente que lo precise, por ejemplo con un parámetro
id_scheme. - No encontrado: el número es válido y está dentro de la cobertura, pero el registro no tiene ficha. Es una respuesta real y, en Francia, no prueba que la empresa nunca existiera, porque algunas unidades se han negado a la difusión pública.
El emparejamiento: un nombre nunca decide solo
La mayoría de los formularios empiezan por un nombre. Los nombres se repiten, cambian y se abrevian, así que una búsqueda por nombre debe devolver candidatas, cada una con una puntuación y sus motivos, nunca una «mejor coincidencia» silenciosa. Cuando encajan varias empresas, la respuesta honesta es «ambigua», con las candidatas, para que una persona o el sistema que llama elija una por su número oficial.
Explica cada emparejamiento con términos que el cliente pueda registrar: mismo identificador, mismo código postal, nombre idéntico tras quitar la forma jurídica. Un emparejamiento sin motivos no se puede revisar.
Los resultados: nada de booleanos
"verified": true esconde todo lo importante. ¿La empresa está activa o solo figura? ¿Respondía la fuente? ¿Está siquiera cubierto el país? Una lista cerrada de resultados, cada uno con un significado preciso, permite escribir reglas fiables. Fuentio usa nueve, y documenta también lo que cada uno no significa:
| Resultado | Lo que dice |
|---|---|
verified | La fuente oficial indicada afirma lo que se devuelve, dentro de la regla de frescura |
partial | Parte de la respuesta se apoya en la fuente; los motivos dicen qué falta |
unverified | La fuente respondió pero no lo confirma (por ejemplo, la empresa está cesada) |
status_unknown | La empresa está en la fuente, que no indica ningún estado actual |
not_found | Identificador válido, dentro de la cobertura, sin ficha |
not_covered | El país, el tipo de identificador, el dato o el periodo no están cubiertos |
ambiguous | Varias empresas podrían coincidir |
stale | Una copia guardada más antigua que la regla, porque no se pudo refrescar la fuente |
source_unavailable | La fuente no respondió y no hay nada utilizable |
Cuando se aplican varios, define cuál prevalece. Fuentio los aplica en un orden fijo, de source_unavailable a verified, para devolver el más prudente.
Cada resultado necesita motivos legibles por una máquina (company_active, company_inactive, status_unknown, insolvency_administration…) y, a ser posible, el detalle de las comprobaciones. Esta es la lista de comprobaciones de una verificación real de TESCO PLC, grabada el 16 de octubre de 2026:
"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": "pass", "detail": "Register status: active."},
{"check": "address_present", "result": "pass", "detail": "Registered address published."},
{"check": "fresh", "result": "pass", "detail": "Checked against the source within its refresh window."}
]
La fuente en cada respuesta
Cada respuesta debe nombrar su fuente, su licencia y cuándo se leyó, no solo en la documentación sino en la propia respuesta. Los registros abiertos imponen una atribución: las condiciones de reutilización del BOE piden citar la fuente; la Licence Ouverte francesa pide citar la fuente y la fecha de actualización; los datos de Companies House se publican bajo la Open Government Licence v3.0, que exige su propia mención. Más en la procedencia en cada respuesta.
Distingue tres fechas que a menudo se confunden: cuándo publicó la fuente el dato, cuándo lo obtuviste y cuándo lo comprobaste por última vez contra la fuente.
Errores que el cliente pueda aprovechar
Una lista cerrada de códigos de error, cada uno con un estado HTTP y una pista, convierte los fallos en decisiones. Algunos que importan en la práctica:
invalid_identifier(400): corregir la entrada; reintentar no sirve.not_found(404): una respuesta real sobre la empresa, no un fallo.rate_limited(429): esperar lo que indiqueRetry-After.quota_exceeded(402): se han agotado las unidades del cliente.upstream_unavailable(503): la fuente oficial no responde; reintentar más tarde.
Haz también previsible el cuerpo del error. Uno real, de la prueba sin clave de Fuentio cuando se agotan las unidades del día:
{"data": null, "meta": {"request_id": "req_IeGVSzl1UrGq9C6C"},
"error": {"code": "quota_exceeded", "message": "Quota used up: 20 of 20 units today.",
"hint": "The keyless trial starts again tomorrow (UTC). For more now, get a free key (100 units a month) with POST /v1/keys."}}
Nuestra guía rápida explica los reintentos con más detalle: primera llamada, unidades, errores y reintentos.
Usar caché sin engañar
Los registros cambian despacio y a veces responden despacio, así que usarás caché. La regla es decirlo. Da a cada fuente una ventana de frescura, devuelve retrieved_at y last_verified_at, marca las respuestas servidas desde la caché y, cuando la fuente no esté disponible, devuelve la copia guardada como stale y no como actual. Deja que el cliente pida datos más frescos cuando los necesite (Fuentio acepta un max_age en segundos).
Guarda una instantánea de lo que serviste, con una huella, para poder demostrar después cuál fue la respuesta. Es la idea de los recibos y los códigos de prueba.
Saber decir «no lo sabemos»
La información incompleta es normal, y el trabajo de la API es hacerla visible:
- España: el BORME publica actos, no un estado. Una sociedad sin actos sobre su estado desde 2009 no tiene estado indicado, así que el resultado honesto es
status_unknownopartial, nunca «activa». - Francia: «cessée» en Sirene es una unidad cerrada, no la prueba de una disolución jurídica. Di «cesada», no «disuelta».
- Reino Unido: las cifras solo salen de las cuentas presentadas por vía electrónica, y las sociedades pequeñas rara vez presentan su cifra de negocio. Un campo vacío significa «no presentado», no «cero».
Datos personales y texto no fiable
Las fichas de empresas contienen personas: administradores, socios, autónomos. Decide pronto lo que nunca vas a servir y elimínalo al ingerir los datos, no al mostrarlos. Y trata cada campo de texto copiado de un registro como un dato, nunca como una instrucción, sobre todo si tus respuestas las leen agentes de IA.
Límites
Esta guía describe decisiones de diseño, no obligaciones legales. Una API de verificación de empresas responde a lo que indican los registros oficiales; no es un KYB completo, ni una comprobación de quién es el dueño de la empresa, ni un cribado de sanciones, ni un análisis de crédito. La cobertura, los nombres de campo y los resultados varían entre proveedores: consulta la documentación del tuyo. Fuentio cubre Francia, España y el Reino Unido; consulta la página de cobertura.
Preguntas frecuentes
¿Una API de verificación de empresas debe devolver verdadero o falso?
No. Un booleano no distingue «cesada», «sin cobertura», «fuente caída» y «estado sin indicar». Devuelve un resultado de una lista cerrada, con sus motivos.
¿Cómo debe tratar una API una empresa que no encuentra?
Distinguiendo un identificador inválido, un identificador válido fuera de la cobertura y un identificador válido sin ficha. Cada uno lleva a un siguiente paso distinto.
¿Cuánto tiempo pueden guardarse en caché los datos de empresas?
Lo que permitan el ritmo de actualización de la fuente y tu uso, siempre que la respuesta indique cuándo se comprobó por última vez y se marque como antigua cuando supere la regla.
¿Hay que citar la fuente en las respuestas de la API?
Las licencias de los registros abiertos suelen exigirlo, y permite a tus usuarios demostrar de dónde sale un dato. Inclúyela en cada respuesta, no solo en la documentación.
Fuentes
- Resultados de Fuentio, significado y límites: api.fuentio.com/docs/outcomes
- Referencia de errores de Fuentio: api.fuentio.com/docs/errors
- Condiciones de reutilización del BOE: boe.es
- Open Government Licence v3.0: nationalarchives.gov.uk
- Companies House Public Data API: developer.company-information.service.gov.uk
