ZATCA QR Code Requirements & TLV Encoding: A Technical Implementation Guide

The Zakat, Tax and Customs Authority (ZATCA) in Saudi Arabia mandates QR codes on electronic invoices to adhere strictly to the TLV (Tag-Length-Value) encoding standard. This encoding method ensures data compactness, determinism, and readability in both simulation and production environments of the Fatoora system. TLV encoding utilizes a 1-byte identifier for the data field, known as the "Tag," followed by the length of the value in bytes, and then the raw UTF-8 byte value.

For Phase 1 invoicing, which covers basic simplified invoices, the QR code must contain specific mandatory tags. These include the seller's legal name, VAT registration number, timestamp of issuance in ISO 8601 UTC/Z format, invoice total including VAT, and the VAT amount charged. Phase 2 of the implementation introduces cryptographic extensions, requiring four additional tags: an invoice hash (SHA-256), a digital signature using ECDSA with a secp256k1 curve, the public key for signature verification, and the certificate signature of the Cryptographic Stamp Identifier (CSID).

To generate a compliant QR code in a Node.js/TypeScript environment, a utility function named "generateZATCAQRCode" is provided. This function takes an object with the required fields and their corresponding values, converts each value into a TLV-compliant binary format, and concatenates them into a single Base64-encoded string suitable for QR code generation.

Common errors leading to invoice rejections involve incorrect TLV structure, missing mandatory tags, mismatched timestamps, and improper character encoding for Arabic names. Precise adherence to these technical specifications is crucial to avoid penalties and ensure successful invoice processing.