ZATCA lehnt Rechnungen mit knappen Fehlercodes ab, und sie unter Deadline-Druck zu entschlüsseln ist brutal. Hier die sieben häufigsten, die wir in Produktion sehen — geordnet nach Häufigkeit, mit einem erprobten Fix für jeden.
1. ENT_ICV-001 — Invoice Counter Value außer Reihenfolge
Der ICV muss pro Gerät streng monoton wachsen. Ursache ist fast immer parallele Ausstellung aus zwei Prozessen gegen dasselbe EGS. Fix: ICV-Vergabe hinter einer einzigen Quelle der Wahrheit serialisieren (eine DB-Sequence reicht).
2. ENT_PIH-002 — Previous Invoice Hash stimmt nicht überein
Der Hash, den Sie als vorherigen geschickt haben, stimmt nicht mit dem überein, den ZATCA gespeichert hat. Ursache: jemand hat eine alte Rechnung erneut abgeschickt, oder der lokale Cache hängt hinterher. Fix: Fatoora nach dem letzten geclearten Hash fragen und Ihre Kette neu aufsäen.
3. KSA-25 — Steuerkategorie-Code fehlt oder ungültig
Jede Position braucht einen UNCL5305-Kategorie-Code: S, Z, E, O oder AE. Häufige Schluderei: bei nullsteuerlichen Positionen leer lassen. Fix: explizit Z setzen, nicht weglassen.
4. KSA-12 — Verkäufer-USt-Nummer falsch formatiert
Saudische USt-IDs haben 15 Stellen, beginnen mit 3 und enden mit einer Prüfziffer. Häufiger Fehler: stattdessen die 10-stellige Commercial Registration Number senden. Fix: USt aus tax_registrations mit kind='VAT' lesen, nicht aus dem Feld der Gewerbelizenz.
5. CLOCK_DRIFT — IssueDateTime mehr als 30 Sekunden außer Sync
Server-Uhrendrift. Fix: NTP-Sync gegen pool.ntp.org, jede Minute, auf jedem rechnungsausstellenden Host.
6. KSA-08 — Standardrechnung ohne Käufer-USt
B2B-Rechnungen in KSA verlangen die USt (TaxID) des Käufers. Vereinfachte (B2C) nicht. Fix: im Serializer nach InvoiceTypeCode verzweigen (388 = Standard, 388 mit Subtype 02 = vereinfacht).
7. KSA-19 — Steuerbetrag inkonsistent mit Positions-Summen
Summe der Positions-Steuern ≠ TaxTotal. Ursache ist fast immer Rundung mitten in der Rechnung. Fix: nur das finale Subtotal pro Satz runden (Banker's Rounding), nie pro Zeile.