Technical Authority Series

The Unofficial Guide to
Fatoora Portal

The fulcrum of Saudi Arabia's digital economy. Bridging the gap between regulatory decrees and the granular realities of ZATCA e-invoicing and technical integration. [1]

Master Onboarding Official Portal ↗
1

Architectural Anatomy

Navigating the ZATCA landscape requires understanding the three distinct environments. Confusion here is the leading cause of integration failure. [11]

Sandbox

sandbox.zatca.gov.sa

For early development. Test XML schema compliance against UBL 2.1 standards. Certificates issued here do not work in production. [8]

Simulation

fatoora.zatca.gov.sa (UAT)

Exact replica of production. Enforces real business rules. Critical for "Dry Runs" before your wave date. [13]

Production

fatoora.zatca.gov.sa

The live environment. Every invoice cleared here is a legal liability. Requires ERAD credentials and MFA. [12]

2

Hybrid Operational Model

Clearance Model

B2B & B2G

A synchronous workflow. The EGS sends the XML to the Fatoora Portal. The portal validates, stamps, and returns the signed invoice.

⚠️ Only this cleared XML is the legal tax document. [6]

Reporting Model

B2C (Retail)

Priority is speed. The EGS signs the invoice locally using a stored CSID. The customer gets the invoice immediately.

⚡ EGS has 24 hours to report it to the portal. [7]
3

Cryptographic Foundations

  • 01
    The secp256k1 Curve

    Unlike RSA, ZATCA mandates Elliptic Curve Cryptography. Using the wrong curve results in immediate CSR rejection. [8]

  • 02
    Certificate Signing Request (CSR)

    Must contain custom OIDs (Object Identifiers) mapping the device to the taxpayer's VAT number and invoice types. [18]

  • 03
    The Hash Chain

    To prevent invoice deletion, every invoice must contain the SHA-256 hash of the previous invoice (PIH). The first invoice's PIH is a Base64-encoded hash of "0".

4

Onboarding Technical Walkthrough

Step 1

OTP Generation

Generated on the Fatoora Portal by the taxpayer. Valid for only one hour. Bridges trust between portal and EGS. [5]

Step 2

Compliance CSID (CCSID)

The EGS calls compliance API with OTP and local CSR. ZATCA returns a CCSID—a restricted certificate for testing. [21]

Step 3

Compliance Check Loop

EGS submits sample invoices (Invoice, Credit, Debit) to prove XML validity. Every sample must pass business rules. [30]

Step 4

Production CSID (PCSID)

Upon success, EGS requests promotion. ZATCA issues the PCSID—the "Golden Key" for live operations. [29]

5

Decoding Common Errors

🔍 Looking for specific error codes? Check our complete guide with 15 detailed ZATCA errors.

Browse ZATCA Error Code Reference →
Error Code Meaning Impact
BR-S-09 VAT calculation mismatch. Usually due to rounding differences between line items and totals. Rejection
BR-KSA-31 Building Number must be 4 digits. Common for unstructured address data. [34] Warning
Hash Mismatch The Previous Invoice Hash (PIH) doesn't match the chain ZATCA has on record. Rejection

Operational Checklist

6M
Receive ZATCA notification and audit your software for Phase 2 readiness. [4]
4M
Access the Simulation Portal. Begin "Dry Run" testing with mirrored data. [13]
1M
Generate Production OTPs and onboard all devices. [17]

