Boletín Claro Referencia API

openapi: 3.2.0
info:
  contact:
    email: hola@boletinclaro.es
    name: Boletín Claro
    url: https://boletinclaro.es/v1
  description: 'API REST de solo lectura sobre las fuentes oficiales que vigila Boletín Claro: la BDNS y EUFUNDING para subvenciones, la PLACSP y TED para licitaciones, y los boletines oficiales del Estado, las comunidades autónomas, las provincias forales y la Unión Europea.


    La búsqueda es **semántica**: se describe en una frase lo que se busca, no se pasan palabras clave sueltas.


    Clave obligatoria en datos; documentación pública. Gratis 100, Individual 500, Pro 2.000, Mega 15.000 créditos/mes (en Gratis, Individual y Pro compartidos con MCP y la web; en Mega la API tiene un saldo propio, independiente del de la aplicación). Coste: búsquedas sencillas 1, empresas 5. Gratis 5 perfiles/mes. Los límites de uso.


    Referencia escrita: https://boletinclaro.es/v1


    Referencia interactiva: https://boletinclaro.es/v1/referencia'
  license:
    name: Condiciones de uso de Boletín Claro
    url: https://boletinclaro.es/terminos
  summary: Subvenciones, licitaciones y boletines oficiales de España y Europa, en JSON.
  termsOfService: https://boletinclaro.es/terminos
  title: de Boletín Claro Referencia API
  version: 1.0.0
servers:
- description: Producción
  url: https://boletinclaro.es/v1
security:
- claveAPI: []
- claveCabecera: []
tags:
- name: Referencia
paths:
  /:
    get:
      description: 'Devuelve la página de referencia en HTML, o un índice de endpoints en JSON si la petición envía `Accept: application/json`.'
      operationId: referencia
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
            text/html:
              schema:
                type: string
          description: La referencia, en HTML o en JSON según `Accept`.
        '429':
          $ref: '#/components/responses/Error429'
      security: []
      summary: Referencia de la API
      tags:
      - Referencia
  /assets/redoc-2.5.4.js:
    get:
      description: 'Redoc 2.5.4 (MIT), servido desde nuestro propio origen en vez de desde un CDN porque la política de seguridad del dominio solo admite scripts propios. No forma parte del contrato de datos: está documentado porque está montado bajo `/v1`.'
      operationId: referenciaScript
      responses:
        '200':
          content:
            application/javascript:
              schema:
                type: string
          description: El script.
        '429':
          $ref: '#/components/responses/Error429'
      security: []
      summary: El script de la referencia interactiva
      tags:
      - Referencia
  /errores:
    get:
      description: 'Todos los errores que puede devolver esta API: qué significa cada uno, si merece la pena reintentar y cuándo. Es la documentación a la que apunta el campo `type` de cualquier respuesta de error.


        HTML en el navegador; con `Accept: application/json`, la misma lista en JSON (`{base, total, errores[]}`, cada error con `codigo`, `tipo`, `estado`, `titulo`, `significado`, `reintento` y `reintentable`).'
      operationId: catalogoDeErrores
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
            text/html:
              schema:
                type: string
          description: El catálogo, en HTML o en JSON según `Accept`.
        '429':
          $ref: '#/components/responses/Error429'
      security: []
      summary: Catálogo de errores
      tags:
      - Referencia
  /errores/{codigo}:
    get:
      description: 'La página a la que dereferencia el `type` de una respuesta de error: qué significa, si merece la pena reintentar y cuándo.'
      operationId: detalleDeError
      parameters:
      - description: El código del error, es decir el último segmento de su `type`. Se acepta en minúsculas, y el slug en español con el que se publicó este catálogo el 10-09-2026 redirige de forma permanente a su código.
        example: BC-4003
        in: path
        name: codigo
        required: true
        schema:
          enum:
          - BC-1001
          - BC-1002
          - BC-1003
          - BC-2001
          - BC-2002
          - BC-3001
          - BC-3002
          - BC-4001
          - BC-4002
          - BC-4003
          - BC-4004
          - BC-4005
          - BC-4006
          - BC-4007
          - BC-5001
          - BC-5002
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
            text/html:
              schema:
                type: string
          description: La entrada del catálogo, en HTML o en JSON según `Accept`.
        '404':
          $ref: '#/components/responses/Error404'
        '429':
          $ref: '#/components/responses/Error429'
      security: []
      summary: Un error del catálogo
      tags:
      - Referencia
  /openapi.json:
    get:
      description: Este mismo documento. Impórtalo en Postman, Insomnia o un generador de clientes.
      operationId: especificacion
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: El documento OpenAPI.
        '429':
          $ref: '#/components/responses/Error429'
      security: []
      summary: Especificación OpenAPI 3.1 de esta API
      tags:
      - Referencia
  /referencia:
    get:
      description: 'La misma especificación, navegable: endpoints, parámetros, esquemas desplegables y ejemplos. Se genera de `/v1/openapi.json`, así que no puede contradecirlo.'
      operationId: referenciaInteractiva
      responses:
        '200':
          content:
            text/html:
              schema:
                type: string
          description: La referencia interactiva, en HTML.
        '429':
          $ref: '#/components/responses/Error429'
      security: []
      summary: Referencia interactiva (este documento, dibujado)
      tags:
      - Referencia
