API · Recetas

Recetas de la API IAE/CNAE 2025

Seis recetas ejecutables — cURL, Node y Python — para llevarte del curl inicial al despliegue real en gestoría, fintech o ERP, y, al final, recetas para agentes MCP.

1 · Consulta puntual 2 · Búsqueda 3 · Migración bulk 4 · Batch asíncrono 5 · Obligaciones fiscales 6 · Módulos (estimación objetiva)7 · Agentes (MCP)

Mostrar código en

Receta 1

Consulta puntual de un código IAE o CNAE

Caso de uso: validar en tu backend un código declarado por el usuario en un formulario (alta de autónomo, KYB, perfil de cliente). Latencia p50 < 100 ms.

curl -H "X-API-Key: cvr_TU_CLAVE" \
  "https://www.conversoriaecnae.es/api/v1/iae/501.3"

Respuesta esperada — 200 OK

{
  "code": "501.3",
  "cod_integro": "A501.3",
  "slug": "albanileria-y-pequenos-trabajos",
  "title": "Albañilería y pequeños trabajos de construcción",
  "seccion_label": "Empresarial",
  "modulos_eligible": true,
  "_meta": { "plan": "free", "remaining": 248 }
}

Prueba en vivo en el playground →

Receta 2

Búsqueda por nombre de actividad

Caso de uso: autocomplete en un formulario de alta. El parámetro q debe ir url-encodeado — los 3 ejemplos lo gestionan automáticamente.

# El parámetro q debe url-encodearse (--data-urlencode lo gestiona)
curl -G "https://www.conversoriaecnae.es/api/v1/search" \
  -H "X-API-Key: cvr_TU_CLAVE" \
  --data-urlencode "q=consultoria" \
  --data-urlencode "type=cnae" \
  --data-urlencode "limit=5"

Respuesta esperada — 200 OK

{
  "query": "consultoria informatica",
  "results": [
    { "cod_cnae": "62.02", "titulo_cnae": "Actividades de consultoría informática" },
    { "cod_cnae": "70.22", "titulo_cnae": "Otras actividades de consultoría de gestión" }
  ],
  "_meta": { "plan": "free", "remaining": 247 }
}

Prueba en vivo en el playground →

Receta 3Profesional

Migración masiva CNAE 2009 → 2025

Caso de uso: gestoría con cientos o miles de clientes que debe actualizar epígrafes en el plazo general de 1 mes (modelo 036, AEAT). Combina POST /v1/bulk con GET /v1/cnae-2009/{code} para los epígrafes obsoletos sin equivalente directo.

# Paso 1 — migrar hasta 50 códigos en una sola petición POST /bulk
curl -X POST "https://www.conversoriaecnae.es/api/v1/bulk" \
  -H "X-API-Key: cvr_TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "codes": ["6201", "6202", "6311"],
    "type": "cnae"
  }'

# Paso 2 — para epígrafes obsoletos sin equivalente directo, consulta el
# catálogo CNAE 2009 (plazo general de 1 mes, modelo 036).
curl -H "X-API-Key: cvr_TU_CLAVE" "https://www.conversoriaecnae.es/api/v1/cnae-2009/4774"

Respuesta esperada — POST /bulk

{
  "type": "cnae",
  "results": [
    { "code": "6201", "found": true, "data": { "titulo_cnae": "Programación informática" } },
    { "code": "6202", "found": true, "data": { "titulo_cnae": "Consultoría informática" } },
    { "code": "6311", "found": false }
  ],
  "total": 3,
  "found": 2,
  "_meta": { "plan": "profesional", "remaining": 1949 }
}

Receta 4 · Python only

Procesamiento por lotes asíncrono en Python

Caso de uso: gestoría con 2.000 clientes en un CSV que debe consultar el catálogo IAE. Usa asyncio + httpx con un pacing de ~6,5 s entre peticiones para mantenerse bajo el límite de ráfaga de 10 req/min por clave y hace exponential backoff sobre HTTP 429.

Python · asyncio + httpx

# Procesamiento secuencial de un CSV de 2.000 códigos IAE — Python 3.11+
# pip install httpx
#
# IMPORTANTE — el límite de ráfaga es 10 req/min POR CLAVE (no por segundo).
# Un semáforo limita paralelismo, no tasa: con respuestas p50 ~80 ms, 8 slots
# en vuelo superan fácilmente los 10 req/min y producen 429 en cascada. La
# única forma correcta de mantener el ritmo es esperar ~6,5 s entre peticiones
# (≈9 req/min, margen seguro bajo el burst guard).
#
# Coste real: un CSV de 2.000 filas tarda ≈3,6 h a este ritmo. Para volúmenes
# sostenidos superiores escribe a [email protected] y te configuramos
# un plan Empresa con límites custom.
import asyncio, csv, os, httpx

