ZATCA Phase 2 (Saudi Arabia): e-invoicing in Odoo

Saudi Arabia has rolled out mandatory e-invoicing in two phases through ZATCA (Zakat, Tax and Customs Authority), under the Fatoorah name. Phase 1 (from December 2021) already required generating and keeping structured electronic invoices. Phase 2 goes much further: direct technical integration with the authority's platform.

What exactly Phase 2 (Integration Phase) is

Phase 2 is known as the Integration Phase. Generating the invoice is no longer enough: your invoicing system must connect via API to ZATCA's platform (Fatoora) and follow a specific format and validation cycle.

ZATCA distinguishes two document types with different flows:

• Standard Tax Invoice (B2B/B2G): requires clearance. The invoice is sent to ZATCA before delivering it to the customer; ZATCA validates it, cryptographically stamps it and returns it cleared.
• Simplified Tax Invoice (B2C): requires reporting. It is handed to the customer instantly with its QR and reported to ZATCA within 24 hours.

Technical requirements you cannot skip

• Invoice in XML UBL 2.1 format (or PDF/A-3 with embedded XML) following ZATCA's schema.
• Cryptographic signature with a certificate issued by ZATCA after device onboarding (CSID).
• Chained hash (PIH, Previous Invoice Hash) linking each invoice to the previous one and guaranteeing series integrity.
• QR code with TLV fields (seller name, VAT number, date, total, VAT amount and the cryptographic stamp) readable by ZATCA's app.
• Unique UUID per invoice and a sequential counter (ICV) that ZATCA verifies to detect gaps.

How it works in Odoo 19

Our module integrates this whole cycle inside Odoo's native invoicing flow, with no external back-office. When you confirm an invoice, Odoo generates the UBL XML, computes the chained hash, sends it to be signed with the ZATCA certificate, builds the QR and makes the clearance or reporting call according to the document type.

Each invoice stores its ZATCA status (accepted, accepted with warnings or rejected), the authority's message and the returned stamp. If ZATCA rejects a document, the reason is logged on the invoice itself so you can fix and resubmit it without losing traceability.

What to watch before your deadline

• Confirm your wave and exact date in ZATCA's notification letter: the integration window opens months ahead but has a firm deadline.
• Clean master data: VAT number, address, postal code and VAT scheme must be correct in Odoo or clearance will fail.
• Test in ZATCA's sandbox first: certificate onboarding and the first invoices must be validated in the test environment before going live.
• Don't mix series: the chained hash (PIH) requires continuous numbering; a gap or a duplicate invoice breaks the chain.

ZATCA Phase 2 is not a cosmetic add-on: it changes how every invoice is issued. Done well inside Odoo, it is transparent to the billing team; done halfway, it turns into rejected invoices and daily manual work.