Naar inhoud springen
Terug naar blog
Saudi ArabiaGepubliceerd op 14 juli 20268 min leestijd

Saudi Arabia e-invoicing: what ZATCA (FATOORA) actually requires

ZATCA is not a format you bolt on at the end — it is a clearance system with a hash chain. The two invoice classes, the ICV/PIH chain that constrains your architecture, and where the cryptographic stamp fits.

ZATCA is not a format you can bolt on at the end of your invoicing pipeline. It is a clearance system with a hash chain running through it — and the chain has opinions about how your pipeline is built. That is the part most integration plans miss.

ZATCA in one paragraph

Saudi Arabia’s e-invoice is UBL 2.1 — but it is not EN 16931. It carries ProfileID “reporting:1.0” and no CustomizationID, a seven-digit invoice-subtype code, its own QR, and an integrity chain. Phase 2 (Integration) is the live one: you sign the invoice, and then you either clear it or report it, depending on who the buyer is.

Two invoice classes that are genuinely different

  • Standard tax invoice (B2B / B2G) — cleared before you give it to the buyer. You submit, ZATCA applies its own stamp and returns the cleared document, and that returned document is the legal invoice. Not yours.
  • Simplified tax invoice (B2C) — reported within 24 hours of issuance. Here your QR is the final one, and the customer walks away with the invoice immediately.

Their mandatory field sets genuinely differ: a standard invoice needs the buyer’s VAT number and full address, a simplified one does not. It is tempting to model one shape and set a flag. Resist it — the difference is not cosmetic, and the seven-digit subtype code on the invoice announces which one you meant.

The part that breaks pipelines: ICV and PIH

Every ZATCA invoice carries two chain fields: an ICV — a gapless sequential counter — and a PIH, the base64 SHA-256 hash of the previous invoice. Each invoice points at the one before it. It is a hash chain, per invoicing unit.

That is an architecture requirement wearing the costume of a data field. Generate two invoices concurrently for the same unit and you have forked the chain. Retry one out of order and you have broken it. If your invoicing is horizontally scaled and stateless — which is usually the sensible design — then Saudi Arabia is asking you to add a strictly sequential, durable counter per unit. That is a design change, not a mapping exercise, and it is much cheaper to discover now than after go-live.

The cryptographic stamp is key custody, not a paywall

Signing needs a CSID: a certificate ZATCA issues, tied to a real VAT-registered Saudi taxpayer. Two things worth knowing, because both are commonly assumed wrong. ZATCA charges nothing for the certificate or the APIs — there is no accreditation fee. And the sandbox works with a dummy OTP, so you can build and test the whole flow without a Saudi taxpayer. The only real gate is that the production certificate belongs to an actual registered business.

So the stamp is not a cost problem. It is a key-custody problem: someone has to hold that private key.

Where MyInvoice fits — and where it stops

We generate the complete, XSD-valid ZATCA document — standard or simplified, with the invoice-subtype code, the ICV/PIH chain fields and the Phase-1 QR — from the data you already export:

curl -X POST https://api.myinvoice.llc/v1/convert \
  -H "X-API-Key: ek_live_..." \
  -F "[email protected]" \
  -F "format=csv" \
  -F "profile=zatca-sa"

What we deliberately do not do: sign it. The document comes out unsigned, and the cryptographic stamp plus the FATOORA clearance or reporting call stay with your ZATCA-onboarded system — which is where your private key belongs anyway. We would rather tell you that plainly than hand you a document that looks finished and is not.

On the QR: it is a TLV structure, base64-encoded. Tags 1 to 5 are plain invoice facts — seller name, VAT number, timestamp, total, VAT total. Tags 6 to 9 are derived from the stamp. So a pre-stamp QR carrying tags 1–5 is not a broken QR; it is the honest one.

Generate a Saudi invoice in your browser

ZATCA revises its specifications and endpoints regularly — always confirm the current mandatory-field list and API contract against ZATCA’s own SDK and documentation before you go live.

Read the API docs