TicketBAI QR — QR Data Format standard

Overview

TicketBAI is the invoicing-software regime of the Basque Country in Spain, a joint project of the three Haciendas Forales and the Basque Government ¹. Every invoice or receipt issued under it carries two printed elements: a 39-character TicketBAI identifier (TBAI-…) and a QR code holding an HTTPS URL of the issuing territory's checking service, with the invoice's identifier, series, number and total as parameters and a CRC-8 as the last parameter ¹ ². The duty reached all remaining taxpayers on 1 December 2022 in Álava and 1 June 2023 in Gipuzkoa, and Bizkaia phased it in through windows from 1 January 2024 to 1 January 2026, each territory with its own exemptions ⁶ ¹⁰ ¹⁵.

History

TicketBAI's stated basis is three OECD reports: 2013 on electronic sales suppression, 2017 on technological tools against tax evasion, and the report of 28 March 2019 on online cash registers ¹. A pilot with more than 40 companies ran in 2019 ¹³. Version 1.1 of the shared technical specification is dated 9 March 2020 ¹.

Each territory then legislated separately, under its own rules for corporate and personal income tax ¹. Each also set its own date, as Gipuzkoa's tax office puts it: "Cada Administración tributaria vasca establecerá la fecha a partir de la cual será exigible TicketBAI" ⁹.

Territory	Act creating the duty	Regulation	Order holding the QR specification	Voluntary from	Mandatory
Álava	Norma Foral 13/2021, 21 April ⁴	Decreto Foral 48/2021, 5 October ⁵	Orden Foral 802/2021, 27 December, Anexo V ⁴	1 January 2022 ⁶	1 April 2022 to 1 December 2022
Gipuzkoa	Norma Foral 3/2020, 6 November ⁷	Decreto Foral 32/2020, 22 December ⁸	Orden Foral 521/2020, 23 December, Anexo V, replaced by Orden Foral 53/2021 ⁷	1 January 2021 ⁸	1 July 2022 to 1 June 2023
Bizkaia	Norma Foral 5/2020, 15 July ¹¹	Decreto Foral 82/2020, 8 September ¹¹	Orden Foral 1482/2020, 9 September, amended by 2170/2020 and 274/2023 ¹¹	2022 and 2023 ¹²	1 January 2024 to 1 January 2026

Dates that moved

Álava. Decreto Foral 48/2021 set 1 April 2022 for collaborating tax advisers, 1 July 2022 for IAE heading 652.1 (retail medicines and health products) and all of Section 2, and 1 October 2022 for everyone else ⁵. Decreto Normativo de Urgencia Fiscal 9/2022, of 14 June, moved that last date to 1 December 2022 and exempted some individuals aged 60 or over ⁶ ²³.
Gipuzkoa. The calendar in force was set by Orden Foral 608/2021 of 9 November, which amended the original one and also exempted some individuals close to retirement age. It runs from 1 July 2022 (tax-management professionals) through 1 September 2022, 1 November 2022 and 1 April 2023 to 1 June 2023 ⁸. Since 1 June 2023 the duty applies to all taxpayers with economic activities in Gipuzkoa ¹⁰.
Bizkaia. The original date was 1 January 2022. A proposal announced on 19 July 2021 moved it to 1 January 2024 ¹⁴, enacted as a Norma Foral at the end of 2021 that extended the voluntary period to 31 December 2023 ¹². Norma Foral 8/2023 of 22 November then replaced the single date with windows ¹¹ ¹⁵.

Bizkaia windows under Norma Foral 8/2023

Bizkaia's obligation is the wider Batuz system, of which TicketBAI is one of three parts ¹².

Date	Who ¹⁵
1 January 2024	Corporate-tax payers that are not micro, small or medium enterprises
1 July 2024	Individuals, income-attribution entities and SMEs in industry, construction, transport, and financial, legal, insurance, rental, health and other professional activities
1 January 2025	Wholesale; SME companies in retail, hospitality, repairs, hairdressing and personal services
1 July 2025	Individuals and attribution entities in that same retail and services group
1 January 2026	Exempt and partially exempt entities, non-profits under Norma Foral 4/2019, and the rest, including agriculture, fishing, education and culture

Technical specification

The symbol is an ordinary QR Code carrying a URL QR payload. The content below is common to the three territories; only the URL changes ¹.

TicketBAI identifier

Fixed length of 39 characters, in the generic form TBAI-NNNNNNNNN-DDMMAA-FFFFFFFFFFFFF-CRC ².

Part	Length	Content
`TBAI`	4	Fixed uppercase text
NIF	9	The issuer's tax number, in its official format, as in the TicketBAI file
Date	6	Issue date as DDMMAA, zero-padded, from `FechaExpedicionFactura`
Signature	13	First 13 characters of `SignatureValue` in the signed TicketBAI file
CRC	3	CRC-8 of the first 36 characters, decimal, zero-padded

