Skip to main content

GCC E-Invoicing | ZATCA Phase 2 — Saudi Arabia

This is the Saudi Arabia country pack for the ECOSIRE GCC E-Invoicing | Core Engine. It adds full ZATCA FATOORA Phase 2 (Integration Phase) compliance: Compliance and Production CSID onboarding against ZATCA, synchronous B2B Standard-invoice clearance, asynchronous B2C Simplified-invoice reporting, the BR-KSA validator taxonomy, the Previous Invoice Hash (PIH) chain, ZATCA QR codes, and bilingual Arabic/English RTL invoice PDFs. Its signing output is verified byte-exact against the ZATCA SDK reference.

This pack requires the core engine. Install ecosire_einvoice_core first (and set its ECOSIRE_EINVOICE_MASTER_KEY), then install this pack on top.

Compatibility: Odoo 17 / 18 / 19 (Community or Enterprise) Price: $799 (one-time) License: Up to 3 domain activations Category: Accounting / Localizations / EDI

Wave 24 deadline — 2026-06-30

ZATCA's Phase 2 enforcement reaches the SAR 375,000 turnover threshold (Wave 24) on 30 June 2026. If your business falls in this wave, your integration must be live before that date. Onboarding (Compliance → Production CSID) and a simulation rehearsal should be completed with time to spare.

Live demo

Try it at zatca.demo.ecosire.com — log in with admin / admin.

What it does​

  • Standard (B2B) clearance + Simplified (B2C) reporting with automatic subtype detection.
  • BR-KSA / EN16931 validator taxonomy — the KSA business rules checked before submission.
  • VATEX-SA exemption codes preloaded (zero-rated / exempt / out-of-scope categories).
  • PIH (Previous Invoice Hash) chain maintained per EGS device, as ZATCA requires.
  • Invoice subtype auto-detection — a VAT-registered (or cross-border B2B) buyer is cleared as Standard; a walk-in / unregistered customer is reported as Simplified. A customer carrying a VAT number can never be a Simplified invoice.
  • ZATCA QR codes — TLV QR with the ZATCA field set (the certificate-signature field is present on Simplified and omitted on Standard).
  • Bilingual Arabic/English RTL invoice PDFs for Standard, Simplified, Credit, and Debit documents.
  • Compliance + Production CSID lifecycle against ZATCA, across sandbox / simulation / production environments.
  • Migration wizard from Odoo's stock l10n_sa_edi, with Migrate and Coexist modes.

Requirements​

RequirementDetail
Odoo17.0, 18.0, or 19.0 (Community or Enterprise)
Core engineecosire_einvoice_core installed, with ECOSIRE_EINVOICE_MASTER_KEY set
Odoo dependenciesecosire_einvoice_core, l10n_sa (Saudi localisation)
Python packagescryptography, lxml, qrcode (already required by the core engine)
LicenseAn active ECOSIRE license for this module
ZATCA accessA ZATCA FATOORA portal account to obtain the onboarding OTP

See the core engine requirements — in particular the ECOSIRE_EINVOICE_MASTER_KEY environment variable, which must be set before you onboard any certificate.

Installation​

  1. Install and configure the GCC E-Invoicing | Core Engine first (including the master key).
  2. Download this pack's ZIP from your ECOSIRE Dashboard and extract it to your addons directory: 
    unzip ecosire-einvoice-ksa-*.zip -d /opt/odoo/addons/
    sudo systemctl restart odoo
  3. In Odoo go to Apps, click Update Apps List.
  4. Search for ECOSIRE GCC E-Invoicing | ZATCA Phase 2 — Saudi Arabia and click Install (Odoo installs the core engine and l10n_sa automatically if they are not yet present).
  5. Enter your ECOSIRE license key when prompted.

After installation a Saudi Arabia submenu appears under Accounting → GCC E-Invoicing.

The KSA pack nests under the engine's root menu:

MenuPathPurpose
Saudi ArabiaAccounting → GCC E-Invoicing → Saudi ArabiaKSA submenu root
ConfigurationAccounting → GCC E-Invoicing → Saudi Arabia → ConfigurationKSA settings
VATEX-SA CodesAccounting → GCC E-Invoicing → Saudi Arabia → Configuration → VATEX-SA CodesPreloaded exemption codes

CSIDs, EGS Devices, Documents, and the Audit Log live under the shared engine menu — see the core engine menu map.

Configuration walkthrough​

Step 1: Company prerequisites​

ZATCA requires complete, accurate seller data. Before onboarding, make sure each company (and each branch that issues invoices) has:

  • A valid VAT registration number (15 digits).
  • A complete registered address (street, building number, district, city, postal code, country = Saudi Arabia).
  • The legal/Arabic company name.
  • The Commercial Registration (CRN) number.
  • If applicable, the ZATCA Branch Code and VAT Group ID fields added by this pack on the company record.

Customers that should receive Standard (B2B) invoices must have their VAT number and address filled in on their contact record — this is also what drives subtype auto-detection.

Step 2: CSID onboarding (Compliance → Production)​

