Conector AEAT para importación: declaración H1 con certificado electrónico
Módulo para integrar en tu software que prepara la declaración de importación H1 según los esquemas de la AEAT, la envía con el certificado del declarante y sigue el estado del despacho.
Conectar tu software con los servicios web de aduanas de la AEAT obliga a construir el mensaje exacto que piden los esquemas oficiales, identificarse con el certificado de cada cliente e interpretar respuestas que llegan en momentos distintos. Este conector AEAT para importación resuelve esa parte: prepara la declaración H1 (mensaje CC415A), la envía con el certificado del declarante y consulta el estado del despacho por MRN.
Para quién es
Empresas de software aduanero, representantes aduaneros con equipo de desarrollo y transitarios que construyen su propio sistema.
Qué resuelve un conector AEAT para importación
- Documentación técnica extensa. Te ahorra traducir las guías y los esquemas oficiales a código.
- Certificados de varios clientes. Cada envío usa el certificado de su cliente, sin mezclarlos.
- Errores de entorno. Impide enviar a producción desde un entorno de pruebas.
- Respuestas difíciles de tratar. Distingue el MRN, el error de formato y el rechazo de la AEAT.
Qué hace
- Construye la declaración H1 según los esquemas oficiales de la AEAT y la comprueba antes de enviarla.
- La envía con el certificado del declarante, con los entornos de preproducción y producción separados, incluidos los de sello electrónico.
- Interpreta la respuesta: MRN asignado, error de formato (CD917A), rechazo funcional (CC456A) o error del servicio.
- Consulta cada cierto tiempo el estado del despacho (levante concedido, pendiente o no concluyente). Reintenta solo cuando el fallo es temporal y aparta las declaraciones que no dan una respuesta clara.
- Guarda los certificados cifrados, oculta el MRN en los registros y avisa antes de que caduque un certificado.
- Exige que una persona apruebe cada versión de la declaración antes de enviarla y permite conciliar el MRN a mano.
Beneficios
- Tu equipo dedica el tiempo a la operativa y no a la conexión con la AEAT.
- Reduces el riesgo de enviar una declaración de pruebas a producción, o con el certificado de otro cliente.
- Ninguna declaración sale sin que alguien la haya revisado.
Contexto del sector
Datos generales del sector con su fuente pública. No son resultados de este producto.
- La AEAT cerró el 14 de octubre de 2025 el anterior sistema de importación mediante DUA, y la declaración H1 quedó como único sistema para declarar importaciones. Fuente: Agencia Tributaria, «Novedades de Aduanas 2025», 2025.
Qué recibes según la modalidad
Precio a consultar según modalidad y alcance. El soporte para integrarlo y el mantenimiento se contratan aparte.
- El código del módulo, con la documentación para adaptarlo a tu modelo de datos.
- Los esquemas oficiales que usa y ejemplos de integración.
- Garantía frente a defectos durante el periodo pactado.
- Todo lo anterior, con derecho a adaptarlo y mantenerlo dentro de tu producto.
- Derecho a integrar el activo en un producto comercial propio, identificado en el contrato.
- Derecho a distribuirlo como parte de ese producto a tus clientes, sin pedir autorización por cada instalación y sin límite de clientes finales, salvo pacto.
- No incluye revenderlo ni sublicenciarlo por separado.
- No es exclusiva, salvo pacto.
- El mantenimiento, el soporte y las adaptaciones se contratan aparte.
Ficha técnica
Lenguaje y entorno de ejecución: TypeScript 5.9 sobre Node.js.
Frameworks: El conector no depende de un framework web: usa el cliente HTTPS de Node.js. Acceso a datos con Prisma 7.10.
Base de datos: PostgreSQL.
Sistemas operativos: Servidor con Node.js.
Idiomas de la interfaz: Español.
Infraestructura necesaria:
- PostgreSQL.
- Certificado electrónico del declarante o del representante aduanero en P12 o PFX.
- Salida a internet hacia los servicios web de la AEAT.
- Planificador de tareas periódicas (cron) para consultar el estado de los despachos.
Despliegue privado: Funciona en tu infraestructura sin servicios de terceros, salvo los servicios web de la AEAT, que son el objeto del módulo.
Bibliotecas principales:
| Biblioteca | Versión | Licencia |
|---|---|---|
| node-forge | 1.4.0 | BSD-3-Clause OR GPL-2.0 |
| @prisma/client | 7.10.0 | Apache-2.0 |
| @prisma/adapter-pg | 7.10.0 | Apache-2.0 |
| pg | 8.23.1 | MIT |
| zod | 3.25.76 | MIT |
Dependencias con condiciones de licencia específicas:
- node-forge 1.4: BSD-3-Clause OR GPL-2.0.
Compatibilidades e integraciones: AEAT, servicio web CC415A V1 (declaración de importación H1, SOAP con certificado de cliente) y servicio ConsultaImportacionV2 (estado del despacho por MRN), con los entornos de preproducción y producción, incluidos los de sello electrónico. Interpreta las respuestas CD917A y CC456A.
Condiciones de redistribución
El código propio admite integración en productos comerciales del licenciatario en las modalidades de módulo integrable, licencia de código y licencia OEM, en los términos del contrato. Solo node-forge tiene una licencia a señalar, doble (BSD-3-Clause OR GPL-2.0); ver la lista de la Ficha técnica. El resto de dependencias de producción tiene licencias permisivas.
Requisitos de instalación
Una aplicación Node.js con PostgreSQL, salida a internet hacia los servicios web de la AEAT y una tarea periódica para consultar el estado de los despachos. Necesitas el certificado electrónico del declarante o del representante aduanero.
Preguntas frecuentes
¿Puedo usarlo directamente con declaraciones reales?
Antes tienes que validarlo en el entorno de preproducción de la AEAT con tus propios datos. Un error en una declaración tiene consecuencias para el declarante, así que esa validación corre de tu cuenta.
¿Firma el XML?
No. La AEAT identifica al declarante por el certificado usado en la conexión. Confirma que tu caso no exige firma adicional.
¿Cubre exportación o tránsito?
No. Cubre la declaración de importación H1 y la consulta del estado del despacho.
¿El mantenimiento está incluido?
No. La AEAT publica nuevas versiones de sus guías y esquemas, y seguirlas forma parte del mantenimiento, que se contrata aparte, igual que el soporte.
Encajan con este activo
Solicitud
Solicita información sobre M-AEAT-01
Rellena el formulario con la referencia del activo y la modalidad que te interesa. Te respondo por escrito. Si necesitas revisar el código, marca la casilla del NDA y lo preparamos antes de enseñar nada.