API_KEY = os.environ["CONVERSOR_API_KEY"]
BASE = "https://www.conversoriaecnae.es/api/v1"
CUOTA_DIARIA = 2000           # plan Profesional — ver /precios
PACING_SECONDS = 6.5          # 60/6.5 ≈ 9 req/min < burst guard de 10/min

async def consultar(client: httpx.AsyncClient, code: str, intento: int = 0) -> dict:
    r = await client.get(f"{BASE}/iae/{code}", headers={"X-API-Key": API_KEY})

    if r.status_code == 429:
        # Backoff exponencial usando retry_after_seconds del body.
        body = r.json()
        espera = body.get("retry_after_seconds", 2 ** intento)
        await asyncio.sleep(espera)
        if intento < 4:
            return await consultar(client, code, intento + 1)
        return {"code": code, "error": "rate_limited"}

    r.raise_for_status()
    return r.json()

async def main(path_csv: str) -> None:
    with open(path_csv, newline="") as f:
        codigos = [row["codigo_iae"] for row in csv.DictReader(f)]

    if len(codigos) > CUOTA_DIARIA:
        raise SystemExit(f"{len(codigos)} > cuota diaria de {CUOTA_DIARIA}")

    resultados: list[dict] = []
    async with httpx.AsyncClient(timeout=10.0) as client:
        for i, code in enumerate(codigos):
            try:
                resultados.append(await consultar(client, code))
            except Exception as exc:  # noqa: BLE001 — no abortar el lote
                resultados.append({"code": code, "error": repr(exc)})
            # Espacia las peticiones para respetar el burst de 10 req/min.
            if i < len(codigos) - 1:
                await asyncio.sleep(PACING_SECONDS)

    ok = [r for r in resultados if "error" not in r]
    ko = [r for r in resultados if "error" in r]
    print(f"OK: {len(ok)}  ·  KO: {len(ko)}")

if __name__ == "__main__":
    asyncio.run(main("clientes.csv"))

Buenas prácticas

Cuota diaria: el plan Profesional permite 2.000 req/día. Aborta antes de ejecutar si el CSV excede el cupo.
Ráfaga real: el límite es 10 req/min por clave. Un semáforo limita paralelismo, NO tasa — con respuestas p50 ~80 ms cualquier pool de workers excede el burst guard. La única forma correcta es esperar entre peticiones (≈6,5 s ≈ 9 req/min). Un CSV de 2.000 filas tarda ≈3,6 h a este ritmo.
Volumen alto sostenido: para más de 100 códigos por día de forma continuada, contacta a [email protected] para un plan Empresa con límites custom.
Reintentos: sobre HTTP 429 lee retry_after_seconds del body y aplica exponential backoff con tope (4 intentos).
Recolección de errores: captura excepciones por petición y guarda {"code": ..., "error": ...} en el resultado para no abortar todo el lote por un fallo aislado.

Receta 5 · Profesional+

Obligaciones fiscales por código (qué modelos AEAT aplican)

Caso de uso: tu software de gestoría o tu panel de onboarding sabe exactamente qué modelos debe presentar cada cliente en cuanto conoces su epígrafe. La API devuelve el 303, el 130, el 111… con su periodicidad y el fecha_proximo_plazo — fecha nominal del calendario AEAT 2026 (sin prórroga de días inhábiles aplicada) — sin que mantengas ni una sola tabla de plazos.

# Qué modelos AEAT debe presentar un código IAE (o CNAE)
curl -H "X-API-Key: cvr_TU_CLAVE" \
  "https://www.conversoriaecnae.es/api/v1/obligaciones/iae/501.3"

Respuesta esperada — 200 OK

{
  "code": "5013",
  "type": "iae",
  "obligaciones": [
    {
      "modelo_id": "303",
      "name": "IVA. Autoliquidación",
      "periodicidad": "trimestral",
      "confidence": 0.95,
      "reason": "Actividad sujeta a IVA en régimen general",
      "fecha_proximo_plazo": "2026-07-20"
    },
    {
      "modelo_id": "130",
      "name": "IRPF. Pago fraccionado",
      "periodicidad": "trimestral",
      "confidence": 0.9,
      "reason": "Estimación directa en IRPF",
      "fecha_proximo_plazo": "2026-07-20"
    }
  ],
  "total": 2,
  "_meta": { "plan": "profesional", "remaining": 1985 }
}

