TicketBAI API FAQ

Answers on how to comply with TicketBAI in Álava, Bizkaia and Gipuzkoa with the Verifacti TicketBAI API: guarantor software, integration, testing, submission to each foral treasury, corrections and Batuz. What each territory’s rules say is on the TicketBAI page.

Integration

2 questions

Do I need a separate integration for TicketBAI or is it the same integration for both TicketBAI and Verifactu?

Why are there two different APIs to integrate with Verifactu and TicketBAI?
We decided to design two differentiated APIs, one for Verifactu and another for TicketBAI, largely following the structure of the official tax authority APIs.
This provides several advantages:
  • Consistency: the endpoints, fields, and error messages we present to our users are practically the same as those in the tax authority APIs.
  • Easier tax consultations: this similarity eliminates interpretations or biases stemming from an intermediary API, which streamlines communication with advisors and with the tax authorities themselves.
What does this mean for integration?
It is necessary to integrate with two different APIs.
However, in practice, after integrating with Verifactu, the subsequent TicketBAI integration usually requires only 10%-20% additional effort. This is because several calls coincide, and when they don't, they maintain a very similar structure.
For example, when creating an invoice, you will need two different JSONs, using one or the other depending on the target API.
What is shared is the NIF management API (NIF registration, representation form and webhooks): you integrate it once and it works for both APIs.

If I am in the SII, do I have to comply with TicketBAI?

Being in the SII does not exempt you from TicketBAI in any of the three territories: they are separate obligations. Who is obliged and from when is on the TicketBAI page.

Guarantor software and representation

3 questions

If I use the TicketBAI API, do I need to become a guarantor software (software garante)?

To comply with TicketBAI, the software that sends the invoicing records must be registered in the official Guarantor Software (Software Garante) list. That is, if a software uses Verifacti to integrate with the Provincial Tax Authorities, Verifacti must be a guarantor software (and it is), but the software that uses Verifacti does not need to be a guarantor software.
Although the law itself does not explicitly require the use of registered software, in practice it is essential. The generated XML files must include identifying data of the software according to its registration: name, version, developer entity, and TicketBAI license number. The latter is obtained upon completing the registration process.
Verifacti has already gone through this process and is a guarantor software. The registration process in the Basque Country requires the company that will send the records (Verifacti) to submit a technical report demonstrating compliance with TicketBAI requirements. Additionally, a responsible declaration must be submitted confirming regulatory compliance and assuming commitments in case of legal modifications affecting the system.
You can consult the official lists at the following links, where Verifacti appears as guarantor software (Bilbabit SL):

Is Verifacti guarantor software in all three territories?

Yes. Verifacti is registered as guarantor software with the foral treasuries of Álava, Bizkaia and Gipuzkoa. Registration is a listing, not an approval: no treasury approves or certifies software. Details per territory in TicketBAI in Álava, TicketBAI in Bizkaia and TicketBAI in Gipuzkoa.

How are certificates and representation managed with TicketBAI?

Signing and submission in compliance with TicketBAI
To comply with TicketBAI regulations, the invoicing system must generate an XML file for each transaction, digitally sign it, and submit it to the corresponding Provincial Tax Authority (Hacienda Foral). Our API takes care of everything: it generates the XML from the data in your call, chains it cryptographically to the previous one, signs it in compliance with the regulation and submits it to the tax authority of Álava, Bizkaia or Gipuzkoa as applicable.
You do not need to provide or register any certificate
Verifacti signs and submits TicketBAI files with its own qualified electronic certificate, acting as a third party issuing on behalf of the taxpayer (the XML files are submitted flagged as issued by a third party).
The only step: the representation model
Just as with Verifactu, before sending the first invoice to the production environment the NIF holder must sign a representation grant form authorising Verifacti to submit tax information on their behalf. It is the same document for all four tax authorities (AEAT, Álava, Bizkaia and Gipuzkoa) and it is handled only once per NIF: a signature completed from a test NIF also covers the same NIF in production.
It can be signed in two ways:
  1. Online signature (individuals / self-employed only): the NIF holder verifies their identity by video and signs from the browser, with no digital certificate required. It costs €2.90 + VAT per signing process. You can see the process step by step in the guide Online signing of the representation model.
  2. Signature with a digital certificate (individuals and legal entities): the pre-filled PDF is downloaded, signed with the issuing NIF's digital certificate and uploaded to Verifacti. It is free.
In both cases you can handle it from the Verifacti web interface (Settings → Representation for each NIF) or programmatically through the NIFs management API.
IMPORTANT: until the representation status is Correcto, the NIF cannot send invoices to the production environment.
You can find more detail on certificates and representation models in this FAQ entry.

Testing and pricing

2 questions

Can I test TicketBAI with the free account?

Yes. The free account includes the TicketBAI test environment, so you can do the integration at no cost. For the foral treasury test NIF, write to soporte@verifacti.com. To send invoices of real NIFs to the foral treasury you need a paid subscription.

Is TicketBAI included in the price?

Yes. TicketBAI has the same price as Verifactu, per NIF active in production: each NIF uses the TicketBAI API or the Verifactu API depending on where it is taxed, at no extra cost. A NIF registered with two treasuries counts as two NIFs. Rates on the pricing page and more in Do prices include TicketBAI?.

Submission and corrections by territory

4 questions

Which treasury does the API send each invoice to?

To the issuing NIF’s. When you register a NIF you choose the treasury it is linked to (alava, vizcaya or guipuzcoa), and the TicketBAI API sends its invoices to that foral treasury. The endpoint is the same in all three territories. The same NIF can be registered with several treasuries, each with its own API key (see the NIF management API documentation).

Does the response include the QR and the TicketBAI code?

Yes, straight away. The response of POST /ticketbai/create includes the QR in Base64 (qr), its URL (url) and the TicketBAI code (tbai), which are printed on the invoice. All fields in the documentation.

Can I correct a rejected invoice?

In Álava and Gipuzkoa, yes: with the SUBSANAR action of PUT /ticketbai/modify. In Bizkaia, no: the API offers no modification or correction, but it does offer cancellation with /ticketbai/cancel. Examples in correction and cancellation.

In Bizkaia, does the API file the Batuz LROE?

Yes, for issued invoices: it sends each one to the LROE (form 140 for individuals and form 240 for legal entities), with registration and cancellation. It does not send expenses or received invoices. More in Batuz and LROE.

Start integrating today

Try it for free with the test environment.

Test environment and test NIF includedSee pricing