ZATCA Phase 2 readiness workbook for an Odoo 19 implementation

How to use this workbook

Create one controlled workbook for each taxpayer scope and keep it under change ownership. The recommended tabs are: entity register, notification evidence, sales journals, document scenarios, master-data exceptions, environment runs, credential responsibilities, defect log and production approval. Use a stable row ID so that a workshop note, test result and later defect can refer to the same requirement.

Each row should name the accountable owner, reviewer, source evidence, target environment, expected result, actual result, status and next action. Store links to controlled evidence locations rather than embedding secrets or uncontrolled copies. A status is complete only when the reviewer can inspect the result, not merely when a task has been discussed.

The workbook supports implementation governance. It does not replace ZATCA guidance, the taxpayer's notification or qualified statutory review. Where the source or transaction scenario is unclear, record the question and the responsible adviser rather than filling the gap with an assumption.

Record the taxpayer, legal entity and notified wave

Reviewed 5 November 2026. Start with the legal taxpayer name, Arabic and English trading names where used, VAT registration number, commercial registration details used by the organisation, legal address, Odoo company record and authorised tax contact. Link each entity to its exact Odoo database and company setup.

Attach the taxpayer's ZATCA notification and record its issuer, recipient, reference, date, targeted entity and stated wave or timeline. ZATCA's Generation Phase began on 4 December 2021 and Integration Phase began on 1 January 2023 in taxpayer waves. An announcement's turnover band and date apply to its targeted group; the organisation's own notification and current official instructions determine its enforcement context.

Use ZATCA's roll-out phases and e-invoicing introduction as the primary programme references. If a group contains several taxpayers, do not copy one entity's notification to another. Each entity receives its own evidence row and decision.

Build the sales-journal and document-scenario matrix

List every sales journal that can create an in-scope invoice, including direct sales and point-of-sale journals where used. Record the Odoo journal ID, legal entity, branch or channel, currency, invoice sequence approach, current production status and intended onboarding owner. Odoo 19 onboards each sales journal separately, so a single journal row is not treated as company-wide evidence.

For each journal, identify standard tax invoices, simplified tax invoices, associated credit notes and associated debit notes. Note typical B2B, B2G or B2C usage without turning that usage into an absolute rule. Document type and transaction scenario determine whether clearance or reporting applies and which exceptions need review.

Add rows for partial and full adjustments, zero-rated or exempt sales where used, foreign-currency documents, advance or milestone scenarios, returns, rejected submissions and corrections. Each scenario needs a source transaction, expected human-readable output, expected structured payload, expected API path and final status evidence.

Qualify seller and buyer master data before onboarding

The Odoo 19 Saudi localisation requires accurate company and contact data for onboarding. Review seller and buyer fields by document scenario, including identification, address, VAT number and SAR currency. The workbook should identify which value came from which authoritative source and who approved it.

For the seller, compare the Odoo company record with the taxpayer evidence and sample legal documents. For buyers, test representative business, government and consumer parties as applicable. Check Arabic and English names, legal versus display names, building and district or address components used by the organisation, country, identifiers and contact records.

Create an exception row for every missing or conflicting value. The row names the record owner, correction source, dependent imports, affected test scenarios and retest result. Do not solve a missing legal value with invented sample text in a production-shaped rehearsal; use an authorised test identity in non-production and a controlled correction process for live data.

Collect current invoices and their Arabic and XML evidence

Gather representative current invoices and notes before designing the target test. Include the original human-readable document, source transaction, existing XML or integration response where available and any customer-visible delivery format. This establishes what the organisation currently issues and which fields or behaviours need clarification.

Human-readable invoices and associated notes must be in Arabic, with additional languages allowed. Review the Arabic output for party details, line descriptions, reasons, totals, tax information, fonts, shaping, page breaks and mixed-direction identifiers. An English interface is not evidence of Arabic output acceptance.

Phase 2 API submission is XML, not PDF/A-3. Odoo 19 can generate PDF/A-3 with embedded UBL 2.1 through Send, but that file remains a sharing artefact rather than the clearance payload. Keep XML, rendered output and API response linked to the same scenario row. ZATCA's detailed guideline and specification hub control the applicable technical requirements.

Plan Sandbox, Simulation and Production runs separately

Odoo 19 documents Sandbox, Simulation and Production for Saudi integration. Create an environment register with the database, Odoo version and edition, installed localisation modules, company, journal, Fatoora environment, tester, run time, scenario IDs and evidence location. Confirm that the test configuration matches the intended design.

Use Sandbox for technical exploration and connection checks. Use Simulation for representative integration scenarios and expected response handling; Simulation invoices are not legally valid. Use Production only after the business approval gate and controlled onboarding steps are complete.

A successful response in one environment does not populate the status of another. Copying a green result from Sandbox into the Production approval row destroys the evidence chain. Repeat the required scenario with its actual environment, journal and credentials, and record the exact response and reviewer.