components:
  responses:
    Error429:
      content:
        application/problem+json:
          examples:
            BC-4001:
              value:
                codigo: BC-4001
                detail: Has superado el límite de peticiones por minuto. Usa una clave de API para subirlo.
                status: 429
                title: Demasiadas peticiones
                type: https://boletinclaro.es/v1/errores/BC-4001
            BC-4002:
              value:
                codigo: BC-4002
                detail: Has superado el ritmo de llamadas o créditos por minuto de tu workspace.
                status: 429
                title: Demasiadas peticiones
                type: https://boletinclaro.es/v1/errores/BC-4002
            BC-4003:
              value:
                codigo: BC-4003
                detail: Has agotado los créditos mensuales de tu workspace. Se renuevan el día 1 a las 00:00 UTC.
                status: 429
                title: Cuota mensual agotada
                type: https://boletinclaro.es/v1/errores/BC-4003
            BC-4004:
              value:
                codigo: BC-4004
                detail: Has alcanzado las 5 llamadas mensuales a perfil de empresa de Gratis. Se renuevan el día 1 a las 00:00 UTC.
                status: 429
                title: Máximo de perfiles agotado
                type: https://boletinclaro.es/v1/errores/BC-4004
            BC-4005:
              value:
                codigo: BC-4005
                detail: Tu workspace ha alcanzado el límite diario de créditos. Se renueva a las 00:00 UTC.
                status: 429
                title: Límite diario de créditos alcanzado
                type: https://boletinclaro.es/v1/errores/BC-4005
            BC-4006:
              value:
                codigo: BC-4006
                detail: Has alcanzado tu límite mensual de créditos como usuario. Se renueva el día 1 a las 00:00 UTC.
                status: 429
                title: Límite mensual por usuario alcanzado
                type: https://boletinclaro.es/v1/errores/BC-4006
            BC-4007:
              value:
                codigo: BC-4007
                detail: Tu workspace ha alcanzado el máximo mensual de consultas de empresa y fichas de detalle.
                status: 429
                title: Máximo mensual de consultas de empresa y fichas alcanzado
                type: https://boletinclaro.es/v1/errores/BC-4007
          schema:
            $ref: '#/components/schemas/Problema'
      description: Has superado la ráfaga, el saldo mensual o diario del workspace, el tope por usuario o el máximo de perfiles y fichas.
      headers:
        Retry-After:
          description: 'Segundos que hay que esperar antes de reintentar. Para `BC-4001` y `BC-4002` son menos de 60; para `BC-4005` son los que faltan hasta las 00:00 UTC; para `BC-4003`, `BC-4004`, `BC-4006` y `BC-4007` son los que faltan hasta el día 1 del mes que viene, así que pueden ser semanas: no reintentes antes, no puede funcionar.'
          example: 43
          required: false
          schema:
            minimum: 1
            type: integer
        X-Credits-Minute-Limit:
          description: Créditos de la admisión y del saldo; X-Profiles cuenta llamadas y solo aparece en Gratis/Trial/Oposiciones.
          schema:
            type: integer
        X-Credits-Minute-Remaining:
          description: Créditos de la admisión y del saldo; X-Profiles cuenta llamadas y solo aparece en Gratis/Trial/Oposiciones.
          schema:
            type: integer
        X-Profiles-Limit:
          description: Créditos de la admisión y del saldo; X-Profiles cuenta llamadas y solo aparece en Gratis/Trial/Oposiciones.
          schema:
            type: integer
        X-Profiles-Remaining:
          description: Créditos de la admisión y del saldo; X-Profiles cuenta llamadas y solo aparece en Gratis/Trial/Oposiciones.
          schema:
            type: integer
        X-Quota-Admission-ID:
          description: Identificador del registro de admisión confirmado atómicamente con el consumo. Disponible en Ajustes → API; no se emite en 401/429 ni documentación pública.
          schema:
            type: string
        X-Quota-Cost:
          description: Créditos de la admisión y del saldo; X-Profiles cuenta llamadas y solo aparece en Gratis/Trial/Oposiciones.
          schema:
            type: integer
        X-Quota-Limit:
          description: 'Créditos mensuales de tu saldo: el de API en Mega; en el resto de planes, el del workspace compartido con MCP y la web.'
          example: 15000
          required: false
          schema:
            type: integer
        X-Quota-Period:
          description: Periodo de cuota mensual.
          schema:
            enum:
            - month
            type: string
        X-Quota-Remaining:
          description: Créditos que te quedan este mes después de admitir esta petición. Cuenta respuestas cacheadas y errores posteriores a la admisión.
          example: 14995
          required: false
          schema:
            type: integer
        X-Quota-Reset:
          description: Momento en que se renueva la cuota, en RFC 3339. La ventana es un mes natural.
          example: '2026-10-01T00:00:00Z'
          required: false
          schema:
            format: date-time
            type: string
        X-Quota-Scope:
          description: El saldo se comparte entre claves, usuarios y clientes MCP del workspace.
          schema:
            enum:
            - workspace
            type: string
        X-Quota-Unit:
          description: Unidad del saldo mensual.
          schema:
            enum:
            - credits
            type: string
        X-Quota-Used:
          description: Créditos de la admisión y del saldo; X-Profiles cuenta llamadas y solo aparece en Gratis/Trial/Oposiciones.
          schema:
            type: integer
        X-RateLimit-Limit:
          description: 'Créditos mensuales de tu saldo: el de API en Mega; en el resto de planes, el del workspace compartido con MCP y la web.'
          example: 15000
          required: false
          schema:
            type: integer
        X-RateLimit-Minute-Limit:
          description: Admisiones por minuto natural UTC, compartidas entre las claves de la cuenta.
          schema:
            type: integer
        X-RateLimit-Minute-Remaining:
          description: Admisiones restantes después de esta petición.
          schema:
            type: integer
        X-RateLimit-Minute-Reset:
          description: Fin de la ventana, en UTC. El cambio de mes también reinicia la ventana.
          schema:
            format: date-time
            type: string
        X-RateLimit-Remaining:
          description: Créditos que te quedan este mes después de admitir esta petición. Cuenta respuestas cacheadas y errores posteriores a la admisión.
          example: 14995
          required: false
          schema:
            type: integer
        X-RateLimit-Reset:
          description: Momento en que se renueva la cuota, en RFC 3339. La ventana es un mes natural.
          example: '2026-10-01T00:00:00Z'
          required: false
          schema:
            format: date-time
            type: string
    Error404:
      content:
        application/problem+json:
          examples:
            BC-3001:
              value:
                codigo: BC-3001
                detail: No tenemos registros de dinero público para el NIF A78053147.
                status: 404
                title: No encontrado
                type: https://boletinclaro.es/v1/errores/BC-3001
            BC-3002:
              value:
                codigo: BC-3002
                detail: La ruta «/v1/noexiste» no existe en esta API. Las rutas que sí existen están en https://boletinclaro.es/v1 y en https://boletinclaro.es/v1/openapi.json.
                status: 404
                title: Ruta no encontrada
                type: https://boletinclaro.es/v1/errores/BC-3002
          schema:
            $ref: '#/components/schemas/Problema'
      description: No hay registros para lo pedido, o la ruta no existe.
  schemas:
    Problema:
      description: 'Cuerpo de error estándar RFC 9457, servido como `application/problem+json`. El campo que debes mirar en tu código es `codigo` (o el `type` que lo contiene): es estable y no cambiará aunque reescribamos el texto.'
      properties:
        codigo:
          description: 'El código del error, que es el último segmento de `type`. El primer dígito es la familia: 1 petición mal formada, 2 clave o plan, 3 no hay nada, 4 vas demasiado rápido, 5 fallo nuestro.'
          enum:
          - BC-1001
          - BC-1002
          - BC-1003
          - BC-2001
          - BC-2002
          - BC-3001
          - BC-3002
          - BC-4001
          - BC-4002
          - BC-4003
          - BC-4004
          - BC-4005
          - BC-4006
          - BC-4007
          - BC-5001
          - BC-5002
          example: BC-1001
          pattern: ^BC-[1-5][0-9]{3}$
          type: string
        detail:
          description: Qué ha pasado en este caso concreto.
          example: El parámetro «consulta» debe tener entre 2 y 2000 caracteres.
          type: string
        status:
          description: El mismo código HTTP de la respuesta.
          example: 400
          type: integer
        title:
          description: Resumen legible, en español.
          example: Consulta no válida
          type: string
        type:
          description: Identificador estable del error, y la URL de la página que lo explica. Catálogo completo y cerrado.
          enum:
          - https://boletinclaro.es/v1/errores/BC-1001
          - https://boletinclaro.es/v1/errores/BC-1002
          - https://boletinclaro.es/v1/errores/BC-1003
          - https://boletinclaro.es/v1/errores/BC-2001
          - https://boletinclaro.es/v1/errores/BC-2002
          - https://boletinclaro.es/v1/errores/BC-3001
          - https://boletinclaro.es/v1/errores/BC-3002
          - https://boletinclaro.es/v1/errores/BC-4001
          - https://boletinclaro.es/v1/errores/BC-4002
          - https://boletinclaro.es/v1/errores/BC-4003
          - https://boletinclaro.es/v1/errores/BC-4004
          - https://boletinclaro.es/v1/errores/BC-4005
          - https://boletinclaro.es/v1/errores/BC-4006
          - https://boletinclaro.es/v1/errores/BC-4007
          - https://boletinclaro.es/v1/errores/BC-5001
          - https://boletinclaro.es/v1/errores/BC-5002
          example: https://boletinclaro.es/v1/errores/BC-1001
          format: uri
          type: string
      required:
      - type
      - codigo
      - title
      - status
      type: object
  securitySchemes:
    claveAPI:
      description: 'Obligatoria para datos. Gratis 100, Individual 500, Pro 2.000, Mega 15.000 créditos/mes en el saldo de API, independiente del de la aplicación (en Gratis, Individual y Pro, saldo del workspace compartido con MCP y la web). Mega añade 1.500 créditos al día y 500 llamadas de cinco créditos al mes por saldo. Consultas sencillas 1; empresas 5. Gratis admite cinco perfiles/mes. Trial tiene el cupo Gratis. Minuto: Gratis 20 llamadas/20 créditos, Individual 30/100, Pro 60/300, Mega 300/1.500. La documentación sigue pública. Crea la clave en https://boletinclaro.es/ajustes/api.'
      scheme: bearer
      type: http
    claveCabecera:
      description: Clave del workspace, disponible también en Gratis.
      in: header
      name: X-API-Key
      type: apiKey
externalDocs:
  description: 'Referencia interactiva: este mismo documento, navegable'
  url: https://boletinclaro.es/v1/referencia