Integrar la API Conversor IAE/CNAE en tu ERP: guía de arquitectura

Si estáis desarrollando un ERP, un SaaS fiscal o una plataforma de gestoría digital orientada al mercado español, en algún momento os toparéis con el mismo requisito: cruzar códigos CNAE 2025 con epígrafes IAE para el Modelo 036, verificar códigos heredados del CNAE 2009, o permitir a los usuarios buscar el código correcto sin salir de vuestra aplicación. Mantener esa base de datos internamente es caro y arriesgado — cambia con cada publicación del BOE — así que consumirla vía API es el camino razonable.

Esta guía cubre los patrones de integración que funcionan en producción: autenticación, rate limits, caching, manejo de errores, y un caso de uso urgente que deberíais contemplar ahora mismo: ayudar a vuestros usuarios a remediar la comunicación del CNAE 2025 que muchos de ellos no hicieron a tiempo.

Contexto regulatorio que afecta a vuestros usuarios hoy

Antes de entrar en los patrones técnicos, una nota importante: el Real Decreto 10/2025, de 14 de enero obligó a autónomos y empresas a comunicar antes del 30 de junio de 2025 a la Tesorería General de la Seguridad Social la equivalencia CNAE 2009 a CNAE 2025. Desde el 1 de enero de 2026, quien no lo hizo está pagando un tipo de contingencias profesionales agravado, y las comunicaciones tardías no tienen efecto retroactivo.

Si vuestra plataforma da servicio a autónomos o empresas, es muy probable que un porcentaje significativo de vuestros usuarios esté en esa situación y no lo sepa. Es una oportunidad clara para añadir una funcionalidad de "chequeo de CNAE 2025" como feature de retención — y la API que os vamos a describir es la forma más eficiente de implementarla.

Autenticación con API key: lo básico que debéis saber

La API Conversor IAE CNAE usa un esquema simple de autenticación por cabecera: X-API-Key: cvr_xxxx. La clave se obtiene con un alta por correo electrónico (el endpoint POST /api/v1/signup no pide tarjeta) y se entrega en el propio email de bienvenida — la API nunca la devuelve en ninguna respuesta posterior, así que tratadla como un secreto rotable.

En vuestro backend, regla habitual: nada de commits con la clave en el código. Cargadla desde una variable de entorno tipo CONVERSOR_API_KEY y validad al arrancar que existe, para que el servicio falle rápido si el despliegue olvida inyectarla. Si construís un SaaS multi-cliente, conviene tener una clave por entorno (dev, staging, producción) para poder revocar cada una por separado si se filtra en un log.

Petición mínima desde Node.js

const res = await fetch('https://www.conversoriaecnae.es/api/v1/cnae/68.20', { headers: { 'X-API-Key': process.env.CONVERSOR_API_KEY } }); const { data, _meta } = await res.json(); console.log('Plan:', _meta.plan, 'Quedan hoy:', _meta.remaining);

El campo _meta.remaining que viene en cada respuesta es vuestro contador vivo: exponedlo en las métricas internas para saber en tiempo real cuánto os queda del cupo diario.

Rate limits y el patrón de backoff

Cada plan tiene un límite diario que se resetea a las 00:00 UTC:

• Desarrollador (gratis): 100 peticiones al día. Bien para desarrollo y pruebas.
• Profesional (29 €/mes): 2 000 peticiones al día. ERPs y SaaS pequeños.
• Empresa (79 €/mes): 10 000 peticiones al día. Plataformas con decenas de miles de usuarios activos.
• Enterprise: personalizado con SLA del 99,9 %.

Cuando rebasáis el límite, la API responde con un HTTP 429 y cuerpo JSON { "error": "Rate limit exceeded", "limit": 2000, "plan": "profesional" }. La gestión limpia desde el cliente combina tres técnicas:

1. Cliente HTTP con retry exponencial: sobre un 429 o 5xx transitorio, esperad 500 ms, luego 1 s, luego 2 s, con jitter. No inventéis la rueda: axios-retry, got o ky traen helpers listos en Node; en Python, tenacity. Tres reintentos bastan.
2. Circuit breaker por encima del retry: si en 30 segundos encadenáis 10 errores 429, abrid el circuito y devolved desde caché local (o un error controlado "Servicio temporalmente limitado") durante 60 segundos. Así no desperdiciáis ni cuota ni latencia.

1. Consulta no-consumidora al endpoint /usage: este endpoint devuelve requests_used_today y remaining_today sin gastar cupo. Integradlo en un health check cada 5 minutos para detectar cuándo vais a tocar techo y adelantaros — por ejemplo degradando a caché antes de agotar la cuota.

Caching: dónde vale la pena y dónde no

Los códigos CNAE e IAE cambian raramente. Una ventana de cache de 24 horas por código individual es segura y reduce la carga de forma brutal. Un patrón que funciona en producción:

frontend -> backend -> Redis (TTL 24h) -> API Conversor si miss

