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."

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