Referencia de la API

BORME API ofrece el Boletín Oficial del Registro Mercantil (BORME) como JSON tipado: eventos extraídos de los anuncios de la sección A del BORME, con cobertura desde el 2 de enero de 2009, a partir de la fuente oficial del BOE. Es una API REST; todas las rutas cuelgan de la URL base https://api.bormeapi.com.

• Autenticación
• Primeros pasos
• Operaciones
• Errores
• Límites y planes

Autenticación

Las solicitudes a operaciones protegidas deben incluir su clave de API en la cabecera X-API-Key:

curl -H "X-API-Key: SU_CLAVE" "https://api.bormeapi.com/v1/events?limit=5"

La clave se obtiene en su cuenta: se accede con un enlace que le enviamos por correo electrónico, y existe un plan gratuito. Una solicitud sin clave, o con una clave desconocida o desactivada, recibe un 401.

Cuatro operaciones no necesitan clave: GET /v1/act-types, GET /v1/sources, GET /v1/health y GET /v1/exports/unsubscribe (el enlace de baja de los correos).

El servidor MCP para asistentes de IA, en https://mcp.bormeapi.com/mcp, responde sin clave con los límites del plan gratuito; con la misma cabecera X-API-Key aplica los de su plan.

Primeros pasos

1. Tipos de acto (sin clave)

La lista de los tipos de acto normalizados, que son los valores que acepta el filtro act_type:

curl "https://api.bormeapi.com/v1/act-types"

2. Buscar eventos

Las constituciones publicadas en Madrid, de la más reciente a la más antigua:

curl -H "X-API-Key: SU_CLAVE" \
  "https://api.bormeapi.com/v1/events?act_type=INCORPORATION&province=MADRID&limit=5"

Otros filtros: date_from y date_to (AAAA-MM-DD), company_name_contains (tres caracteres como mínimo), municipality, capital_min y capital_max. limit admite hasta 200 resultados por página y offset hasta 10.000. Con format=csv la respuesta es una tabla plana.

3. Cronología de una empresa

Cada evento trae el company_slug de su empresa. Con él se pide su cronología; order=desc devuelve primero los eventos más recientes:

curl -H "X-API-Key: SU_CLAVE" \
  "https://api.bormeapi.com/v1/companies/mercadona-sa/events?order=desc&limit=10"

El campo total indica cuántos eventos cubre el periodo de su plan; para paginar, incremente offset en pasos de limit, sin superar 10.000; este límite puede impedir recuperar toda la cronología.

Operaciones

Todas las operaciones públicas de la API. Los parámetros y los esquemas de respuesta de cada una están en la referencia interactiva.

Errores

Toda respuesta de error es un objeto JSON con el campo detail. Casi siempre es una frase en inglés; en tres respuestas de la búsqueda por NIF es un objeto cuyo campo error indica el motivo. Las frases se citan aquí literalmente, tal como las recibirá su código; lo que va entre llaves, como {slug}, se sustituye por el valor de su solicitud.

401 — clave no válida

• invalid or disabled API key — falta la cabecera X-API-Key, o la clave no existe o está desactivada.
• this trial key has expired — get a fresh one at https://bormeapi.com — la clave de prueba ha caducado; obtenga una nueva.
• invalid API key — la clave se revocó mientras se procesaba una operación sobre sus listas, suscripciones o volcados.

403 — el plan no incluye la operación

Cuando una operación exige un plan superior, el mensaje indica el plan mínimo y enlaza a su cuenta. Si contrató la API a través de RapidAPI, la frase termina en cambio con el plan de RapidAPI que necesita.

• company snapshots need the basic tier — https://bormeapi.com/account — fichas de empresa y búsqueda por NIF.
• company lookups need the basic tier — https://bormeapi.com/account — búsqueda por hoja registral.
• person lookups need the basic tier — https://bormeapi.com/account — cargos de una persona.
• brand data needs the basic tier — https://bormeapi.com/account — marcas de una empresa.
• brand search needs the basic tier — https://bormeapi.com/account — búsqueda de marcas.
• batch lookup needs the pro tier — https://bormeapi.com/account — consulta de NIF por lote.
• point-in-time (as_of) needs the pro tier — https://bormeapi.com/account — estado de una empresa en una fecha.
• bulk dumps need the pro tier — https://bormeapi.com/account — volcado completo de empresas.
• network graphs need the pro tier — https://bormeapi.com/account — red de cargos.
• signals need the Risk tier — https://bormeapi.com/account — señales de riesgo.
• risk profiles need the risk tier — https://bormeapi.com/account — perfil de riesgo.
• watchlist limit reached ({limit} on '{tier}' tier) — ha alcanzado el número máximo de listas de vigilancia de su plan.
• subscription limit reached ({limit} on '{tier}' tier) — ha alcanzado el número máximo de suscripciones CSV de su plan.

La cronología de una empresa también responde 403 cuando la empresa tiene eventos pero ninguno cae dentro del historial que cubre su plan; el mensaje indica cuántos hay y entre qué fechas.

