Caso real: cómo un banco español valida epígrafes IAE en producción
Seguimiento del caso real: 718 llamadas a la API en casi tres semanas, solo días laborables. Así valida epígrafes IAE una entidad bancaria española.
Ya contamos la integración inicial de una entidad bancaria española en nuestro artículo Cómo un banco regional español clasifica el IAE de sus clientes empresa con una API, publicado el 23 de mayo de 2026. Aquello cubría los primeros 4 días: 282 llamadas, un pipeline KYB que pasó de 5 minutos a 0,3 segundos por código. Esto es lo que muestran casi tres semanas de producción real (13 días de actividad) con el mismo cliente.
El problema: un epígrafe IAE mal clasificado contamina todo el expediente
En el alta de clientes empresa, el epígrafe IAE determina las obligaciones fiscales del cliente. Clasificarlo mal implica expedientes erróneos y revisiones manuales que retrasan la operativa. Antes de la integración, el equipo de cumplimiento del banco tardaba unos 5 minutos por código consultando PDFs del BOE; con la API, cada validación se resuelve en 0,3 segundos (dato medido en la primera entrega del caso, publicada en mayo), eliminando el error humano y el cuello de botella. Un epígrafe mal clasificado no es un simple fallo de datos: contamina el expediente completo y obliga a reabrir el caso.
La integración: una llamada GET por código
El banco integró un endpoint único en su flujo de alta de clientes empresa. Cuando el gestor introduce el código IAE declarado por el solicitante, el sistema lanza una petición contra la API antes de continuar con el expediente.
El endpoint es GET /api/v1/iae/{code} sobre la base https://www.conversoriaecnae.es/api/v1. El código admite forma con o sin puntos (501.3 o 5013). Si un código numérico coincide en varias secciones de la AEAT (Empresarial, Profesional o Artística), la API responde 409 con una lista de candidatos y se desambigua con el parámetro ?slug=. La autenticación viaja en la cabecera X-API-Key con la clave que empieza por cvr_.
La petición real que ejecuta el middleware del banco es exactamente esta:
curl -H "X-API-Key: cvr_TU_CLAVE" https://www.conversoriaecnae.es/api/v1/iae/5013
La respuesta JSON que reciben contiene estos campos:
- code: «501.3»
- title: «Albañilería y pequeños trabajos de construcción»
- seccion_label: «Empresarial»
- category: «Construcción»
- description: con las notas oficiales del epígrafe, incluido el límite de 36.060,73 euros de presupuesto por obra
- associated_cnae: con los CNAE 2025 equivalentes — 43.91 «Actividades de mampostería y albañilería» y 43.99 «Otras actividades de construcción especializada n.c.o.p.»
- related_iae: con epígrafes vecinos como 501.1 y 501.2
- keywords y last_updated
Con esta respuesta, el sistema del banco valida automáticamente que el código existe, lo asigna a la sección correcta de la AEAT y completa los campos de actividad y CNAE equivalente en el expediente, sin intervención manual.
Los números: casi tres semanas en producción
Entre el 20 de mayo y el 5 de junio de 2026 registramos 718 llamadas al endpoint GET /api/v1/iae/{code} desde la clave API del banco. Son datos agregados de producción, consultados en nuestra base de datos (Supabase) el 7 de junio de 2026.
El detalle día a día muestra un patrón inequívoco de uso en producción real:
- 20 de mayo (miércoles): 130 llamadas
- 21 de mayo (jueves): 112 llamadas
- 22 de mayo (viernes): 40 llamadas
- 25 de mayo (lunes): 58 llamadas
- 26 de mayo (martes): 74 llamadas
- 27 de mayo (miércoles): 61 llamadas
- 28 de mayo (jueves): 39 llamadas
- 29 de mayo (viernes): 19 llamadas
- 1 de junio (lunes): 35 llamadas
- 2 de junio (martes): 31 llamadas
- 3 de junio (miércoles): 36 llamadas
- 4 de junio (jueves): 44 llamadas
- 5 de junio (viernes): 39 llamadas
Hay 13 días con actividad, todos laborables. Los fines de semana registran 0 llamadas. El rango diario va de 19 a 130 llamadas.
Los dos primeros días concentran el pico: 130 y 112 llamadas. Es el backfill de la cartera existente, donde el banco repasó los expedientes activos para normalizar los epígrafes. A partir del tercer día, la actividad se mueve entre 19 y 74 llamadas diarias, un ritmo que encaja con las altas nuevas de clientes empresa. Que la actividad siga exactamente el calendario laboral bancario y que los picos se expliquen por una carga inicial de backfill es la señal más clara de que esto no son pruebas de un desarrollador: es un proceso de negocio integrado en producción.
El banco usa el plan Profesional, de 29 euros al mes con un límite de 2.000 solicitudes diarias. Su pico máximo de 130 llamadas al día consume el 6,5 % de la cuota diaria, lo que deja margen de sobra para crecer sin cambiar de plan.
Por qué no scraping ni CSV
Las tarifas del IAE se publican en PDFs del BOE no estructurados. La AEAT actualiza criterios y notas a lo largo del año. Mantener un parser propio o un CSV descargado exige vigilancia continua y un desarrollador dedicado a perseguir cambios.
El catálogo completo suma 2.875 códigos en total: 1.186 epígrafes IAE, 1.060 códigos CNAE 2025 y 629 códigos CNAE 2009, con 1.010 correspondencias de CNAE 2009 a CNAE 2025. Los datos provienen de fuentes oficiales (AEAT, INE, BOE) y se actualizan trimestralmente en la API.
Un CSV estático no resuelve la ambigüedad entre secciones de la AEAT. Un código como 501.3 existe en la sección Empresarial, pero otros códigos numéricos se solapan entre Empresarial, Profesional y Artística. La API detecta esa ambigüedad y responde 409 con los candidatos, algo que un fichero plano no puede hacer sin lógica adicional. Tampoco incluye las correspondencias CNAE actualizadas, que cambian con cada revisión de la clasificación.
Cómo replicarlo en tu equipo
Cualquier equipo puede montar la misma validación en menos de una hora. La clave gratuita se crea en la página de precios de la API: plan Desarrollador, 250 solicitudes al día y 10 por minuto, sin tarjeta.
La llamada más básica con curl:
curl -H "X-API-Key: cvr_TU_CLAVE" https://www.conversoriaecnae.es/api/v1/iae/5013
Si trabajas en Node.js, la integración son dos líneas:
const res = await fetch("https://www.conversoriaecnae.es/api/v1/iae/5013", { headers: { "X-API-Key": process.env.CONVERSOR_API_KEY } });
const epigrafe = await res.json();
Toda la referencia de endpoints, parámetros y códigos de respuesta está en la documentación de la API.
Preguntas frecuentes
¿Qué banco es?
No publicamos el nombre por confidencialidad con el cliente. Los datos de uso agregados son reales, consultados en la base de datos de producción (Supabase) el 7 de junio de 2026. Es el mismo banco regional español cuya integración inicial contamos en mayo.
¿Necesito un plan de pago para hacer esto?
No para empezar. El plan Desarrollador gratuito da 250 solicitudes al día y 10 por minuto, suficiente para probar la integración y cubrir volúmenes bajos. Este cliente usa el plan Profesional de 29 euros al mes con 2.000 solicitudes diarias, porque necesita más volumen y soporte prioritario.
¿Qué pasa si el código no existe?
La API devuelve 404. Conviene reintentar normalizando el formato, porque el endpoint acepta el código con o sin puntos. Si el código numérico es ambiguo entre secciones de la AEAT, la API responde 409 con una lista de candidatos y se desambigua añadiendo el parámetro ?slug= con el slug canónico del epígrafe correcto.
¿La API aguanta más volumen?
Los planes van de 250 solicitudes al día en el plan gratuito hasta 10.000 solicitudes al día en el plan Empresa de 79 euros al mes. Para volúmenes superiores hay un plan Enterprise a medida. El banco de este caso, con sus 718 llamadas en casi tres semanas, está muy por debajo del límite de su plan Profesional.
Fuentes: Datos de uso agregados de producción (Supabase), consultados el 7 de junio de 2026
Brian Mena
Creador del Conversor IAE CNAE, Ingeniero, MiFID II, emprendedor.
Especialista en códigos de actividad económica IAE y CNAE 2025, con amplia experiencia ayudando a autónomos y empresas españolas a identificar sus epígrafes correctos. Creador del Conversor IAE-CNAE, herramienta líder para la clasificación de actividades económicas en España.
