ZATCA-QR-Code erklärt: die 9 TLV-Felder, Phase 1 vs. Phase 2 und wie Sie ihn prüfen
Von Zain Abbas, Kodenova · Aktualisiert am
Was der QR-Code eigentlich ist
Der QR-Code auf einer saudischen E-Rechnung ist weder ein Link noch ein Bild der Rechnung. Er ist ein kurzer, in Base64 kodierter Datenblock, den ein Smartphone ohne Internetverbindung lesen kann.
Die Daten darin folgen einem Format namens TLV: Tag, Length, Value. Jedes Feld besteht aus drei Teilen, die direkt aufeinander folgen:
- Tag: ein Byte, das angibt, um welches Feld es sich handelt (1 für den Namen des Verkäufers, 2 für die Umsatzsteuernummer usw.).
- Length: ein Byte, das angibt, wie viele Bytes der Wert belegt.
- Value: das Feld selbst, kodiert in UTF-8.
Alle Felder werden ohne Leerzeichen oder Trennzeichen aneinandergereiht, und die gesamte Bytefolge wird anschließend in Base64 kodiert. Der technische Leitfaden der ZATCA begrenzt die fertige Base64-Zeichenkette auf 700 Zeichen.
Die 9 TLV-Felder
| Tag | Feld | Beispielwert | Phase |
|---|---|---|---|
| 1 | Name des Verkäufers | Al Noor Trading | Phase 1 und 2 |
| 2 | Umsatzsteuernummer des Verkäufers | 300000000000003 | Phase 1 und 2 |
| 3 | Zeitstempel der Rechnung (Datum und Uhrzeit) | 2026-10-16T10:15:00Z | Phase 1 und 2 |
| 4 | Rechnungsbetrag inklusive Umsatzsteuer | 1150.00 | Phase 1 und 2 |
| 5 | Umsatzsteuerbetrag | 150.00 | Phase 1 und 2 |
| 6 | Hash der XML-Rechnung | SHA-256-Hash | Phase 2 |
| 7 | ECDSA-Signatur des Hashs | kryptografischer Wert | Phase 2 |
| 8 | Öffentlicher ECDSA-Schlüssel | kryptografischer Wert | Phase 2 |
| 9 | Signatur der ZATCA über den öffentlichen Schlüssel des Stempels | kryptografischer Wert | Phase 2, nur vereinfachte Rechnungen und zugehörige Gut- und Lastschriften |
Die Tags 1 bis 5 sind lesbarer Klartext. Die Tags 6 bis 9 sind kryptografische Daten; ein Decoder zeigt sie daher als kodierte Zeichenketten, nicht als Wörter.
Der Rechnungs-Hash in Tag 6 ist ein SHA-256-Hash der XML-Rechnung. Der Sicherheitsstandard der ZATCA erläutert, dass der Hash die UBL-Extensions, den Signaturblock und das QR-Element selbst ausschließt. Das ist logisch: Der QR-Code kann keinen Hash von sich selbst enthalten.
Phase 1 vs. Phase 2
Die ZATCA hat die E-Rechnung in zwei Phasen eingeführt, und der QR-Code hat sich mit ihnen verändert.
Phase 1 (Erzeugung) begann am 4. Dezember 2021. Rechnungen mussten mit einem konformen System erstellt werden, und vereinfachte Rechnungen (B2C) mussten einen QR-Code mit den fünf Grundfeldern tragen. Die Detailed Guidelines der ZATCA sagen ausdrücklich, dass in dieser Phase auf Standardrechnungen (B2B) kein QR-Code vorgeschrieben war.
Phase 2 (Integration) begann am 1. Januar 2023 und wird in Wellen umgesetzt. Steuerpflichtige werden nach Umsatzschwellen einbezogen. Gehört Ihr Unternehmen zur jüngsten Gruppe, lesen Sie unseren Beitrag zu Welle 25 für SAP Business One. In Phase 2 kommen die Tags 6 bis 9 hinzu, und die Regeln hängen von der Rechnungsart ab:
| Thema | Standardrechnung (B2B) | Vereinfachte Rechnung (B2C) |
|---|---|---|
| ZATCA-Ablauf | Freigabe, bevor die Rechnung an den Käufer geht | Meldung, innerhalb von 24 Stunden nach Ausstellung |
| Wer stempelt die Rechnung | Die ZATCA, bei der Freigabe | Ihr System, mit seiner eigenen CSID |
| QR-Code | Von der ZATCA in der Freigabeantwort hinzugefügt oder aktualisiert | Von Ihrem System mit allen 9 Tags erzeugt |
| Tag 9 | Nicht verwendet | Pflicht |
Der praktische Punkt bei B2B: Ihre gedruckte Rechnung oder Ihr PDF sollte den QR-Code verwenden, den die ZATCA nach der Freigabe zurückgibt, nicht einen, den Ihr System vor dem Senden erzeugt hat. Bei B2C baut Ihr System den vollständigen QR-Code selbst im Moment des Verkaufs auf.
Ein durchgerechnetes Beispiel
Hier ein QR-String im Stil von Phase 1 für eine Rechnung über 1.000 SAR zuzüglich 15 % Umsatzsteuer, aufgebaut aus den Beispielwerten der Tabelle oben:
AQ9BbCBOb29yIFRyYWRpbmcCDzMwMDAwMDAwMDAwMDAwMwMUMjAyNi0xMC0xNlQxMDoxNTowMFoEBzExNTAuMDAFBjE1MC4wMA==Dekodieren Sie die ersten Bytes, sehen Sie 01 0F und danach den Namen des Verkäufers. 01 ist Tag 1. 0F ist hexadezimal 15, die Anzahl der Bytes in „Al Noor Trading“. Danach folgen 02 0F und die 15-stellige Umsatzsteuernummer, und so weiter bis Tag 5.
Fügen Sie diesen String in unseren kostenlosen ZATCA-QR-Code-Decoder ein, und Sie sehen die fünf Felder einzeln aufgeschlüsselt.
So prüfen Sie den QR-Code auf Ihrer Rechnung
Nutzen Sie diese Schritte, wenn ein Kunde meldet, dass sein Scanner „ungültiger QR-Code“ anzeigt, oder wenn Sie ein neues Rechnungslayout testen.
- Den Rohstring holen. Scannen Sie den gedruckten QR-Code mit einer beliebigen Scanner-App oder kopieren Sie den Wert, der am Rechnungsdatensatz in Ihrem ERP gespeichert ist.
- Dekodieren. Lassen Sie ihn durch einen TLV-Decoder laufen. Scheitert der Decoder sofort, ist der String vermutlich kein Base64, oder es wurden zusätzliche Zeichen angehängt (Leerzeichen, Zeilenumbrüche, ein URL-Präfix).
- Tags 1 bis 5 mit der Rechnung vergleichen. Name und Umsatzsteuernummer des Verkäufers müssen Ihrer Umsatzsteuerregistrierung entsprechen. Tag 4 muss dem Rechnungsbetrag inklusive Umsatzsteuer entsprechen, Tag 5 der gesamten Umsatzsteuer der Rechnung.
- Den Zeitstempel prüfen. Tag 3 sollte zu Ausstellungsdatum und -uhrzeit der Rechnung passen. Ein Zeitstempel von einem anderen Tag bedeutet meist, dass der QR-Code aus dem falschen Feld erzeugt wurde.
- Die Tags zählen. Eine vereinfachte Rechnung in Phase 2 sollte 9 Tags zeigen. Eine freigegebene Standardrechnung sollte den von der ZATCA zurückgegebenen QR-Code tragen. Sehen Sie auf einer Phase-2-Rechnung nur 5 Tags, druckt Ihr Layout einen alten Phase-1-Wert.
- Die Länge prüfen. Der Base64-String sollte höchstens 700 Zeichen lang sein.
Das Dekodieren bestätigt die Struktur und die lesbaren Felder. Es beweist nicht, dass die Signatur in den Tags 7 und 9 echt ist. Dafür brauchen Sie das signierte XML und die Validierung der ZATCA selbst, die im SDK oder durch die Plattform bei Freigabe und Meldung erfolgt.
Häufige Fehler beim QR-Code
Der technische Leitfaden der ZATCA nennt einige Fehler, die immer wieder auftreten. Dieselben sehen wir, wenn wir Rechnungslayouts prüfen:
- Arabischer Verkäufername nicht in UTF-8. Der Name erscheint beim Scannen als Fragezeichen oder kaputte Zeichen.
- Länge in Zeichen statt in Bytes gezählt. Ein arabischer Name mit 10 Buchstaben belegt etwa 20 Bytes. Steht im Längenbyte 10, wird jedes folgende Tag falsch gelesen.
- Trennzeichen zwischen den Feldern. Kommas, Leerzeichen oder Auffüllzeichen zwischen den TLV-Gruppen machen das Dekodieren unmöglich. Es darf keine geben.
- Beträge, die nicht zur Rechnung passen. Oft wird der QR-Code aus der Zwischensumme erzeugt oder aus Werten vor einem Rabatt auf Belegebene.
- Falscher QR-Code auf B2B-Rechnungen. In Phase 2 sollte der freigegebene QR-Code der ZATCA auf dem Beleg stehen.
In SAP Business One wird der QR-Wert normalerweise an der Ausgangsrechnung gespeichert (in einem benutzerdefinierten Feld oder in den Daten des elektronischen Belegs) und über Crystal Reports oder den Print Layout Designer als Barcode oder Bild gedruckt. Schlägt der gedruckte Code fehl, prüfen Sie zuerst den gespeicherten Wert mit einem TLV-Decoder. Ist der gespeicherte Wert korrekt, liegt das Problem im Layout, nicht in der Schnittstelle.
Wo das in Phase 2 einzuordnen ist
Der QR-Code ist das sichtbare Ende eines längeren Prozesses: UBL-2.1-XML, Hash-Bildung, Signatur mit Ihrer CSID sowie Freigabe oder Meldung über die APIs der ZATCA. Ist einer dieser Schritte fehlerhaft, ist meist auch der QR-Code falsch. Unser Leitfaden zur ZATCA-E-Rechnung beschreibt den gesamten Ablauf, und der Rechner für die saudische Umsatzsteuer hilft, wenn Sie die Tags 4 und 5 von Hand nachprüfen möchten.
Druckt SAP Business One bei Ihnen einen QR-Code, den Kunden oder die ZATCA ablehnen, senden Sie uns ein Beispiel, und wir sagen Ihnen, welcher Teil fehlschlägt.
Quellen
- ZATCA: E-Invoicing Detailed Technical Guideline, Version 2 (Nov 2022)
- ZATCA: Detailed Guidelines for E-Invoicing, Version 2 (May 2023)
- ZATCA: Electronic Invoice Security Features Implementation Standards (19 May 2023)
- ZATCA Developer Community: Structure of the QR code for electronic tax invoices
- ZATCA: E-Invoicing guidelines page
Passende Leistungen
Häufige Fragen
Wie viele Felder enthält ein ZATCA-QR-Code?
Bis zu neun. Die Tags 1 bis 5 enthalten den Namen des Verkäufers, seine Umsatzsteuernummer, den Zeitstempel der Rechnung, den Betrag inklusive Umsatzsteuer und den Umsatzsteuerbetrag. Die Tags 6 bis 8 enthalten den Hash der XML-Rechnung, die ECDSA-Signatur und den öffentlichen ECDSA-Schlüssel. Tag 9 gibt es nur bei vereinfachten Rechnungen und den zugehörigen Gut- und Lastschriften.
Ist ein QR-Code auf B2B-Rechnungen (Standardrechnungen) Pflicht?
In Phase 1 (Erzeugung) war er nur auf vereinfachten Rechnungen vorgeschrieben. In Phase 2 (Integration) erhalten Standardrechnungen ihren QR-Code bei der Freigabe, wenn die Plattform der ZATCA die Rechnung stempelt und mit QR-Code zurückgibt.
Wie lang darf ein ZATCA-QR-Code höchstens sein?
Laut technischem Leitfaden der ZATCA wird der QR-Code in Base64 mit höchstens 700 Zeichen kodiert. Jeder TLV-Wert hat außerdem eine Länge von einem Byte, ein einzelnes Feld kann also nicht länger als 255 Bytes sein.
Warum zeigt mein ZATCA-QR-Code beim Scannen kaputten arabischen Text?
Meist wurde der Name des Verkäufers vor dem Aufbau der TLV-Struktur nicht in UTF-8 kodiert, oder das Längenbyte wurde nach Zeichen statt nach Bytes berechnet. Arabische Buchstaben belegen in UTF-8 jeweils zwei Bytes, die Länge muss also Bytes zählen.
Kann mir eine QR-Scanner-App sagen, ob die Rechnung gültig ist?
Ein normaler Scanner zeigt nur den Base64-Text. Ein TLV-Decoder zeigt die Felder, sodass Sie sie mit der Rechnung vergleichen können. Um nachzuweisen, dass die Signatur echt ist, brauchen Sie das signierte XML und die Validierungswerkzeuge der ZATCA, der QR-Code allein reicht nicht.
Bereit für den Start?
Sagen Sie uns, was Sie brauchen. Sie erhalten eine klare technische Antwort, einen festen Leistungsumfang und einen Preis, in der Regel innerhalb von 24 Stunden.