Four hyphens separate the five parts ². Because part of the signature is printed on the invoice, signing always comes before generating the invoice image ¹.

The authorities' sample is TBAI-00000006Y-251019-btFpwP8dcLGAF-237. The Álava annex states that its NIF and signature are not valid and only show the format ².

QR parameters

The specification sets error-correction level M and UTF-8 ¹. Invalid characters in the URL or its parameters must be URL-encoded ¹.

Key	Value
`id`	The 39-character identifier
`s`	Invoice series, matching `SerieFactura`
`nf`	Invoice number, matching `NumFactura`
`i`	Total including VAT, matching `ImporteTotalFactura` in both value and format
`cr`	CRC-8, always last

The specification's sample payload ¹:

https://batuz.eus/QRTBAI/?id=TBAI-00000006Y-251019-btFpwP8dcLGAF-237&s=T&nf=27174&i=4.70&cr=007

Base URL per territory

Territory	Production QR URL	Notes
Álava	`https://ticketbai.araba.eus/tbai/qrtbai/`	Current Anexo V and technical page ² ⁴; the 2020 v1.1 specification instead gives `https://ticketbai.araba.eus/TBAI/QRTBAI`, without the slash ¹
Bizkaia	`https://batuz.eus/QRTBAI/`	Trailing slash counts for the CRC ¹; QR test tool at `pruebatuz.bizkaia.eus/B4PEQR0C/test` ¹⁶
Gipuzkoa	`https://tbai.egoitza.gipuzkoa.eus/qr/`	Trailing slash counts for the CRC ³; test environment `https://tbai.prep.gipuzkoa.eus/qr/` ¹⁷

The Álava discrepancy matters: the slash and case are inside the checksummed string, so the two forms give different cr values. The legal annex is the later text, and it is the one Álava's technical page still shows ² ⁴.

CRC-8

The same routine serves both checksums ¹ ²:

Parameters: polynomial x⁸ + x² + x + 1, Init 0, RefIn false, RefOut false, XorOut 0. Output is a decimal string padded to three digits (%03d in the published code). The authorities publish a Java reference with its 256-entry table ².
For the identifier: the input is the first 36 characters, UTF-8.
For the QR: the input is the content built so far, UTF-8, so neither cr nor the & that attaches it is included. The base URL is part of the input, which is why the specification states whether its slash counts ¹.
Purpose: detecting accidental changes ¹. It is a checksum, not a security feature. A CRC computed from the content proves nothing about authenticity; the check against the authority's records does that.

Verified in this research with a bitwise implementation of those parameters: the first 36 characters of the sample identifier give 237, and the sample URL gives cr=007, both matching the published values ¹ ².

Same parameters on (structurally illustrative)	`cr`
`https://batuz.eus/QRTBAI/` (published)	007
`https://ticketbai.araba.eus/tbai/qrtbai/`	094
`https://ticketbai.araba.eus/TBAI/QRTBAI`	204
`https://tbai.egoitza.gipuzkoa.eus/qr/`	010

Open point. The specification does not say with an example whether the CRC runs over the percent-encoded or the raw form, and the published sample has nothing to encode. One vendor SDK says the signature part can contain Base64 + and /, encodes them, and computes the CRC over the encoded URL, while marking that reading as pending confirmation with the authorities' test tools ²². That is a third-party statement, so implementers should confirm it with the test tool.

Size and placement

The QR must be from 30×30 mm to 40×40 mm. A 6 mm white margin on all four sides is recommended ¹.
Computed: the sample URLs need version 6 (41 × 41 modules) at level M, with 95 to 110 characters. That gives 0.73 mm per module at 30 mm and 0.98 mm at 40 mm.
In portrait, identifier and QR go at the very bottom; in landscape, at the far right. The identifier sits on one line above the QR, and it may wrap, breaking after a hyphen ².
On a multi-page invoice, both go on the last page ⁹.
The taxpayer is responsible for legibility: an invoice with an unreadable QR is not valid for TicketBAI purposes ¹.

Behind the QR

Before the invoice image exists, the software generates an XML file in UTF-8, and signs it ¹. Each file records the previous invoice's series, number, date and first 100 characters of its SignatureValue, which chains the invoices ¹. In Gipuzkoa's text, which is the one read for this page, the signature must be XAdES enveloped, class EPES; enveloping and detached forms are not accepted ¹⁸. Each territory publishes its own policy identifier: Álava at ticketbai.araba.eus/tbai/sinadura/ ⁴, Gipuzkoa at www.gipuzkoa.eus/ticketbai/sinadura ¹⁹, and Bizkaia as "TicketBAI electronic signature 1.2" ¹⁶.

