ZATCA e-invoicing for Odoo

By Matheel · Updated

Odoo (ERP) tells you when an order is paid; Matheel turns that payment into a ZATCA invoice, filed and accepted, with a bilingual PDF and the QR.

Odoo's Saudi localization already files with ZATCA. Matheel fits when your edition lacks it, or when you want the PDF/A-3 and device handling without the setup.

Free Odoo module: Matheel for Odoo 17 and 18 (Community and Enterprise): every invoice you post is filed with ZATCA, with the QR, PDF and XML attached to it. Install it, register the device in Settings, and skip the code below.

The event to listen to

Automation rule on account.move (customer invoices) with a 'Values Updated' trigger plus a condition payment_state = 'paid' (values: not_paid, in_payment, paid, partial, reversed, blocked, invoicing_legacy) and the action 'Send Webhook Notification'

Registering it

Studio > Automations: model account.move, trigger + condition, Action 'Send Webhook Notification' with URL and Fields (the Sample Payload previews the request)

Checking it came from Odoo

None: Odoo POSTs plain JSON with no signature or secret (ir.actions.server _run_action_webhook). Put a long random token in the URL and check it

Amount and lines

If the amount includes VAT (it usually does), send it as is with "prices_include_vat": true.

The code

It receives the event, verifies it and calls matheel_invoice(items): the ready function that locks the device row, files the invoice and saves the new token.

import hmac, os, xmlrpc.client
from flask import Flask, request, abort

app = Flask(__name__)
URL, DB, USER, KEY = (os.environ[k] for k in ("ODOO_URL", "ODOO_DB", "ODOO_USER", "ODOO_API_KEY"))

# Odoo's webhook is unsigned: the URL carries ?token=... and we check it.
@app.post("/odoo/invoice-paid")
def invoice_paid():
    if not hmac.compare_digest(request.args.get("token", ""), os.environ["ODOO_HOOK_TOKEN"]):
        abort(401)
    move_id = request.get_json()["_id"]  # account.move id sent by Send Webhook Notification
    uid = xmlrpc.client.ServerProxy(f"{URL}/xmlrpc/2/common").authenticate(DB, USER, KEY, {})
    models = xmlrpc.client.ServerProxy(f"{URL}/xmlrpc/2/object")
    lines = models.execute_kw(DB, uid, KEY, "account.move.line", "search_read",
        [[["move_id", "=", move_id], ["display_type", "=", "product"]]],
        {"fields": ["name", "quantity", "price_subtotal"]})
    items = [{"name": l["name"], "quantity": str(l["quantity"]),
              "price": f'{l["price_subtotal"] / l["quantity"]:.2f}'} for l in lines]
    matheel_invoice(items)
    return "", 200

Notes

The webhook body is {_id, _model, _action} plus the fields you pick (record.read(load=None)), so relational fields arrive as ids only, hence the XML-RPC read. 'in_payment' may come before 'paid' depending on bank reconciliation: choose which one counts as paid. Odoo's Saudi Arabia localization has its own ZATCA e-invoicing (ZATCA API integration), so Matheel fits Odoo setups that don't use it. The docs and code here are for Odoo 18.0; whether newer versions still offer XML-RPC was not checked. Odoo docs give no payload schema, only 'POST API request with the values of the selected Fields'; the shape is from the 18.0 source.

FAQ

Does Odoo file invoices with ZATCA by itself?

Odoo's Saudi localization already files with ZATCA. Matheel fits when your edition lacks it, or when you want the PDF/A-3 and device handling without the setup.

Do I have to change my prices for VAT?

No. Send the amount the customer paid with "prices_include_vat": true; Matheel backs the VAT out and keeps the amount due equal to what was paid.

What if two payments arrive in the same second?

A device's invoices go one after another. Lock the device row while filing (the ready function does), and Matheel refuses a stale device token with 409 so the chain never forks.

Official sources: www.odoo.com/documentation/18.0/applications/studio/automate · www.odoo.com/documentation/18.0/developer/reference/external · github.com/odoo/odoo/blob/18.0/odoo/addons/base/models/ir_ac · github.com/odoo/odoo/blob/18.0/addons/account/models/account · www.odoo.com/documentation/18.0/applications/finance/fiscal_

Try it now on the developer sandbox

No key, no signup: a real ZATCA answer, with the bilingual PDF and the QR.

Start Pricing