ZATCA Phase 2 Odoo Integration: What It Takes

ZATCA Phase 2 — the integration phase of Saudi e-invoicing — requires your system to produce invoices as XML, submit them to the Fatoora platform through its APIs, and carry a unique identifier, a cryptographic stamp and a QR code. For an Odoo site, the work is less about sending and more about what your records can produce.

Phase 1 made invoices structured. Phase 2 makes the authority a party to them.

The first phase of Saudi e-invoicing was about the document: invoices had to be generated electronically in a defined form, with the required fields and a QR code, and stored. Your systems talked to each other and to your customers, and the authority was not in the conversation.

Phase 2 is called the integration phase because that is literally what it adds. Your invoicing system now has to talk to the Fatoora platform through APIs, and the authority becomes a participant in the issuing of each invoice rather than an auditor of it afterwards. If you have worked through the UAE’s version of the same idea, the shape will be familiar, and the difference matters: the UAE routes documents through an accredited private provider in what is known as a five-corner model, while Saudi Arabia has you integrate with the authority’s own platform directly.

ZATCA has published all of this in detail — the implementation resolution, the detailed technical guidelines and the security features implementation standards are on its own site, and anyone scoping this work should be reading those rather than a vendor’s summary, including this one. What follows is the shape of the job, not a substitute for the specification.

Clearance and reporting are two different flows

This is the distinction that most often gets missed in scoping, and getting it wrong changes the whole design.

Tax invoices go through clearance

A standard tax invoice — the business-to-business kind — follows the clearance model. Your system submits the invoice to the platform before you share it with the buyer. It is validated, and if it passes, it is stamped and returned to you. The version you then give your customer is the cleared one that came back, not the one you sent. Read that twice if you are designing the flow, because it means your invoice delivery now waits on a round trip you do not control.

Simplified invoices are reported

Simplified tax invoices — broadly the consumer-facing kind — follow the reporting model instead. You issue the invoice to the customer and report it to the platform. The sequence is the other way round, which is the only sane arrangement for a till with a queue in front of it.

So a business that does both has two flows with two different dependencies. A retailer with a wholesale arm is not implementing one integration; it is implementing two behaviours over one connection, and the point-of-sale side has a timing requirement the invoicing side does not.

What the document itself has to carry

Phase 2 invoices are XML submitted through the API rather than a human-readable file with data attached to it. Each invoice or associated note needs its own unique identifier. Cleared tax invoices come back carrying a cryptographic stamp — an electronic stamp produced by cryptographic means, so the document’s authenticity can be checked rather than taken on trust — along with a QR code added at clearance.

Before any of that can happen, the system that generates your invoices has to be onboarded. The authority treats it as a unit that identifies itself, and onboarding is how it obtains the cryptographic stamp identifier it uses from then on. That is a real step with its own failure modes, and it is the one most likely to be discovered late, because nothing about it appears in a feature list.

What this means for an Odoo install specifically

Which version you are on, and what has been done to it

Odoo’s Saudi localisation has moved over successive versions, and so has the platform’s accounting layer, so the only trustworthy answer to “does our Odoo do this” comes from pushing a real invoice through your own install and seeing what comes back. A feature list will not tell you, and neither will we from the outside. If your invoice numbering, your invoice reports or your partner records have been customised — and on an install more than a couple of years old they usually have — the question stops being about Odoo and becomes about your Odoo.

Your master data will fail before your integration does

The pattern is the same in every structured-invoicing regime we have worked in. The connection gets built in a predictable amount of time. The invoices then get refused because a customer has no registration number, a tax treatment was applied by habit rather than mapped to a permitted category, or a unit of measure exists only as free text somebody typed. Our write-up of how a single coded field breaks a whole invoice run is a UAE example of exactly this failure, and the method for finding every record that will fail — rather than the one that did — transfers directly.

What happens when clearance says no

Design the refusal path before the happy path, because the refusal path is the one that will run every day for the first few weeks. Somebody has to see that a document was refused, understand the reason in plain language rather than as a code, fix the underlying record rather than the single invoice, and re-submit. If that work lands in a queue nobody owns, you have built a compliance system that quietly stops being compliant, which is worse than not having built it.

What we would tell you not to do

Do not stack a version upgrade onto this project because a deadline makes it feel like the moment. They are two risks and combining them is how dates get missed. If the upgrade is genuinely needed, sequence it — our Odoo support and upgrade work exists for that, and it is a separate conversation on purpose.

Do not buy an integration before you know which of your entities and which of your invoice types are in scope, and do not take that answer from a software firm. It is a question for your tax adviser, and settling it in writing first is the cheapest thing you will do on this project.

And if you issue a small, stable number of straightforward invoices, look seriously at doing this through the tooling available to you by hand before you commission anything. That is a real option and it costs you nothing to evaluate.

Being straight about our own position

We build Odoo integrations and we would like to build yours, so weigh that. What we will not do is tell you we are certified by the authority, because we are not, or imply that appointing us transfers the obligation, because it does not. The compliance is yours. What a build buys you is a system that can produce documents that pass, and a path for the ones that do not. Nothing here is tax or legal advice; the scope, the waves and the dates that apply to your business belong to ZATCA’s published resolutions and to your own tax adviser.

Where to start

Three things, in order. Confirm with your adviser which entities and invoice types are in scope and what your own timing is. List every place in the business that issues an invoice, including the till and the spreadsheet, because each one is a system that has to be onboarded or retired. Then take twenty real customer records and twenty real invoice lines and check them against what the specification asks for. The third exercise is the one that tells you whether this is a small integration or a data project with an integration at the end, and it is also the one the Odoo work we do is usually hired to finish.