Referencia · versión 1

Todo el dinero público español, en JSON

Una API REST sobre las 28 fuentes oficiales que vigila Boletín Claro: subvenciones, licitaciones y boletines del Estado, las comunidades autónomas y Europa. Se busca en lenguaje natural, no por palabras clave.

Empieza aquí

No hace falta clave para probarla. Pega esto en tu terminal:

curl -H "X-API-Key: $BOLETINCLARO_API_KEY" "https://boletinclaro.es/v1/oportunidades?consulta=digitalizaci%C3%B3n%20para%20una%20pyme%20industrial&limite=3"

Y esto es lo que responde, sin recortar nada salvo la lista:

{
  "consulta": "digitalización para una pyme industrial",
  "total": 3,
  "resultados": [
    {
      "titulo": "(CHD) Cheque Digitalización 2026",
      "fuente": "BDNS",
      "identificador": "857234",
      "tipo": "subvencion",
      "fecha_publicacion": "2026-09-01",
      "fecha_fin": "2026-10-15",
      "importe": 2000000,
      "moneda": "EUR",
      "ambito": "local",
      "ubicacion": ["Aranda de Duero, Burgos, Castilla y León"],
      "codigos_ubicacion": ["09018", "0947", "09"],
      "enlace": "https://www.infosubvenciones.es/bdnstrans/GE/es/convocatoria/857234",
      "ficha": "https://boletinclaro.es/subvencion/857234"
    }
  ]
}

Si prefieres no leer nada más, la API se describe a sí misma: /v1/openapi.json es su especificación OpenAPI 3.1, con todos los parámetros, todas las respuestas y ejemplos reales. Impórtala en Postman o en Insomnia y ya puedes llamar.

Y si lo que quieres es hojearla: /v1/referencia es esa misma especificación dibujada, con los esquemas desplegables endpoint por endpoint. Esta página cuenta el porqué de las cosas; aquella enseña la forma exacta de cada respuesta.

Los seis endpoints

• /oportunidades — el dinero abierto
• /boletines — las gacetas oficiales
• /licitaciones — abiertas por CPV
• /empresas — buscar por nombre
• /empresas/{nif} — perfil de dinero público
• /codigos — CPV, CNAE e IAE

curl -H "X-API-Key: $BOLETINCLARO_API_KEY" "https://boletinclaro.es/v1/oportunidades?consulta=obra%20p%C3%BAblica%20de%20alumbrado&tipo=licitaciones&limite=5"

curl -H "X-API-Key: $BOLETINCLARO_API_KEY" "https://boletinclaro.es/v1/boletines?consulta=oposiciones%20de%20auxiliar%20administrativo&zona=Bizkaia"

curl -H "X-API-Key: $BOLETINCLARO_API_KEY" "https://boletinclaro.es/v1/licitaciones?cpv=72000000,48000000&limite=20"

curl -H "X-API-Key: $BOLETINCLARO_API_KEY" "https://boletinclaro.es/v1/empresas?consulta=telefonica"

curl -H "X-API-Key: $BOLETINCLARO_API_KEY" "https://boletinclaro.es/v1/empresas/A78053147"

{
  "nif": "A78053147",
  "nombre": "TELEFONICA SOLUCIONES DE INFORMATICA Y COMUNICACIONES",
  "dinero_publico_total": 3282678796.43,
  "subvenciones": { "numero": 2, "importe": 106587.48,
                    "primera": "2022-01-01", "ultima": "2023-01-01" },
  "contratos":    { "numero": 4806, "importe": 3282572208.95 },
  "organismos_principales": [ { "organismo": "…", "numero": 12, "importe": 4200000 } ],
  "importes_por_anio":      [ { "anio": 2025, "numero": 340, "importe": 219000000 } ],
  "ficha": "https://boletinclaro.es/empresa/A78053147"
}

curl -H "X-API-Key: $BOLETINCLARO_API_KEY" "https://boletinclaro.es/v1/codigos?consulta=limpieza%20de%20edificios&tipos=cpv&limite=5"

Consultas largas en JSON