Receta 6Profesional

Régimen de módulos (estimación objetiva) de un epígrafe IAE

Caso de uso: tu producto calcula la estimación objetiva sin mantener tablas de módulos. La API te da los módulos de IRPF e IVA, las unidades, los umbrales y los avisos de cálculo de cada actividad. Para los códigos que colisionan entre secciones AEAT, la respuesta 409 incluye los candidatos y reintentas con ?slug=; los ejemplos lo gestionan automáticamente.

# Régimen de módulos (estimación objetiva) de un epígrafe IAE.
# Si el código colisiona entre secciones AEAT, la respuesta 409
# incluye los candidatos: reintenta con ?slug= para desambiguar.
curl -H "X-API-Key: cvr_TU_CLAVE" \
  "https://www.conversoriaecnae.es/api/v1/modulos/642.1"

Respuesta esperada — 200 OK

{
  "code": "6421",
  "slug": "comercio-menor-carnes-huevos-caza-y-granja",
  "titulo": "Comercio menor carnes, huevos, caza y granja",
  "modulos_eligible": true,
  "regimen": {
    "actividad": { "definicion": "Comercio al por menor de carnes y despojos; huevos, aves, conejos de granja, caza y productos derivados de los mismos" },
    "modulos_irpf": [
      {
        "modulo_num": 1,
        "definicion": "Personal asalariado",
        "unidad": "Persona",
        "rendimiento_anual_unidad": 2355.68
      }
    ],
    "modulos_iva": [],
    "umbrales_actividad": {},
    "umbrales_generales": {},
    "intelligence": {
      "modulos_summary": "...",
      "calculo_hints": { "primary_modulos": [], "common_pitfalls": [] },
      "citations": []
    }
  },
  "_meta": { "plan": "profesional", "remaining": 1985 }
}

Código ambiguo — 409 Conflict

{
  "error": "ambiguous_code",
  "code": "834",
  "message": "Múltiples filas IAE coinciden con este código. Use ?slug= para desambiguar.",
  "candidates": [
    { "code": "834", "cod_integro": "A834", "title": "Servicios propiedad inmobiliaria e industria", "slug": "servicios-propiedad-inmobiliaria-industria", "url": "/api/v1/modulos/834?slug=servicios-propiedad-inmobiliaria-industria" },
    { "code": "834", "cod_integro": "B834", "title": "Odontologos", "slug": "odontologos", "url": "/api/v1/modulos/834?slug=odontologos" }
  ],
  "_meta": { "plan": "profesional", "remaining": 1985 }
}

Recetas para agentes · MCP

Recetas para agentes (MCP)

Con el servidor MCP, un agente —Claude, Cursor, Gemini CLI u otro cliente compatible— llama estas herramientas directamente en tu nombre. No necesitas escribir una sola línea de código HTTP: el agente interpreta tu pregunta en lenguaje natural, elige la herramienta correcta y devuelve la respuesta ya procesada.

Obligaciones fiscales: «¿Qué modelos AEAT me tocan con el epígrafe 5013?»

El agente llama obligaciones_fiscales y devuelve el listado de modelos (303, 130…) con su periodicidad y el próximo plazo AEAT calculado.

Clasificación: «Encuentra el CNAE 2025 para una consultoría informática y dame su ficha completa»

El agente encadena buscar_codigo para localizar el código y después detalle_cnae para obtener la ficha con correspondencias, obligaciones y señales fiscales.

RETA: «Soy autónomo con 28.000 € de rendimiento neto, ¿cuál es mi cuota mínima de autónomos en 2026?»

El agente llama cuota_reta con el rendimiento neto y devuelve la base de cotización, la cuota mensual mínima y el tramo de la tabla RETA 2025–2026.

Conéctalo en Claude en 30 segundos — ver guía MCP.

¿Listo para tu primera petición?

Gratis y sin tarjeta: la primera clave de cada email empieza con 14 días de prueba Profesional (2.000 peticiones/día) y después pasa al plan Gratis (250 peticiones/día). La clave llega a tu email en segundos.

Solicitar API Key gratis →Ver documentación completa