Assign OTP and CSID ownership without exposing secrets

For Sandbox, Odoo provides a pre-populated six-digit OTP. Only Simulation and Production require retrieval of the six-digit OTP from the corresponding Fatoora environment. Each sales journal is still onboarded separately. The Fatoora portal user manual provides the official portal workflow reference for retrieving Simulation and Production OTPs. The taxpayer decides who is authorised to request, receive and use those OTPs and who controls the resulting CSID.

The credential-responsibility tab records the authorised requester, OTP recipient, onboarding operator, CSID custodian, approved storage location, permitted users, rotation or revocation owner and emergency contact. It stores references to the credential vault or approved process, not the OTP, CSID secret or private key itself.

Test access and handover before the production window. If the requester is unavailable or a credential must be changed, the runbook should identify the authorised alternative and the effect on dependent journals. Training screenshots and defect reports must redact sensitive values while preserving enough response evidence for diagnosis.

Execute standard, simplified and adjustment scenarios

In the usual Phase 2 flow, standard tax invoices, typically B2B or B2G, follow clearance. Simplified tax invoices, typically B2C, are reported within 24 hours. Record the expected treatment by scenario and verify exceptions against current ZATCA material and qualified review.

For a standard scenario, capture the prepared document, validation result, submission response, clearance outcome, rendered Arabic invoice and any later sharing output. For a simplified scenario, capture issuance, reporting response and final status within the applicable process. Do not infer final acceptance from an HTTP request alone; record the business-visible status and the response evidence supplied by the integration.

Odoo 19 supports credit and debit notes with a ZATCA-compliant reason and original-invoice reference. Test both standard and simplified adjustment scenarios where used. Verify the reason, reference, amounts, tax, Arabic output and final status, including partial adjustments and repeated failure recovery.

Retain negative evidence and prove the correction path

A readiness workbook that contains only successful samples cannot show how the organisation will operate under failure. Include missing buyer data, invalid identifiers, rejected payloads, unavailable connections, duplicate attempts, timeout or unknown-status handling and credential or journal mismatch where these can be tested safely.

For each negative run, record the triggering condition, actual response, user-visible message, whether a fiscal document was created, retry constraints and the responsible resolver. Capture the corrected input and subsequent result as separate evidence rows linked to the original failure.

Do not delete rejected attempts from the evidence set or repeatedly press submission without understanding duplicate risk. The operational runbook explains who investigates, who can authorise a retry, how finance confirms final status and how a support case is escalated with redacted artefacts.

Review VAT, Zakat and dependent operational boundaries

Odoo 19 preconfigures standard 15% VAT and zero-rated and exempt options. Finance and the qualified tax adviser review tax codes and account mappings for the test scenarios. The standard rate is applied only where legally applicable, and test evidence distinguishes configuration correctness from statutory interpretation.

VAT and Zakat returns are separate; Odoo's VAT and withholding reports do not submit a Zakat return. Use ZATCA's VAT return and Zakat return references for their distinct processes.

If invoice acceptance depends on inventory, point of sale, banking, mada, payroll or a third-party archive, link the relevant workstream rather than marking it implicitly complete. Provider and institution behaviour, current payroll parameters and hosting or backup arrangements receive their own validation and ownership.

Approve production with a signed evidence gate

The production approval tab summarises entity and journal scope, scenario coverage, unresolved defects, master-data exceptions, credential ownership, migration status, Arabic output review, support readiness and rollback or fallback decisions. Link every summary statement to its underlying run or signed review.

The release authority should include the taxpayer's responsible business owner and the designated finance, operations and technical reviewers. Their decision records accepted scope, residual risks, restrictions and next review. A technically configured journal with unresolved buyer-data or Arabic-output defects is not marked fully ready.

After release, monitor invoice responses, unknown statuses, adjustments, recurring master-data failures and support questions. Changes to journals, entities, credentials, localisation modules or document design trigger impact review and targeted retesting. The workbook remains an operating record rather than a one-time sales attachment.

Use official sources and label implementation education correctly

The primary product reference is the Odoo 19 Saudi fiscal localisation. Primary regulatory references are ZATCA's introduction, roll-out phases, detailed guideline, specification hub and Fatoora manual. The solution-provider directory is a separate official directory reference, not an implementation outcome claim.

Public OXP2026 sessions on e-invoicing onboarding and acceptance, e-invoicing evidence and version boundaries and localisation readiness are educational delivery material only. They are not dedicated Saudi technical guidance, Oakland references, customer evidence or endorsements.

Odoo 20 demonstrations remain separate educational context and do not establish Odoo 19 capability. For a Saudi decision, use the taxpayer's notification, official ZATCA rules, versioned Odoo 19 documentation and the organisation's own reproducible test results.