Works Cited & Technical References
  1. Complyance.io, "EGS Onboarding — ZATCA Phase-2 E-Invoicing," Medium (2025).
  2. ZATCA, "How to Get Ready?"
  3. ZATCA, "Detailed Guidelines for E-Invoicing Version 2."
  4. Sedin Technologies, "ZATCA E-Invoicing in Saudi Arabia: Phases, Waves & Compliance Guide."
  5. Fatoora Developer Community, "Onboarding and Renewal - Documentation."
  6. ClearTax, "ZATCA E-Invoicing: EGS Solution Explained."
  7. Wafeq, "Quickstart: Report a simplified invoice to ZATCA."
  8. ZATCA, "Developer Portal Manual Version 2."
  9. ZATCA, "Developer Portal Manual Version 3."
  10. ZATCA, "Download SDK."
  11. EINV Blog, "Types of APIs & Environment of Zatca Endpoints."
  12. ZATCA, "FATOORA Portal User Manual."
  13. Fatoora Developer Community, "What is the difference between FATOORA portal and Simulation portal?"
  14. Tax2gov, "Fatoora Platform Access for Taxpayers Explained."
  15. PwC, "Saudi Arabia - Fatoora portal user manual Version 2 issued by ZATCA."
  16. ClearTax, "How to renew existing CSIDs in KSA e-Invoicing?"
  17. VATupdate, "Fatoora Portal User Manual."
  18. Fatoora Developer Community, "CSR Generation Process - General."
  19. ClearTax, "How to do Revocation of CSIDs in KSA e-Invoicing?"
  20. QuickDice ERP, "What does a Certificate Signing Request (CSR) mean?"
  21. Microsoft Dynamics 365, "Onboarding for electronic invoicing in Saudi Arabia."
  22. Fatoora Developer Community, "Is there any difference between Simulation portal and Fatoora portal when creating CSR?"
  23. Medium, "ZATCA E-Invoice Integration Guide: A Complete E-Invoicing Integration Journey with Laravel."
  24. ApiZatca, "Resolving the 'Production CSID Does Not Cover Simplified Documents' Error."
  25. Stack Overflow, "Production CSID does not cover Simplified documents error."
  26. ClearTax, "How to Validate ZATCA e-Invoice Using QR Code?"
  27. Tally Solutions, "KSA Fatoora Portal: A Definitive Guide."
  28. Fatoora Developer Community, "Automatic OTP retrieval via SAML SSO."
  29. Fatoora Developer Community, "How to Obtain Production CSID?"
  30. Fatoora Developer Community, "Completed Compliance Invoice But Getting On Production CSID."
  31. QuickDice ERP, "How to renew existing CSIDs in KSA e-Invoicing system?"
  32. Claudion, "ZATCA E-Invoice Validation."
  33. ClearTax, "How to Resolve Errors in e-Invoices in Saudi Arabia?"
  34. Fatoora Developer Community, "Error when trying to clear the invoice."
  35. ApiZatca, "FAQs on ZATCA Phase 2 KSA E-Invoicing."
  36. Manager.io Forum, "Issue with ZATCA Integration in Manager.io."
  37. Cygnet.One, "Saudi Arabia Fatoora Portal: The Complete Guide."
  38. Vita-xpro.com, "ZATCA Mandated Error Codes List."
  39. Fatoora Developer Community, "Clarification Required on ZATCA Validation Warnings and Errors."
  40. ZATCA, "Roll-out phases."
  41. EY, "Saudi Arabia announces 22nd wave of Phase 2 e-invoicing integration."
  42. Thomson Reuters, "E-invoicing Phase 2 in KSA: How ZATCA's Guidelines Affect You."

Looking for a full ZATCA solution?

Manual Fatoora Portal submission is tedious. Qeemah connects directly to ZATCA, auto-generates QR codes, signs invoices, and submits them—with full Arabic support and zero compliance headaches.

Qeemah vs Daftra Qeemah vs Qoyod Compare with other platforms →

Fatoora Portal FAQ

What is the Fatoora portal?
Fatoora is ZATCA's official e-invoicing platform in Saudi Arabia. Businesses use it to onboard their e-invoicing solution, obtain CSID certificates, and clear or report Phase 2 electronic invoices to the Zakat, Tax and Customs Authority.

How do I log in to the Fatoora portal?
Access the Fatoora portal through the ZATCA website and sign in with your ERAD/TIN taxpayer credentials. You then generate an OTP inside the portal to onboard each e-invoicing device or solution (EGS unit).

What is the difference between the Fatoora portal and the Simulation portal?
The Simulation portal is a testing environment that mirrors production so you can validate invoices before go-live, while the production Fatoora portal issues live CSID certificates and processes real clearance and reporting. Certificates from one environment do not work in the other.

What is a CSID and how do I get one?
A CSID (Cryptographic Stamp Identifier) is a certificate ZATCA issues to identify your e-invoicing solution. You obtain a compliance CSID by generating a CSR and passing compliance checks, then request a production CSID to start issuing live invoices.

Is the Fatoora portal free to use?
Yes, ZATCA does not charge for using the Fatoora portal or issuing CSID certificates. You only need a compliant e-invoicing solution that can generate the required XML, QR codes, and cryptographic stamps.

Skip the technical debt

Don't spend months deciphering UBL 2.1 schemas and cryptographic curves. Qeemah handles the Fatoora Portal integration end-to-end.

Start ZATCA Integration View Developer Docs
Chat with us on WhatsApp