Delivery differs by territory:

Gipuzkoa: the file goes to the tax authority simultaneously with issue (Decreto Foral 32/2020, art. 14) ⁸. Deferred sending needs an authorisation for proven lack of coverage ⁸.
Álava: the file also goes simultaneously with issue ²⁰.
Bizkaia: the invoice data goes into the LROE ledger in the tax office's online portal, and non-immediate submission is allowed, generally until the 25th of the month after the quarter, or 31 January for the last quarter. The Zergak article adds that in practice the software sends immediately ¹³.

Checking a code

Scanning opens the territory's service. Álava says the code "certifica que la factura ha llegado a la Hacienda Foral de Álava", and a customer can report a suspected undeclared invoice ²⁰. In Gipuzkoa the check needs no identification, and the identifier can be typed in instead. If the invoice names a recipient, the page asks for a Gipuzkoataria login ²¹.

Use cases

Retail and hospitality receipts. TicketBAI focuses on sectors selling to final consumers, largely for cash ¹.
Customer verification. Bizkaia counted more than 757,000 invoices checked by QR in 2025 in a table labelled 26 June 2025, against 365,187 in 2024 and 88,309 in 2023 ²⁴.
Fraud reporting. Álava offers a citizen channel for "Sin Qr", "Qr erróneo" or "Sin Ticket" ⁴; Gipuzkoa asks for a photo of the whole invoice if the check shows a red message ²⁵.
Free invoicing tools. Bizkaia's "Haz tu factura" app issues PDF invoices with the QR and identifier, with 1,930,624 reported as of 30 December 2025 ¹³ ²⁴. Álava publishes FakturAraba ⁴.
Spanish B2B e-invoicing. The format annex of Orden HAC/1028/2026, the state's public e-invoicing solution, has a reference typed QR, described VERIFACTU or TICKETBAI, and carrying that QR's URL ²⁶.

Not every document carries it. In Bizkaia, proformas and pre-tickets may never include the identifier or QR ²⁷, and duplicates reuse the original's QR and identifier ²⁸. Unreadable-format electronic invoices to businesses or public bodies, such as Facturae, skip the QR but keep the identifier ²⁸.

Implementations

No official reference library was found beyond the published CRC routine. These are community projects:

Barnetik/tbai-php-lib: PHP, 42 stars, last commit October 2026. Generates, signs and sends TicketBAI invoices.
OCA/l10n-spain: Odoo localisation, 590 stars. The 16.0 branch lists six l10n_es_ticketbai* modules; l10n_es_ticketbai_api last changed in May 2026.
codesyntax/pytbai: Python, 4 stars, last commit October 2026. Kept despite the low star count because it is the only standalone Python library found.
squareetlabs/ticketbai-sdk: Java, 0 stars, last commit October 2026. Covers all three territories and returns the identifier and QR URL, leaving image generation to the caller ²². Listed for its documented handling of URL encoding.
ticketbai Ruby gem: its TbaiQr class builds the Bizkaia URL with the same five parameters, and documentation states no source repository.

No dedicated decoder was found. The payload is a plain URL, so a generic reader such as zxing/zxing reads it (Java, 34,185 stars as recorded on the URL QR page). Validating it then means splitting the parameters and recomputing both CRCs. Only the authority's service can confirm that the invoice exists.

Comparison

Spain VeriFactu QR: the closest relative, and a legally separate regime. Spain's tax agency says TicketBAI, in its forms, has content "similar a la modalidad VERI*FACTU" ²⁹. Taxpayers under foral direct-tax rules fall outside the Spanish regulation, which reaches those territories only for taxpayers domiciled in common territory ²⁹. Verifactu adaptation dates are 1 January 2027 for corporate-tax payers and 1 July 2027 for others ²⁹. The choice is set by tax residence, not preference. A company's own invoices follow its own administration's system in mixed trade ²⁹.

Plain URL QR: TicketBAI uses the same mechanism, but fixes the host per territory, the parameter names and order, the error-correction level and the printed size. It also adds a checksum, which a general URL code lacks.

The code itself carries no TLV structure or signature of its own. Integrity in the code is a CRC-8 against accidental error, and authenticity rests on the signed XML held by the authority, of which 13 characters are printed.

Fun facts

A TicketBAI code is checksummed twice: the identifier has its own CRC, then the whole URL, including that CRC, gets another ¹.
Bizkaia's QR checks grew almost ninefold from 2023 to 2025 ²⁴.

Status

