Cómo integrar códigos CNAE/IAE en tu software de facturación (Verifactu-ready)

Los fabricantes de software de facturación y ERPs españoles se enfrentan a una tormenta regulatoria con tres fechas clave. Verifactu exige sistemas informáticos de facturación (SIF) conformes con el reglamento, con declaración responsable del fabricante: sociedades antes del 1 de enero de 2027 y autónomos antes del 1 de julio de 2027, según el Real Decreto-ley 15/2025, de 2 de diciembre. Además, el plazo para actualizar el código CNAE al CNAE 2025 ante la AEAT termina el 30 de junio de 2026. Un software que guarda la actividad del cliente con un CNAE 2009 obsoleto o un IAE mal clasificado propaga el error a modelos fiscales y censos. Consulta la guía completa de Verifactu para los detalles normativos.

Por qué tu software de facturación necesita códigos correctos

Integrar códigos CNAE e IAE correctos en tu SIF no es una mejora cosmética, sino un requisito estructural para cumplir con Verifactu y con la actualización censal ante la AEAT. Un epígrafe IAE mal asignado o un CNAE 2009 obsoleto en la ficha del cliente condiciona los modelos que presenta (303, 390…) y su situación censal. El resultado son requerimientos, revisiones manuales y un soporte técnico saturado. La API del Conversor IAE-CNAE te permite automatizar la selección, validación y migración de estos códigos directamente desde tu lógica de negocio, eliminando el error humano y garantizando que cada alta de cliente nazca con los códigos correctos según la AEAT.

Selector de actividad con búsqueda semántica

El alta de un cliente en un ERP suele incluir un campo desplegable con cientos de epígrafes IAE. El usuario teclea «fontanería», no encuentra nada y acaba seleccionando «Otros servicios» por descarte. La API resuelve esto con el endpoint GET /api/v1/search, que implementa una búsqueda híbrida léxica y semántica sobre los catálogos IAE y CNAE 2025. El parámetro q acepta descripciones en lenguaje natural a partir de dos caracteres, y el parámetro type permite filtrar por iae, cnae o both. La autenticación se realiza mediante la cabecera X-API-Key con una clave que empieza por cvr_.

curl -H "X-API-Key: cvr_TU_CLAVE" "https://www.conversoriaecnae.es/api/v1/search?q=fontaneria&type=both&limit=10"

El caso de uso es directo: en el formulario de alta de cliente, sustituyes el desplegable tradicional por un campo de texto libre. El usuario escribe «reformas de cocinas» y el selector devuelve los epígrafes IAE y códigos CNAE 2025 relevantes, ordenados por relevancia. Esto evita que el usuario tenga que navegar manualmente 1.186 epígrafes IAE y reduce drásticamente los errores de clasificación en origen.

Migrar carteras CNAE 2009 a CNAE 2025

El 30 de junio de 2026 es la fecha límite para comunicar a la AEAT el nuevo código CNAE 2025 de cada cliente. Si tu software almacena códigos CNAE 2009 en las fichas de cliente (el catálogo obsoleto suma 629 códigos), necesitas un plan de migración automatizado. La API incluye 1.010 correspondencias CNAE 2009 a CNAE 2025. Para obtener la correspondencia de un código concreto, utilizas GET /api/v1/cnae-2009/{code}, disponible a partir del plan Profesional.

curl -H "X-API-Key: cvr_TU_CLAVE" https://www.conversoriaecnae.es/api/v1/cnae-2009/4711

Para migrar una cartera completa, el flujo recomendado es recorrer los CNAE 2009 de tus clientes con el endpoint anterior y enriquecer las fichas resultantes en lotes de hasta 50 códigos mediante POST /api/v1/bulk. Este endpoint acepta un array codes y un parámetro type con valor iae o cnae, y devuelve los resultados en el mismo orden, marcando con found false los códigos no encontrados. También requiere plan Profesional o superior.

curl -X POST https://www.conversoriaecnae.es/api/v1/bulk -H "X-API-Key: cvr_TU_CLAVE" -H "Content-Type: application/json" -d '{"codes":["501.3","504.1","505.4"],"type":"iae"}'

Este enfoque te permite procesar toda la base de clientes en lotes controlados, validar cada correspondencia y actualizar los registros antes de la fecha límite del 30 de junio de 2026.

Obligaciones fiscales por actividad

