Verifactu API: how to integrate Verifactu into your software or ERP

A Verifactu API is the piece that connects your invoicing system to the Spanish Tax Agency (AEAT): it generates a record for every invoice, chains it to the previous one and sends it to the AEAT. The AEAT doesn't publish a conventional REST API. It publishes a web service with its own XML schemas. Your system can connect to it directly or through an intermediary that offers its own API. If you invoice from in-house software or a custom ERP, that integration, and the declaration that it complies, is your responsibility.

With an off-the-shelf invoicing product, the vendor does the work. If your invoices come out of a system built for your company, an ERP customised over the years or an old application nobody wants to touch, there's no update to download: someone has to design the integration.

This article is for that situation. It's a technical guide to help you decide, not tax advice.

What Verifactu requires from an invoicing system

Royal Decree 1007/2023 sets the requirements for invoicing systems in Spain. For whoever has to integrate them, they come down to five obligations:

• One billing record per invoice. A structured summary of the invoice data, which the AEAT calls a registration record, plus a cancellation record when one has to be voided.
• A chained hash. Each record carries a hash calculated from its own data and the previous record's hash. If anyone alters an old record, the chain breaks. The algorithm is published in the AEAT technical documentation.
• A QR code on the invoice, which lets the customer check the record on the AEAT website.
• Submit or retain. In VERI*FACTU mode, records are sent to the AEAT immediately. Outside it, they're kept in the system itself, electronically signed and with an event log.
• A declaration of conformity (declaración responsable) from the system's producer, certifying that it complies.

Verifactu deadlines: when your system has to be ready

Following the extension in Royal Decree-law 15/2025, according to the Spanish Tax Agency:

• Entities that file Corporate Income Tax: before 1 January 2027.
• All other taxpayers: before 1 July 2027.

An in-house integration isn't a two-week job. It needs design, development, testing in the AEAT pre-production environment and a period running alongside real invoices. If your deadline is January, the margin is already tight.

Three ways to integrate Verifactu into your software

1. Connect directly to the AEAT web service

Your system builds the records in XML following the official schemas, calculates the hash, authenticates with an electronic certificate and calls the AEAT web service.

• For: no third-party dependency and no per-invoice fees.
• Against: you maintain the certificate, track schema changes and handle validation errors yourself.
• When I'd choose it: when there's a technical team that will keep maintaining the system and invoice volume justifies it.

2. Use an intermediary's Verifactu API

Several providers offer their own API, usually REST and JSON, which handles the XML conversion, the hash and the submission. Your system only sends them the invoice data.

• For: faster integration, and the provider keeps up with regulatory changes.
• Against: you add an external dependency that all your invoicing data passes through, with its own costs and terms.
• When I'd choose it: when the system is small, the team can't take on tax-related maintenance or the deadline is tight.

3. Stop invoicing from your own system

Sometimes the sensible move is for your system to keep handling orders and customers while invoices are issued by a product that's already compliant and integrated with it. The AEAT also offers a free invoicing application for businesses that meet its conditions.

• When I'd choose it: when invoicing isn't what sets the company apart. As I argued in software should fit the business, build custom where it adds value, not out of habit.

Architecture of a Verifactu API integration

Whichever route you take, an integration that works has the same shape:

1. Issue the invoice with its final number and data. From this point on, the invoice isn't edited: it's corrected or cancelled.
2. Generate the registration record with the fields required by the AEAT record design.
3. Calculate the hash using the previous record's hash, and store it with the record in the same transaction as the invoice.
4. Generate the QR code and include it in the PDF or printed invoice, with the required wording.
5. Queue the submission instead of doing it inside the user's request. If the AEAT is slow or doesn't respond, the invoice already exists and the submission is retried.
6. Store the response to each submission (accepted, accepted with errors or rejected) and the status of every record.
7. Review rejections, with a screen where someone in finance can see what failed and fix it.

Steps 5 to 7 are the ones most often forgotten. A direct call to the web service works in the demo and fails on day one with a poor connection. In Gustela CRM, a commercial CRM I built, every outbound message goes through a queue with a status, a date and rules applied before queuing. A tax integration needs exactly the same pattern.

Before going live, the AEAT provides a pre-production portal for testing submissions. Use it with real, anonymised invoices, including corrective and cancelled ones, not just the happy path.

Custom or legacy software: who certifies it?

This is the part that surprises people most. The AEAT is clear about it in its FAQ on the declaration of conformity:

• If the software was developed by the company itself, the company has to certify it.
• If a third party modifies or extends a system, those changes aren't covered by the original producer's certification and need their own certification.

In practice: if your ERP was customised by a supplier that's no longer around, or your team added invoicing to an internal application, someone has to own the integration and sign the declaration. With legacy systems, it's usually the moment to decide whether to adapt what's there or to separate invoicing from everything else.

What breaks before you ever reach the API

Most of the problems I see aren't in the submission. They're in the data that reaches the invoice: duplicated customers with different tax IDs, prices recalculated at invoicing time, invoices edited after they were issued. A chained hash forgives none of that.

I went into this in Verifactu software: the problem isn't the invoices, it's the data. The underlying idea is to store what was agreed, not what's true today. That's what Lantilla.com, an online photography shop I built, does: every order keeps a snapshot of the title, variant and price at the moment of purchase.

The API is the easy part. The hard part is making sure what you send it is true from the start.

Verifactu API FAQ

Is there an official Verifactu API?

The AEAT publishes a web service with its WSDL, the XML schemas, the record designs and a validations and errors document. It isn't a REST API with JSON. The "Verifactu APIs" advertised as REST come from providers acting as intermediaries with that service.

Do invoices have to be sent to the AEAT in real time?

No. What's mandatory is that the system meets the requirements. VERI*FACTU mode sends each record immediately and, in exchange, doesn't require records to be signed or retained in the system. The other mode doesn't submit, but requires electronically signed records and an event log.

Do I need an electronic certificate to connect to the AEAT?

Yes. Submissions are authenticated with an electronic certificate, belonging either to the taxpayer or to whoever acts on its behalf as a representative or authorised collaborator.

We built our own invoicing software. What do we have to do?

Adapt it to the requirements, test it and issue the declaration of conformity as its producer. If a third party developed it, agree in writing who certifies what.

How long does it take to integrate Verifactu into a custom ERP?

It depends more on how tidy your invoicing data is than on the API. With a clean system, the integration is contained. With invoices edited after issue or numbering done by hand, that has to be fixed first.

If your invoicing runs on in-house, custom or legacy software and you're not sure how to adapt it, my custom software page explains how I work: I review what's there, propose the simplest of the three routes and, if needed, build the integration.