Active, and fully phased in. Gipuzkoa's duty has applied to all taxpayers since 1 June 2023 ¹⁰. Bizkaia closed its fifth and final window on 1 January 2026, with almost 70,000 taxpayers in Batuz ²⁴.

Current signals of maintenance:

Álava updated its registration validations (v13) on 22 July 2026 ⁴.
Bizkaia's TicketBAI servers change their SSL/TLS certificate chain on 24 November 2026 ¹⁶.
Bizkaia's Decreto Foral 100/2025 of 13 November created a new TicketBAI exemption for exempt and partially exempt corporate-tax entities and non-profits ¹¹.
Orden HAC/1028/2026 of 2 October names TICKETBAI in the state's e-invoicing format ²⁶.

Exemptions differ. Álava exempts some individuals aged 60 or over who were active on 31 December 2021, subject to further conditions ²³; Gipuzkoa exempts some close to retirement ⁸; Bizkaia has no age-based exemption, but has one for income up to 2,000 euros a year under conditions ²⁷.

Penalties. Gipuzkoa's unofficial consolidated text gives a fine of 20 % of the previous year's turnover, with a minimum of 20,000 euros, for failing to use compliant software (Norma Foral 2/2014, art. 133 bis) ⁷.

The XML format has moved on (Bizkaia lists schema 1.2.2, dated 19 October 2023 ¹⁶), while the QR rules in the 2020 specification and the later annexes match, apart from the Álava URL above.

Sources

1 Especificaciones funcionales y técnicas del sistema TicketBAI 1.1 — Diputaciones Forales de Álava, Bizkaia y Gipuzkoa and Basque Government, 2020 2 Anexo V: Especificaciones del código TicketBAI y del código QR — Diputación Foral de Álava, file dated March 2022 3 Anexo V: Especificaciones del código TicketBAI y del código QR — Diputación Foral de Gipuzkoa, accessed 2026 4 Documentación técnica TicketBAI — Diputación Foral de Álava, accessed 2026 5 Decreto Foral 48/2021, de 5 de octubre — BOTHA no. 117, 13 October 2021 6 1.9. ¿Desde cuándo se aplica TicketBAI? — Diputación Foral de Álava, accessed 2026 7 Normas Forales que regulan la Obligación TicketBAI — Diputación Foral de Gipuzkoa, unofficial consolidated text, accessed 2026 8 Decreto Foral 32/2020, de 22 de diciembre — Diputación Foral de Gipuzkoa, unofficial consolidated text, accessed 2026 9 ¿Desde cuándo se aplica TicketBAI? — Diputación Foral de Gipuzkoa, accessed 2026 10 Calendario TicketBAI — Diputación Foral de Gipuzkoa, accessed 2026 11 Normativa Batuz — Diputación Foral de Bizkaia, accessed 2026 12 Actualidad Normativa Tributaria, no. 11 — Basque Government, November 2023 13 Iñigo Egia Ossorio, article on the Batuz project — Zergak no. 70, Basque Government, 2025 14 Batuzen derrigortasunaren atzerapena — Diputación Foral de Bizkaia, 19 July 2021 15 Implantación definitiva — Diputación Foral de Bizkaia, accessed 2026 16 Documentación técnica Batuz — Diputación Foral de Bizkaia, accessed 2026 17 Guía de entorno de pruebas de TicketBAI — Diputación Foral de Gipuzkoa, accessed 2026 18 Orden Foral 521/2020, de 23 de diciembre, Anexo III — Diputación Foral de Gipuzkoa, unofficial consolidated text, accessed 2026 19 Documentación y normativa TicketBAI — Diputación Foral de Gipuzkoa, accessed 2026 20 Información general TicketBAI — Diputación Foral de Álava, accessed 2026 21 Consulta QR -cliente- — Diputación Foral de Gipuzkoa, accessed 2026 22 squareetlabs/ticketbai-sdk README — Squareet Labs (third party), accessed 2026 23 Decreto Normativo de Urgencia Fiscal 9/2022, de 14 de junio — BOTHA no. 73, 22 June 2022 24 Bizkaiko Foru Aldundiak BATUZen ezartzeko prozesua amaitu du — Diputación Foral de Bizkaia, 30 December 2025 25 Sin QR o QR erróneos — Diputación Foral de Gipuzkoa, accessed 2026 26 Orden HAC/1028/2026, de 2 de octubre — BOE no. 247, 5 October 2026 27 Preguntas frecuentes Batuz — Diputación Foral de Bizkaia, accessed 2026 28 TicketBAI: qué es Batuz, v1.0 — Diputación Foral de Bizkaia, accessed 2026 29 Preguntas frecuentes: cuestiones generales, ámbitos de aplicación — Agencia Tributaria, accessed 2026

Deployments

No country reports mention this standard by name.