Saudi Fatoora UUID & Hash (ZATCA Phase 2) Validator
Validate the authenticity, format, and checksum of Saudi Fatoora UUID & Hash (ZATCA Phase 2).
About Saudi Fatoora UUID & Hash (ZATCA Phase 2) Validation
The Fatoora project is Saudi Arabia's national e-invoicing platform governed by the Zakat, Tax and Customs Authority (ZATCA). Phase 2 (Integration Phase) mandates that every tax invoice is digitally signed using X.509 certificates and contains a sequential cryptographic hash tying it to the preceding invoice.
The specification requires a canonical UUID v4 (`8-4-4-4-12` hex characters) inside `<cbc:UUID>` of UBL 2.1 XML, and a Base64-encoded SHA-256 Invoice Hash (44 characters) in `<ext:UBLExtensions>`, enabling tamper-evident verification by ZATCA APIs.
Anatomy & Structure of Fatoora QR Code (TLV Base64) — Saudi Arabia
The e-Invoicing QR Code encodes 5 mandatory tags in binary TLV format:
| Position | Field | Length | Meaning & Rule | Example |
|---|---|---|---|---|
| Tag 1 | Seller Company Name | Variable | Seller legal name in UTF-8 | Acme Corp |
| Tag 2 | Seller VAT Number | 15 digits | 15-digit VAT number starting and ending in 3 | 300123456700003 |
| Tag 3 | Invoice Timestamp | ISO 8601 | Timestamp in format YYYY-MM-DDTHH:mm:ssZ | 2024-01-15T12:00:00Z |
| Tag 4 | Total Invoice Amount | Decimal | Invoice total amount including VAT | 115.00 |
| Tag 5 | VAT Total Amount | Decimal | Highlighted VAT tax amount | 15.00 |
TLV and Base64 Encoding (ZATCA Fatoora Phase 1/2)
Fiscal QR Code encoding algorithm:
- 1. For each fiscal field (1 to 5), write tag number in 1 byte.
- 2. Write length in UTF-8 bytes in 1 byte.
- 3. Write the UTF-8 encoded text bytes.
- 4. Concatenate all blocks and encode the binary buffer in Base64.