Cómo gestorías, fintech y ERPs integran la API en una tarde

Las empresas deben comunicar el cambio de sus epígrafes CNAE al nuevo catálogo INE 2025 en el plazo general de 1 mes (modelo 036). Para una gestoría con 200 a 2.000 clientes activos, hacer esa migración de forma manual —consultando una a una las equivalencias en la web de la AEAT— puede consumir semanas de trabajo.

Con el endpoint POST /api/v1/bulk, la gestoría envía hasta 50 códigos CNAE 2009 en una sola petición y recibe los registros completos del catálogo CNAE 2025: título, sector, códigos IAE asociados y los modelos AEAT aplicables. El proceso completo para 2.000 clientes cabe en 40 peticiones. A la velocidad media de la API (~80ms p50 por petición), el catálogo entero queda procesado en menos de 4 minutos.

Los códigos que devuelven found: false son candidatos para revisión manual: pueden ser epígrafes sin equivalente directo o códigos que el cliente declaró de forma incorrecta. El campo _meta.remaining indica cuántas peticiones quedan en el día para planificar el trabajo en varias sesiones.

Cuando un autónomo solicita apertura de cuenta en una plataforma fintech o neobanco, declara su actividad económica mediante el código IAE que aparece en su resolución de alta censal (Modelo 036). Si ese código no se valida en el momento del registro, el equipo de compliance debe revisarlo manualmente días después —un cuello de botella que dispara el abandono del onboarding.

El endpoint GET /api/v1/iae/{code} devuelve en una sola llamada el título oficial del epígrafe, los códigos CNAE 2025 asociados, el sector (seccion_label) y si el código es elegible para estimación objetiva por módulos. Con esa información, el sistema puede categorizar automáticamente la cuenta, calcular el perfil de riesgo fiscal inicial y pre-rellenar campos del formulario KYB sin preguntas adicionales al usuario.

La latencia media del endpoint está por debajo de 100ms en p95, lo que permite integrarlo en el flujo de validación en tiempo real sin degradar la experiencia de registro. Un código IAE no encontrado (HTTP 404) se traduce de inmediato en un mensaje de ayuda al usuario, antes de que la cuenta quede en estado pendiente.

Los ERPs y SaaS contables que clasifican a sus clientes por sector económico necesitan mantener su tabla maestra de códigos CNAE actualizada. El catálogo INE 2025 introdujo nuevos epígrafes, fusiones y cambios de denominación respecto al CNAE 2009 —y las actualizaciones menores pueden llegar en cualquier momento.

El endpoint GET /api/v1/search requiere un término de búsqueda de al menos 2 caracteres y no expone un volcado de catálogo completo. El patrón real para refrescar el maestro semanalmente es iterar por prefijo alfabético: llamar con q=a, q=b, … q=z, q=0 … q=9 (36 peticiones de hasta 50 resultados cada una) y deduplicar los registros por cod_cnae client-side. Sobre el plan Profesional (2.000 req/día) el sync semanal completo supone menos del 2 % del cupo diario.

Nota técnica: /api/v1/search no implementa filtro por fecha de modificación (updated_since). El patrón recomendado es diff completo client-side: descargar con prefijos, comparar el campo last_updated o el hash del registro contra la copia local y aplicar upsert solo en las filas que han cambiado.