Con un TTL de 24 horas, una petición del tipo GET /cnae/6820 que reciba 500 usuarios concurrentes en vuestra app genera una sola llamada a la API Conversor. El resto se sirven desde Redis en menos de 5 ms. Si os importa la frescura absoluta durante una migración regulatoria (como la del CNAE 2009 al 2025), podéis validar la caché contra el campo last_updated del registro y solo invalidar entradas más antiguas que esa fecha.

Lo que no deberíais cachear: los resultados del endpoint /search?q=..., porque dependen de la query libre del usuario y el universo de búsquedas posibles es enorme. Si queréis acelerar búsquedas frecuentes, considerad cachearlas en el frontend con un debounce de 250 ms y una TTL corta (5 minutos) en vuestro backend.

Manejo de errores: lo que debéis exponer al usuario

La API devuelve errores en formato estándar:

• 401 — clave API ausente o inválida (alerta para vuestro equipo de ops, nunca al usuario final).
• 404 — código no existe (mostrad una sugerencia del endpoint /search como "did you mean?").
• 429 — rate limit superado (degradá a caché silenciosamente si podéis).
• 400 — query inválida (sanead el input en el frontend antes de enviar).
• 403 — endpoint de plan superior (mostrad CTA de upgrade solo si el usuario os paga por esa feature).

La regla de oro: nunca filtrar mensajes crudos de la API al usuario final. Un 401 debe convertirse en un log interno y un mensaje genérico "Error interno, estamos trabajando en ello"; un 404 debe convertirse en un "No hemos encontrado ese código, ¿querías decir...?" con sugerencias reales.

Caso práctico: feature "Chequeo CNAE 2025" en menos de 50 líneas

Un flujo que deberíais ofrecer hoy a vuestros usuarios — autónomos o empresas — es un chequeo rápido de si su CNAE actual es CNAE 2009 o CNAE 2025, y en el primer caso darle la correspondencia oficial. En pseudocódigo:

async function chequeoCnae2025(userCnae) {
const r1 = await apiGet('/cnae/' + userCnae);
if (r1.ok) return { estado: 'correcto', codigo: r1.data };

const r2 = await apiGet('/cnae-2009/' + userCnae);
if (r2.ok && r2.data.correspondences.length > 0) {
return {
estado: 'pendiente_comunicar',
cnae_2009: userCnae,
equivalencias_2025: r2.data.correspondences,
accion: 'Comunicar a TGSS vía IMPORTASS o sistema RED',
};
}
return { estado: 'desconocido' };
}

Con esa función envuelta en un endpoint de vuestra API interna, podéis mostrar en el dashboard del usuario un banner: "Detectamos que tu CNAE podría estar desactualizado desde el 1 de enero de 2026. Comunicarlo a la TGSS evita un sobrecoste en contingencias profesionales." Retención pura.

Patrones de búsqueda: autocompletado con /search

Para el alta de cliente, el patrón más común es el lookup con autocompletado: el usuario teclea "diseño gráfico", vuestro frontend hace debounce de 250 ms y llama a /search?q=diseno+grafico&type=cnae&limit=10. La API devuelve los 10 códigos CNAE 2025 más relevantes ordenados por un sistema de puntuación multi-señal (prefix match, fuzzy match, popularity, etc.). Al seleccionar uno, llamáis a /cnae/{code} para traer el registro completo con epígrafes IAE relacionados.

El equipo que quiera probar el flujo sin tocar código puede usar el conversor gratuito desde la web para validar ejemplos antes de escribir una sola línea de integración. La documentación completa está en la página oficial.

Lee también

• Si gestionáis una cartera de clientes: Cartera sobrecotizando por CNAE 2025: detectarla con API bulk.
• Si queréis que vuestros usuarios autónomos validen su propio CNAE sin tocar vuestra plataforma: 100 consultas gratis al día.

Preguntas frecuentes

¿La API ofrece webhooks para avisar de cambios en códigos CNAE o IAE?

Actualmente el modelo es pull: vosotros consultáis el dato y os llega con el campo last_updated. Para detectar cambios regulatorios conviene combinar una consulta periódica a los códigos críticos con la invalidación de caché basada en last_updated. Si tenéis un caso de uso que requiere webhooks reales, el equipo de Enterprise evalúa integraciones a medida.

¿Podemos usar una sola clave API para varios entornos (dev, staging, prod)?

Técnicamente sí, pero es mala práctica. Usad una clave por entorno para poder revocar la de staging si un desarrollador la filtra en un log sin afectar a producción. El alta es gratuita y se hace por correo desde la documentación oficial.

¿Qué pasa con los datos de usuario si la API recibe información personal en las peticiones?

La API solo procesa códigos CNAE e IAE, que no son datos personales. Los únicos datos personales que guarda el servicio son el correo de alta y el hash de la clave (ni siquiera la clave en claro). Las IPs de las peticiones se almacenan hasheadas con SHA-256 para cumplir RGPD.