/oportunidades, /boletines y /codigos aceptan también POST de solo lectura. Usa esta forma para consultas largas o con muchos caracteres acentuados: un proxy puede responder 414 a una URL larga antes de que llegue a la API. El cuerpo admite hasta 32 KiB; la consulta se recorta a 2000 caracteres. Los mismos buscadores atienden GET y POST.

curl -H "X-API-Key: $BOLETINCLARO_API_KEY" -X POST "https://boletinclaro.es/v1/oportunidades" \
  -H "Content-Type: application/json" \
  -d '{"consulta":"ayudas para digitalización industrial","zona":"Andalucía","limite":3}'

En JSON, fuentes y tipos son listas de textos y incluir_cerradas es booleano. No mezcles cuerpo y parámetros en la URL. Los parámetros desconocidos, repetidos o no admitidos se rechazan con 400; cursor y fecha_desde no están disponibles.

Autenticación y créditos compartidos

Todas las rutas de datos requieren una clave, también en Gratis. Créala en Ajustes → API. La documentación, OpenAPI y el catálogo de errores siguen públicos.

curl -H "X-API-Key: $BOLETINCLARO_API_KEY" "https://boletinclaro.es/v1/empresas/A78053147"

También se acepta Authorization: Bearer bc_live_…. El secreto se muestra una vez y se revoca desde Ajustes.

Trial y Oposiciones tienen el cupo de lectura Gratis. Cambiar de plan o terminar el Trial no reinicia el consumo.

El saldo pertenece al workspace: en Gratis y Pro lo comparten todas sus claves, usuarios, clientes MCP y consultas de datos en la web. En Mega la API tiene un saldo propio, independiente del de la aplicación (web y conector MCP): lo comparten todas las claves y no se descuenta de la aplicación, que tiene el suyo. Mega añade, en cada saldo, un tope de 1.500 créditos al día (BC-4005, cabeceras X-Quota-Daily-*) y de 500 llamadas de cinco créditos al mes (BC-4007, cabeceras X-Heavy-*). Gratis admite además cinco llamadas mensuales a /empresas/{nif} o perfil_empresa, aunque se repita el NIF. El mes se renueva el día 1 a las 00:00 UTC; el minuto también es natural UTC.

X-RateLimit-Limit: 15000
X-RateLimit-Remaining: 14995
X-RateLimit-Reset: 2026-10-01T00:00:00Z
X-Quota-Limit: 15000
X-Quota-Remaining: 14995
X-Quota-Used: 5
X-Quota-Cost: 5
X-Quota-Unit: credits
X-Quota-Period: month
X-Quota-Scope: workspace
X-Quota-Admission-ID: abc123example
X-RateLimit-Minute-Limit: 300
X-RateLimit-Minute-Remaining: 299
X-Credits-Minute-Limit: 1500
X-Credits-Minute-Remaining: 1495

X-Quota-* y sus alias mensuales X-RateLimit-* expresan créditos. X-RateLimit-Minute-* expresa llamadas, y X-Credits-Minute-*, créditos. En Gratis, X-Profiles-Limit y X-Profiles-Remaining informan del tope adicional.

X-Quota-Admission-ID identifica el registro confirmado junto con el débito. En Ajustes → API puedes consultar y conciliar el registro mensual compartido con MCP y web: actor, operación, coste y saldo antes/después. No guarda claves en claro ni consultas. Se conserva 400 días desde el cierre del mes; el saldo anterior al inicio de la auditoría se muestra aparte.

El saldo se reserva atómicamente antes de consultar datos. Una admisión consume incluso con caché o error posterior; un rechazo no descuenta. Los lotes MCP se reservan completos. Cada reintento es otra admisión. Si el contador falla, se devuelve 503 sin consultar datos. Las solicitudes sin clave reciben 401; sin saldo o con una ráfaga excesiva: 429 con Retry-After. La documentación no consume. La revocación puede tardar hasta 60 segundos por la caché; la reserva lee el plan actual en cada llamada.

Errores

Todos los errores siguen el estándar RFC 9457, con Content-Type: application/problem+json, y llevan un código estable que identifica exactamente uno de los casos documentados. El campo que debes mirar en tu código es codigo, o el type que lo contiene: no cambian aunque reescribamos el texto.