404 — no encontrado

• no state for '{slug}' — company may predate coverage or slug is misspelled — no hay ficha para ese slug: la empresa puede ser anterior a la cobertura o el slug está mal escrito.
• no state for '{slug}' — lo mismo, en el perfil de riesgo.
• no events for '{slug}' on or before {as_of} — la empresa no tiene eventos en la fecha pedida ni antes.
• no events on record for company '{slug}' — the slug may be misspelled, or the company predates our 2009 coverage — no hay eventos de esa empresa: el slug puede estar mal escrito o la empresa es anterior a 2009.
• no company on hoja '{hoja}' (parsed from '{input}'). Registry codes are the province abbreviations the Registro Mercantil uses, e.g. GC Las Palmas, M Madrid, B Barcelona. — ninguna empresa en esa hoja registral; el código de registro es la abreviatura de provincia que usa el Registro Mercantil.
• subscription not found — la suscripción no existe o no pertenece a su cuenta.
• no such watchlist on this key — la lista de vigilancia no existe o no pertenece a su cuenta.
• nif_unmapped — valor de detail.error en la búsqueda por NIF: no tenemos ninguna empresa asociada a ese NIF. El BORME no incluye un campo específico para el NIF; la correspondencia se obtiene de fuentes abiertas y, en algunos casos, del texto de sus anuncios, así que lo más probable es una laguna en esa correspondencia, no que la empresa no exista. El NIF queda registrado y conviene repetir la consulta más adelante.

409 — NIF ambiguo

• {nif} is mapped to 2 companies, so we cannot say which one it identifies. Our NIF mapping is cross-referenced from open sources, not printed by BORME, and these two sources disagree. Resolve it with the company name or the Registro Mercantil sheet. — valor de detail.error: nuestra correspondencia asocia el NIF con más de una empresa (el número de empresas varía); detail.candidates lista las candidatas. Decida con la denominación o con la hoja registral.

422 — solicitud no válida

• '{value}' is not a date. Use YYYY-MM-DD, and a day that exists on the calendar. — fecha con formato incorrecto o inexistente.
• as_of must be YYYY-MM-DD and a real calendar day (got '{value}') — lo mismo para as_of.
• '{value}' is not a signal type. Valid: ACCORDION, ADDRESS_CLUSTER, AEAT_DEBTOR, DISTRESS_COMBO, INSOLVENCY_FILED, MASS_EXIT, OWNERSHIP_CHANGE, PHOENIX, PUBLIC_CONTRACT_AWARD — tipo de señal desconocido; la frase enumera los válidos.
• '{value}' is not a hoja registral: expected a registry code and a sheet number, e.g. 'GC 49576', 'M-198300' or 'B123456'. — el valor no tiene la forma de una hoja registral.
• '{nif}' is not a valid NIF/CIF: expected 9 characters (letter+7 digits+control, e.g. A46103834). This is a malformed identifier, not a gap in our coverage — a well-formed NIF we cannot map is reported as unmatched. — el identificador no tiene la forma de un NIF. Si parece un número de hoja registral, la frase lo añade y propone la búsqueda por hoja.
• nif_check_character_failed — valor de detail.error: el carácter de control del NIF no es válido.
• name must not be empty — el nombre de la persona está vacío.
• body must be {"nifs": ["A46103834", ...]} — el cuerpo de la consulta por lote no tiene esa forma.
• valid email required — la suscripción CSV necesita una dirección de correo válida.
• company_slug or name_contains is required — la lista de vigilancia necesita una empresa o un fragmento de denominación.

Cuando un parámetro no cumple su tipo o sus límites (por ejemplo, limit=0), la API responde antes de ejecutar la operación y detail es una lista: cada elemento indica en loc el parámetro y en msg el motivo.

429 — límite alcanzado

• daily quota exceeded ({quota} requests/day on '{tier}' tier) — ha agotado las consultas diarias de su plan.
• one dump per day per owner — try again tomorrow (the snapshot regenerates nightly) — ha alcanzado el límite de un volcado por titular y día (UTC); vuelva a intentarlo al día siguiente.

500, 503 y 504 — errores del servidor

• internal error — error interno (500).
• could not verify the API key right now — this is a temporary problem on our side, not with your key or your request; retry in a few seconds — no se pudo comprobar la clave en ese momento (503); repita la solicitud en unos segundos.
• please retry in a moment — conflicto momentáneo al leer los datos de su cuenta (503); repita la solicitud.
• query took too long and was cancelled — narrow it with a shorter date range (date_from/date_to) or a smaller limit. This is a timeout on our side, not a rejection of your parameters. — la consulta superó el tiempo máximo (504); acote el periodo o reduzca limit.

Límites y planes

Cada plan tiene un número de consultas al día y un periodo de historial de eventos. Al superar la cuota diaria, la API responde 429.

Los precios y lo que incluye cada plan están en la sección de precios.