Skip to main content

TicketBAI in the Basque Country: Bizkaia, Gipuzkoa and Álava/Araba

TicketBAI is the mandatory e-invoicing system for all three Basque foral territories. Each Diputación Foral (Provincial Council) runs its own receiving platform, its own endpoints, and has its own enforcement dates. Frihet supports all three territories with automatic ZIP code detection.

Why three separate systems​

The Basque foral territories have full fiscal autonomy. Bizkaia, Gipuzkoa and Álava/Araba designed technically compatible systems — same XAdES signature standard, same SHA-256 chaining, same QR — but with separate receiving infrastructure. Whether your company is in Bilbao or Vitoria-Gasteiz determines which Hacienda Foral you report to and which endpoint Frihet uses for submission.

Automatic detection by ZIP code​

Frihet identifies the foral territory from the ZIP code in your fiscal profile:

PrefixTerritorySystemHacienda Foral
48xxxBizkaiaBATUZHacienda Foral de Bizkaia
20xxxGipuzkoaTicketBAI GipuzkoaHacienda Foral de Gipuzkoa
01xxxÁlava/ArabaTicketBAI ÁlavaHacienda Foral de Álava

If your ZIP code does not start with any of these prefixes, the TicketBAI section does not appear in Settings. Navarra (31xxx) has its own system under the Hacienda Foral de Navarra and is not included in this version.

Mandatory elements in every TicketBAI invoice​

Regardless of territory, each TicketBAI invoice must contain:

  • XML signed with XAdES-BES using the taxpayer's digital certificate
  • SHA-256 chained hash with the immediately preceding invoice (issuer|series|number|date|amount|previousHash)
  • TBAI identifier assigned by the Hacienda Foral after validating the submission
  • QR code generated from the actual TBAI identifier returned by the authority (never generated internally)

The chain is inviolable: altering one record invalidates the entire subsequent chain.

Bizkaia — BATUZ​

BATUZ is the Hacienda Foral de Bizkaia system. Unlike Gipuzkoa and Álava, it uses SOAP with custom HTTP headers instead of REST.

Endpoints​

EnvironmentURL
Sandboxhttps://pruebasarqueo.bizkaia.eus/N3B4000M/aurkezpena
Productionhttps://sarrerak.bizkaia.eus/N3B4000M/aurkezpena

BATUZ-specific headers​

The Bizkaia SOAP service requires custom HTTP headers not used by other systems:

eus-bizkaia-n3-version: 1.0
eus-bizkaia-n3-idoperacion: {unique UUID per submission}
eus-bizkaia-n3-nif: {issuer NIF}
eus-bizkaia-n3-tipoComunicacion: A00
Content-Type: application/octet-stream; charset=UTF-8

Frihet manages these headers automatically in its BATUZ submission Cloud Function. No additional configuration is required.

Expected response​

BATUZ returns a SOAP result with:

  • CSV — Secure Verification Code for the taxpayer
  • IdentificadorTBAI — unique identifier for the invoice in Bizkaia
  • Estado — Correcto, AceptadoConErrores or Incorrecto

Frihet stores the CSV and IdentificadorTBAI in Firestore under invoices/{id}/tbai/submission and generates the QR from the real IdentificadorTBAI. If BATUZ returns an error status, the invoice is marked as pending correction.

Mandatory dates in Bizkaia​

Taxpayer groupFrom
Large taxpayers (turnover > €6M)1 January 2022
All other businesses and self-employed1 January 2023
Invoicing software (technical compliance)1 January 2022

Gipuzkoa — TicketBAI REST​

The Hacienda Foral de Gipuzkoa uses a REST API instead of SOAP, which simplifies technical integration.

Endpoints​

EnvironmentURL
Sandboxhttps://tbai-z.prep.gipuzkoa.eus/sarrerak/alta
Productionhttps://tbai-z.egoitza.gipuzkoa.eus/sarrerak/alta

Submission method​

POST /sarrerak/alta
Content-Type: application/xml; charset=UTF-8
Authorization: {client certificate in mTLS}

The request body is the TicketBAI XML signed with XAdES-BES. The response returns the IdentificadorTBAI and validation status in JSON.

Mandatory dates in Gipuzkoa​

Taxpayer groupFrom
Taxpayers in module estimation1 January 2022
Self-employed in simplified direct estimation1 October 2022
Remaining companies and self-employed1 July 2023