Un SIF que se limita a emitir facturas con un código de actividad está desaprovechando una oportunidad de aportar valor diferencial. La API permite precargar las obligaciones fiscales específicas de cada cliente según su epígrafe IAE o CNAE 2025. El endpoint GET /api/v1/obligaciones/{code_type}/{code} devuelve los modelos AEAT aplicables a un código, con el nivel de confianza, el motivo normativo, la periodicidad y el plazo de presentación. El endpoint de obligaciones requiere plan Profesional o superior; el complementario GET /api/v1/calendario/{code_type}/{code} es público y devuelve un archivo iCalendar (.ics) con los próximos plazos fiscales que puedes suscribir en cualquier calendario.

La API cubre 8 modelos AEAT: 036, 100, 130, 131, 303, 347, 349 y 390. No todos los modelos aplican a todos los códigos; la variabilidad depende de la actividad concreta. Para los epígrafes IAE acogidos al régimen de estimación objetiva, GET /api/v1/modulos/{code} devuelve los módulos de IRPF e IVA aplicables. Actualmente hay 81 epígrafes IAE con módulos. El caso de uso para un SIF es claro: en lugar de que el usuario configure manualmente qué modelos presentar, el sistema precarga esta información desde la ficha del cliente basándose en su epígrafe validado.

Checklist de integración

1. Crear una clave gratuita en la página de precios. El plan Desarrollador ofrece 250 req/día y 10 req/min, suficiente para desarrollo y pruebas.
2. Implementar el selector de actividad con GET /api/v1/search, sustituyendo los desplegables manuales por un campo de texto con búsqueda semántica.
3. Guardar siempre el par IAE y CNAE 2025 en la ficha del cliente. Los códigos se almacenan con puntos (501.3) y la API acepta ambas formas (501.3 o 5013).
4. Migrar los CNAE 2009 de la cartera existente combinando GET /api/v1/cnae-2009/{code} y POST /api/v1/bulk antes del 30 de junio de 2026.
5. Precargar las obligaciones fiscales con el endpoint premium de obligaciones y los plazos con el endpoint público de calendario, enriqueciendo la ficha del cliente con los modelos AEAT que le corresponden.
6. Controlar los errores de la API: 401 indica clave ausente o inválida; 403 significa que el plan contratado no cubre ese endpoint; 404 señala un código no encontrado, por lo que conviene probar con y sin puntos; 409 aparece cuando el código es ambiguo y requiere el parámetro slug; 429 indica cuota excedida y debe respetarse la cabecera Retry-After.
7. Dimensionar el plan según el volumen de operaciones: el plan Desarrollador gratuito ofrece 250 req/día y 10 req/min; el plan Profesional, por 29 €/mes, ofrece 2.000 req/día y 30 req/min; el plan Empresa, por 79 €/mes, ofrece 10.000 req/día y 100 req/min.

Para profundizar en la integración programática frente a asistentes de IA, consulta la comparativa entre MCP y API REST. La documentación completa de todos los endpoints está disponible en la referencia de la API.

Preguntas frecuentes

¿Necesito adaptar mi software de facturación para Verifactu ya?

Los plazos del Real Decreto-ley 15/2025 establecen la obligatoriedad para sociedades antes del 1 de enero de 2027 y para autónomos antes del 1 de julio de 2027. Aunque queda margen, la complejidad de la adaptación técnica, la declaración responsable que debe emitir el fabricante y la migración de códigos CNAE aconsejan empezar cuanto antes. Los detalles normativos completos están en la guía de Verifactu.

¿Puedo probar la API sin pagar?

Sí. El plan Desarrollador es gratuito e incluye 250 req/día y 10 req/min. Solo necesitas registrarte para obtener una clave que empieza por cvr_ y empezar a hacer peticiones contra la base https://www.conversoriaecnae.es/api/v1.

¿La búsqueda funciona con lenguaje natural?

Sí. El endpoint GET /api/v1/search implementa una búsqueda híbrida léxica y semántica. El parámetro q admite descripciones como «reformas de cocinas» y devuelve los epígrafes IAE y códigos CNAE 2025 relevantes, sin necesidad de conocer la nomenclatura oficial.

¿Qué pasa con los códigos CNAE 2009 después del 30 de junio de 2026?

Los 629 códigos CNAE 2009 y sus 1.010 correspondencias seguirán siendo consultables en la API como referencia histórica. Sin embargo, la actividad declarada ante la AEAT deberá estar ya codificada en CNAE 2025. La API te permite realizar esa migración de forma automatizada antes de la fecha límite.