---
title: "Lookup masivo de códigos"
method: POST
path: "/bulk"
tags: ["Códigos"]
---

# Lookup masivo de códigos

`POST /bulk`

Consulta hasta 50 códigos IAE o CNAE en una sola petición. Requiere plan Profesional o superior. Devuelve los resultados en el mismo orden que se solicitan, con `found: false` para los no encontrados.

## Request body

- BulkRequest
  - `codes` string[], required — Lista de códigos (1–50). Cada uno solo dígitos y puntos, máx. 20 caracteres.
  - `type` 'iae' | 'cnae', required

## Response `200`

Resultados del lookup masivo

- BulkResponse
  - `type` 'iae' | 'cnae'
  - `results` BulkResult[]
    - `code` string, required
    - `found` boolean, required
    - `data` object, nullable — Fila completa del catálogo cuando `found` es true; ausente cuando es false. Para `type=cnae`, el campo `iae_correspondiente` contiene códigos IAE cualificados por sección (`cod_integro_iae`, p. ej. `"A011"`), no códigos numéricos simples — esto desambigua los epígrafes que comparten número entre secciones A/B/C. Para reutilizar uno en `GET /iae/{code}`, quita la letra de sección inicial (`"A011"` → `"011"`). Para `type=iae`, el campo `relaciones_iae` contiene códigos IAE relacionados cualificados por sección (`cod_integro_iae`, p. ej. `"A011"`), no códigos numéricos simples — el mismo criterio de desambiguación. Para reutilizar uno en `GET /iae/{code}`, quita igualmente la letra de sección inicial (`"A011"` → `"011"`).
  - `total` integer
  - `found` integer
  - `_meta` Meta — Metadatos del envelope para endpoints con clave: plan actual, cuota restante y nudge de upgrade (solo plan Free al ≥80% de cuota).
    - `plan` string, required — Plan de la clave (free, profesional, empresa, enterprise).
    - `remaining` integer, required — Peticiones restantes de la cuota diaria.
    - `upgrade_hint` string — Mensaje legible de upgrade. Presente solo en plan Free al consumir ≥80% de la cuota.
    - `upgrade` UpgradeMeta — Forma estructurada del nudge de upgrade para renderizar UI nativa. Presente solo en plan Free al ≥80% de cuota.
      - `hint` string
      - `url` string, uri
      - `current_plan` string
      - `recommended_plan` object
        - `id` string
        - `label` string
        - `daily_limit` integer
        - `monthly_price_eur` integer
      - `daily_limit_after` integer
      - `price_eur_monthly` integer

## Other responses

- `400` — Petición inválida (parámetro o cuerpo mal formado).
- `401` — Falta la cabecera `X-API-Key` o la clave es inválida/desactivada.
- `403` — El endpoint requiere un plan de pago (Profesional o superior).
- `429` — Límite de cuota diaria o de ráfaga superado. La cabecera `Retry-After` indica los segundos hasta poder reintentar.
- `500` — Error interno del servidor.

---

[API](https://skmtc.dev/conversoriaecnae/apis/conversor-iae-cnae-api.md) · [All operations](https://skmtc.dev/conversoriaecnae/apis/conversor-iae-cnae-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/conversoriaecnae/conversor-iae-cnae-api/revisions/2f9842f5e11b/schema)