Álava/Araba — TicketBAI REST​

The Hacienda Foral de Álava also uses REST, with a similar structure to Gipuzkoa but its own domain.

Endpoints​

EnvironmentURL
Sandboxhttps://pruebas-ticketbai.araba.eus/TicketBAI/v1/facturas/
Productionhttps://ticketbai.araba.eus/TicketBAI/v1/facturas/

Submission method​

POST /TicketBAI/v1/facturas/
Content-Type: application/xml; charset=UTF-8

The response includes the validation status and the IdentificadorTBAI for accepted invoices.

Mandatory dates in Álava​

Taxpayer groupFrom
Large companies (> €6M)1 January 2022
All other taxpayers with economic activity1 January 2023

BYOC digital certificate​

TicketBAI requires signing with the taxpayer's own certificate, not a service certificate. Frihet implements a Bring Your Own Certificate (BYOC) model:

  1. Go to Settings → TicketBAI → Digital certificate.
  2. Upload the .p12 or .pfx file with the certificate password.
  3. Frihet encrypts the certificate with AES-256-GCM and stores it in Firestore. The encryption key does not leave the Cloud Functions environment.
  4. On each submission, Frihet decrypts the certificate in memory, signs the XML, and discards it without persisting the decrypted form.

Valid certificates for TicketBAI:

  • FNMT — Fábrica Nacional de Moneda y Timbre (individuals and legal entities)
  • Izenpe — Basque certification authority (recommended for foral taxpayers)
  • Other certificates recognized by the Haciendas Forales (ACCV, ANF, Camerfirma)
Certificate expiry

Certificates for legal entities expire. Frihet shows a warning 30 days before expiry. A signature with an expired certificate is rejected by the Hacienda Foral with an unrecoverable error. Renew the certificate before expiry and update it in Settings.

Testing in sandbox​

The sandbox allows integration verification without fiscal effects:

  1. Go to Settings → TicketBAI.
  2. The section only appears if your ZIP code is from a foral territory (48xxx, 20xxx, 01xxx).
  3. Click Test sandbox to send a test invoice to your Hacienda Foral's test environment.
  4. The result shows the verification CSV and IdentificadorTBAI if the test succeeds.

In sandbox you can submit without a real certificate to verify XML format and connectivity. For production, a certificate is mandatory.

Technical pipeline in Frihet​

Frihet runs the TicketBAI pipeline in Cloud Functions (europe-west1):

  1. XML construction — TicketBAI v1.2 conforming to the XSD schema of the relevant Hacienda Foral
  2. XAdES-BES signing — using the BYOC certificate decrypted in memory
  3. SHA-256 chaining — calculates previousHash from the last record in the same series
  4. Territory detection — routes to the correct endpoint (BATUZ SOAP, Gipuzkoa REST, Álava REST)
  5. Submission and validation — receives CSV + IdentificadorTBAI
  6. QR generation — from the real IdentificadorTBAI returned by the authority
  7. Persistence — CSV, QR, hash and status stored in Firestore

If submission fails, the invoice stays in pending_tbai status and Frihet retries automatically with exponential backoff.

Status check via MCP​

If you use the Frihet MCP server, the ticketbai_status tool returns the current status of any invoice:

ticketbai_status(invoiceId: string)
→ { invoiceId, status, csv, qrUrl, province, tbaiIdentifier, submittedAt }

status values: submitted, accepted, rejected, pending, no_submission_yet.

Frequently asked questions​

Is TicketBAI the same as VeriFactu? No. VeriFactu is the AEAT system for the rest of Spain. TicketBAI is the system of the Basque Haciendas Forales. If your company is in the Basque Country, you use TicketBAI. Both systems coexist but are independent and do not share data.

What if my company has offices in Bizkaia and Madrid? Invoices issued from the permanent establishment in Bizkaia go to BATUZ. Invoices issued from Madrid go to VeriFactu (AEAT). Frihet manages both systems based on the active fiscal profile on each invoice.

Does TicketBAI apply to self-employed? Yes. The system is mandatory for any taxpayer with economic activity in foral territory, whether an individual (self-employed) or a legal entity (company). Applicable document types and numbering series are the same.

Does the sandbox use real data? No. Each Hacienda Foral's sandbox is an isolated test environment. TBAI identifiers generated in sandbox have no fiscal validity and do not appear in the Hacienda's records.

Official references​