Certificates are onboarded through the core engine's 7-step CSID wizard. With this pack installed, the ZATCA-facing steps are fully functional.

  1. EGS Device — enter the organisation name, VAT, CRN, branch, and device serial for the e-invoice generation unit.
  2. Generate CSR — the engine generates the ECDSA secp256r1 key pair and CSR; the KSA pack enriches the CSR with the ZATCA-required certificate extensions.
  3. Enter OTP — log in to the ZATCA FATOORA portal, generate the OTP for your EGS unit, and paste it here.
  4. Compliance CSID — the pack calls ZATCA's compliance endpoint and stores the Compliance CSID.
  5. Sandbox Self-Test — runs the ZATCA compliance checks (the compliance invoice matrix) to prove your setup signs and validates correctly.
  6. Promote to Production — the pack requests and stores the Production CSID.
  7. Done — you can now sign and submit live invoices.

The private key is Fernet-encrypted with the master key throughout; it is never stored in plaintext. A daily renewal check warns you 30 days before a production certificate expires.

Step 3: Simulation vs Production endpoints​

Choose the target environment during onboarding. The pack talks to the matching ZATCA base URL:

EnvironmentUseZATCA gateway
SandboxDeveloper-portal testinggw-fatoora.zatca.gov.sa/e-invoicing/developer-portal
SimulationPre-production rehearsal that mirrors productiongw-fatoora.zatca.gov.sa/e-invoicing/simulation
ProductionLive clearance and reportinggw-fatoora.zatca.gov.sa/e-invoicing/core

Rehearse in Simulation until your invoices clear cleanly, then onboard a Production CSID and switch over. Simulation documents are kept out of the production dashboard KPIs.

Daily usage​

Standard vs Simplified​

The pack detects the subtype automatically when a document is created:

  • Standard (B2B) — the buyer is VAT-registered, or is a cross-border B2B buyer. Cleared synchronously via ZATCA's clearance endpoint; the buyer should not be handed the invoice until ZATCA returns the cleared XML.
  • Simplified (B2C) — retail / walk-in customers with no VAT registration. Reported asynchronously after issuance.

A customer carrying a VAT number can never produce a Simplified invoice — that combination is rejected as a ZATCA validity error.

How invoices get cleared or reported​

Post your customer invoice as usual in Accounting. The e-invoice document is produced and flows through the engine's lifecycle: the Submit Pending Documents job (every 5 minutes) signs and submits it, or you can drive a single document by hand from Accounting → GCC E-Invoicing → Documents with the Sign, Submit Now, and Retry Now buttons. See the core engine daily-usage guide for the full state machine and the dashboard.

Bilingual invoice PDFs​

The pack ships ZATCA-compliant bilingual Arabic/English RTL PDF templates for Standard, Simplified, Credit, and Debit documents, including the ZATCA QR code. Print a posted invoice — the ZATCA Tax Invoice (Bilingual) report is available from the invoice's Print menu.

Handling failed documents​

Use the dashboard's Failed documents list or filter Documents by state. Read the Errors tab for the ZATCA error code and message, fix the underlying invoice/partner data, and click Retry Now. The BR-KSA validators catch most issues before submission, so many failures are corrected by completing missing seller or buyer fields.

The audit log​

Every event — signing, clearance, reporting, rejection, retry — is recorded in the engine's immutable, hash-chained audit log, with PII redacted and PostgreSQL triggers preventing any edit or delete. Retention defaults to the ZATCA-mandated 6 years.

Migration from l10n_sa_edi​

If you previously used Odoo's stock l10n_sa_edi ZATCA module, the pack ships a migration wizard (Saudi Arabia → Migration) that detects it and offers:

  • Migrate (recommended) — copies each company's Compliance and Production CSIDs from the stock journal fields into the engine (private keys re-encrypted with the master key), then deactivates the stock ZATCA EDI flow so it stops firing on new invoices. The stock module is never uninstalled. After migrating, the wizard optionally runs a 2-invoice simulation smoke test to confirm the engine signs correctly (the smoke is fail-soft — it never rolls back the migration).
  • Coexist (advanced) — leaves both the stock flow and the ECOSIRE engine active. No CSIDs are copied and nothing is deactivated.
  • Do nothing for now — make no changes; you can re-run the wizard later.

After a successful migrate, ECOSIRE owns the new-invoice e-invoicing flow and your existing certificates carry over, so you do not need to re-onboard with ZATCA.

FAQ​

Do I need the core engine? Yes. This pack provides the KSA rules and ZATCA endpoints, but the UBL builder, signer, orchestrator, audit log, and dashboard all live in ecosire_einvoice_core. Install the engine first.

Is Point of Sale (POS) supported? POS Phase 2 e-invoicing is on the v1.1 roadmap and is not included in this release. The current release covers account.move invoices and credit/debit notes (Standard and Simplified). If you sell through Odoo POS, contact us about the roadmap timeline.

Is the signing actually ZATCA-compliant? The XAdES-BES signing and QR output are verified byte-exact against the ZATCA SDK reference, and the BR-KSA / EN16931 validator taxonomy runs before submission.

Which waves are in scope? The pack targets the Phase 2 Integration Phase waves, with Wave 24 (SAR 375,000 threshold, 30 June 2026) as the primary launch target. Earlier waves are already covered.

Can I keep Odoo's l10n_sa_edi running alongside it? Yes — choose Coexist in the migration wizard. Most customers migrate fully instead, since running both flows can double-submit.

What happens to my existing ZATCA certificates when I migrate? They are copied into the engine and re-encrypted with your master key — you do not re-onboard with ZATCA.

Support​

Last updated on