Spanish AEAT import connector: H1 declaration over SOAP with a client certificate
A module to build into your software that prepares the H1 import declaration to the AEAT schemas, sends it with the declarant's certificate and tracks the clearance status.
Connecting your software to the customs web services of Spain's tax and customs agency (Agencia Estatal de Administración Tributaria, AEAT) means building the exact message the official schemas ask for, identifying yourself with each customer's certificate and interpreting responses that arrive at different times. This AEAT customs connector takes care of that part: it prepares the H1 declaration (message CC415A), sends it with the declarant's certificate and checks the clearance status by MRN.
Who it is for
Customs software companies, customs representatives with a development team and freight forwarders building their own system. It is built for import filings with Spain's AEAT.
What an AEAT customs connector solves
- Long technical documentation. You do not have to turn the official guides and schemas into code yourself.
- Certificates from several customers. Each submission uses its own customer's certificate, with no mix-ups.
- Environment errors. It stops a test environment from sending to production.
- Responses that are hard to handle. It tells an MRN apart from a format error and from a rejection by the AEAT.
What it does
- Builds the H1 declaration to the AEAT's official schemas and checks it before sending.
- Sends it with the declarant's certificate, with separate preproduction and production environments, including the electronic seal environments.
- Interprets the response: MRN assigned, format error (CD917A), functional rejection (CC456A) or service error.
- Checks the clearance status at regular intervals (release granted, pending or inconclusive). It retries only when the failure is temporary and sets aside declarations that do not get a clear answer.
- Stores certificates encrypted, masks the MRN in logs and warns you before a certificate expires.
- Requires a person to approve each version of the declaration before it is sent, and lets you reconcile the MRN by hand.
Benefits
- Your team spends its time on operations, not on the AEAT connection.
- You reduce the risk of sending a test declaration to production, or one sent with another customer's certificate.
- No declaration goes out without someone having reviewed it.
Industry context
General industry data with its public source. These are not results of this product.
- On October 14, 2025, the AEAT shut down its previous import system based on the DUA (Documento Único Administrativo, the single administrative document), and the H1 declaration became the only system for declaring imports. Source: Agencia Tributaria, "Novedades de Aduanas 2025" (customs updates for 2025), 2025.
What you get with each license
Price upon request, depending on license type and scope. Integration support and maintenance are contracted separately.
- The module code, with documentation to adapt it to your data model.
- The official schemas it uses, and integration examples.
- A warranty against defects for the agreed period.
- Everything above, with the right to adapt and maintain it inside your product.
- The right to embed the asset in a commercial product of your own, identified in the contract.
- The right to distribute it to your customers as part of that product, without asking for authorization for each installation and with no limit on end customers, unless otherwise agreed.
- It does not include reselling or sublicensing it on its own.
- It is not exclusive, unless otherwise agreed.
- Maintenance, support and adaptations are contracted separately.
Technical specifications
Language and runtime: TypeScript 5.9 on Node.js.
Frameworks: The connector does not depend on a web framework: it uses the Node.js HTTPS client. Data access with Prisma 7.10.
Database: PostgreSQL.
Operating systems: A server with Node.js.
Interface languages: Spanish.
Required infrastructure:
- PostgreSQL.
- The electronic certificate of the declarant or the customs representative, in P12 or PFX format.
- Outbound internet access to the AEAT web services.
- A scheduler for periodic tasks (cron) to check clearance status.
Private deployment: Runs on your infrastructure with no third-party services, apart from the AEAT web services, which are what the module connects to.
Main libraries:
| Library | Version | License |
|---|---|---|
| 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 |
Dependencies with specific license terms:
- node-forge 1.4: BSD-3-Clause OR GPL-2.0.
Compatibility and integrations: AEAT web service CC415A V1 (H1 import declaration, SOAP with a client certificate) and the ConsultaImportacionV2 service (clearance status by MRN), with the preproduction and production environments, including the electronic seal environments. It interprets the CD917A and CC456A responses.
Redistribution terms
The asset's own code can be embedded in the licensee's commercial products under the embeddable module, source code and OEM licenses, on the terms of the contract. Only node-forge has a license worth flagging, a dual license (BSD-3-Clause OR GPL-2.0); see the list in the Technical specifications. The other production dependencies have permissive licenses.
Installation requirements
A Node.js application with PostgreSQL, outbound internet access to the AEAT web services and a scheduled task to check clearance status. You need the electronic certificate of the declarant or the customs representative.
Frequently asked questions
Can I use it straight away with real declarations?
First you have to validate it in the AEAT preproduction environment with your own data. An error in a declaration has consequences for the declarant, so that validation is your responsibility.
Does it sign the XML?
No. The AEAT identifies the declarant by the certificate used for the connection. Check that your case does not require an additional signature.
Does it cover export or transit?
No. It covers the H1 import declaration and the clearance status check.
Is maintenance included?
No. The AEAT publishes new versions of its guides and schemas, and keeping up with them is part of maintenance, which is contracted separately, like support.
They fit with this asset
Request
Request information on M-AEAT-01
Fill in the form with the asset reference and the license type you're considering. I reply in writing. If you need to review code, tick the NDA box and we'll sign one before anything is shared.