{
  "type": "https://boletinclaro.es/v1/errores/BC-1001",
  "codigo": "BC-1001",
  "title": "Consulta no válida",
  "status": 400,
  "detail": "El parámetro «consulta» debe tener entre 2 y 2000 caracteres."
}

El primer dígito dice de quién es el problema: BC-1xxx la petición está mal formada · BC-2xxx la clave o el plan · BC-3xxx no hay nada ahí · BC-4xxx vas demasiado rápido · BC-5xxx se ha roto de nuestro lado.

Cada type es una URL que se puede abrir, y cada una explica su error: por qué ocurre, cómo se arregla, y si merece la pena reintentarlo y cuándo. El catálogo entero está en /v1/errores, y responde también en JSON con Accept: application/json.

Los errores que se pueden reintentar traen la cabecera Retry-After con los segundos que hay que esperar. Permite distinguir la ráfaga de los máximos mensuales sin leer el código: BC-4001 y BC-4002 se despejan en menos de un minuto, y BC-4003 y BC-4004, el saldo y el máximo de perfiles, el día 1 a las 00:00 UTC.

Cómo identificar una entrada

Guarda los tres campos juntos: fuente + fecha_publicacion + identificador. Esa tripleta es la clave.

El identificador es la referencia que le da la fuente oficial —el número de anuncio del BOE, el expediente de la PLACSP, el de publicación de TED—, así que es estable en el único sitio que no controlamos nosotros. Pero su calidad depende del boletín:

BOE    BOE-B-2026-23881      único a nivel global
BOJA   boja-2026-113-64      lleva año y número
BOCM   BOCM-20260706-74      lleva la fecha
BON    2026.154.46           lleva año y número
BOB    II-3954_cas.pdf       nombre de fichero, secuencia anual
BOPV   1459                  un número pelado
BORM   BORM-2827             una secuencia

Sobre los datos

Importes

importe viene en la moneda de moneda, casi siempre euros, como número. Cuando la fuente no publica importe el campo no aparece, en vez de venir a cero: así una suma tuya no se queda corta en silencio. Un cero que sí viene es un cero de verdad.

Fechas

Las fechas de las entradas usan AAAA-MM-DD; las marcas de caché y de cuota usan RFC 3339 con zona horaria. fecha_publicacion es cuándo salió en el boletín, fecha_fin el cierre del plazo — y es lo que usamos para decidir si algo sigue abierto. Solo una parte de las convocatorias publica plazo: si no viene, no es que no lo tenga, es que la fuente no lo da.

Geografía

ambito vale nacional o local. Cuando es local vienen las dos formas, para dos usos distintos: ubicacion trae el nombre completo del lugar («Aranda de Duero, Burgos, Castilla y León») para leerlo, y codigos_ubicacion la jerarquía del INE de lo más concreto a lo más general —municipio, provincia, comunidad— para cruzarla con tus datos.

En ubicacion hay una entrada por lugar, no una por nivel: si una convocatoria cubre dos municipios verás dos, y si cubre uno verás uno, no tres repitiendo la misma jerarquía.

Para filtrar, zona acepta el nombre de una comunidad, una provincia o un municipio, y aplica la jerarquía: pedir Andalucía incluye Sevilla y sus municipios. Lo de ámbito nacional entra siempre, porque también aplica a esa zona.

Cuántos resultados

total es cuántas filas trae esta respuesta, no cuántas hay en total. No hay paginación ni sincronización incremental: los resultados son una selección y no permiten certificar una extracción completa. El techo son 50. Para abarcar más, acota mejor: por tipo, por fuentes o por CPV.

En /licitaciones, busqueda informa del límite de candidatos, candidatos leídos, grupos consultados y truncada. Se consultan como máximo 600 valores CPV expandidos en 20 grupos, hasta 120 candidatos por grupo, y se conservan los 120 más recientes antes de descartar cerradas. Una selección mayor da 400 para que la acotes. Los códigos de seis o siete dígitos se completan con ceros a la izquierda: usa 72000000 para informática. La jerarquía no garantiza una exportación exhaustiva.

Preguntas que nos hacen

Empezar

Crea una cuenta Gratis y emite tu clave para usar los 100 créditos mensuales, que comparten la API, el MCP y la web.