ZATCA Phase 2 · Fatoora
How ZATCA Phase 2 works — and where Esnad fits
Saudi VAT-registered businesses must connect their e-invoicing solution to ZATCA’s Fatoora platform. You can build that integration yourself, or send JSON to Esnad and let us own the XML, certificates, and government APIs.
What is ZATCA and Fatoora?
ZATCA (Zakat, Tax and Customs Authority) is the Saudi authority that regulates VAT and mandatory e-invoicing.
Fatoora is ZATCA’s e-invoicing platform — the portal and APIs your E-Invoice Generation Solution (EGS) must talk to in Phase 2.
Phase 2 is not optional once your business falls into an announced integration wave. Non-cleared B2B invoices are not valid tax invoices for delivery to the buyer.
Phase 1
Phase 1 — Generation
Generate, issue, and store structured electronic invoices with mandatory fields and a QR code. No live API submission to ZATCA.
Phase 2
Phase 2 — Integration
Integrate your EGS with Fatoora. Standard (B2B) invoices use real-time clearance. Simplified (B2C) invoices must be reported within 24 hours of issuance.
ZATCA rolls Phase 2 out in waves by taxable revenue, with advance notice before each group’s deadline. Check your wave status on the Fatoora portal or ZATCA communications.
How to comply without Esnad
ZATCA publishes the standards. A capable engineering team can integrate Fatoora directly. Here is what that path actually requires.
What you must build and operate
- 1
UBL 2.1 XML (KSA profile)
Every invoice is Universal Business Language XML — not a PDF alone. PDF/A-3 with embedded XML may be used for human display; Fatoora clearance and reporting expect compliant XML.
- 2
Cryptographic stamp (CSID)
Generate an ECDSA key pair and CSR, obtain a Compliance CSID via OTP from the Fatoora portal, pass compliance invoice tests, then request a Production CSID (PCSID) to sign live invoices.
- 3
UUID, ICV, and PIH chain
Each invoice needs a UUID. Each EGS unit needs a strictly sequential Invoice Counter Value (ICV) and a Previous Invoice Hash (PIH) linking invoice N to N−1 so records cannot be inserted or altered unnoticed.
- 4
Clearance vs reporting APIs
B2B standard invoices: submit to clearance and only share the cleared XML with the buyer after ZATCA accepts. B2C simplified invoices: issue with QR immediately, then report to Fatoora within 24 hours.
- 5
QR, archive, and renewals
Build TLV QR for simplified invoices, store signed/cleared XML for the legally required retention period, and renew CSIDs before expiry — typically yearly.
DIY integration flow
End-to-end path when your POS or ERP talks to Fatoora itself — onboarding, signing, then clearance or reporting.
Onboard every EGS unit
Keys + CSR
ECDSA key pair per EGS
Fatoora OTP
Proves VAT ownership
Compliance CSID
Pass invoice test suite
Production CSID
Sign live tax invoices
Build & sign yourself
UBL 2.1 XML
Full KSA profile
ICV + PIH
Counter & hash chain
CSID signature
Cryptographic stamp
Submit to ZATCA Fatoora
B2B · Clearance
Real-timeOnly then deliver to the buyer
B2C · Reporting
Within 24hYou own the XML, crypto, certificates, queues, archive, and every ZATCA rule change.
B2B — Clearance
Seller generates signed XML → Fatoora clearance API → ZATCA returns cleared XML with its stamp → only then deliver to the buyer.
B2C — Reporting
Seller issues signed invoice + QR to the buyer immediately → report the same XML to Fatoora within 24 hours.
Why teams still struggle
- ▸First happy-path invoice is not the hard part — keeping PIH/ICV correct across branches for years is.
- ▸Certificate onboarding, compliance tests, and annual renewals need runbooks and on-call.
- ▸ZATCA validation rules and error codes evolve; direct integrators absorb every change in their codebase.
- ▸Sandbox and production must stay isolated; one wrong environment breaks live tax documents.
Where Esnad comes in
Esnad is middleware between your system and Fatoora. You keep selling and invoicing in JSON. We build UBL, sign with the unit CSID, maintain the PIH chain, call clearance or reporting, archive the result, and return status, UUID, QR (B2C), and download URLs.
With Esnad
Your app never speaks UBL or Fatoora. One REST API; we handle government complexity.
Your POS / ERP
- •Invoice JSON
- •API key
- •egs_unit_id
Esnad
- •UBL XML
- •Sign · PIH · ICV · QR
- •Clearance or reporting
- •Archive XML + PDF
ZATCA Fatoora
- •Government validation
- •Stamp / acknowledgement
Response → status · UUID · QR (B2C) · XML & PDF URLs
Fatoora OTP only when creating or renewing a unit — no XML in your app.
Your side in three steps
Create account & API key
Sandbox keys start with zatca_test_. Production keys start with zatca_live_. Strict separation by design.
Register an EGS unit (OTP once)
We generate keys and CSR, run the ZATCA compliance flow, and store the certificate. You paste the Fatoora OTP when onboarding or renewing.
POST invoice JSON
Send seller, buyer (B2B), line items, and egs_unit_id. Get back cleared or reported status, QR for B2C, and links to signed XML and PDF.
DIY Fatoora vs Esnad
| Concern | Build it yourself | Use Esnad |
|---|---|---|
| Integration language | UBL XML + crypto | JSON REST API |
| EGS / CSID onboarding | You own CSR, OTP, compliance tests | OTP from you; flow by Esnad |
| PIH & ICV per branch | You design and never break the chain | Automatic per EGS unit |
| B2B clearance | You call Fatoora and block buyer delivery | We clear, then return status |
| B2C reporting | You queue and hit the 24h window | We report; you show QR now |
| Spec & rule changes | Your engineering backlog | Stable API — we absorb updates |
| Time to first sandbox invoice | Weeks to months | Hours with test OTP |
Skip the XML. Ship Phase 2.
14-day free trial. Sandbox ready quickly. Same API when you move to production CSIDs.
Summary for product education. Always follow the latest official ZATCA / Fatoora guidelines and your wave notice for legal obligations.