ZATCA phase 2 (Arabie saoudite) : facturation électronique dans Odoo

L'Arabie saoudite a déployé la facturation électronique obligatoire en deux phases par l'intermédiaire de la ZATCA (Zakat, Tax and Customs Authority), sous le nom de Fatoorah. La phase 1 (depuis décembre 2021) exigeait déjà de générer et de conserver des factures électroniques structurées. La phase 2 va beaucoup plus loin : une intégration technique directe avec la plateforme de l'administration.

Ce qu'est exactement la phase 2 (Integration Phase)

La phase 2 est connue sous le nom d'Integration Phase. Il ne suffit plus de générer la facture : votre système de facturation doit se connecter par API à la plateforme de la ZATCA (Fatoora) et suivre un format et un cycle de validation précis.

La ZATCA distingue deux types de documents, avec des flux différents :

• Standard Tax Invoice (B2B/B2G) : exige le clearance. La facture est envoyée à la ZATCA avant d'être remise au client ; la ZATCA la valide, y appose un sceau cryptographique et la renvoie autorisée.
• Simplified Tax Invoice (B2C) : exige le reporting. Elle est remise au client sur-le-champ avec son QR et déclarée à la ZATCA dans les 24 heures qui suivent.

Exigences techniques incontournables

• Facture au format XML UBL 2.1 (ou PDF/A-3 avec XML intégré) selon le schéma de la ZATCA.
• Signature cryptographique avec un certificat délivré par la ZATCA après l'onboarding de l'appareil (CSID).
• Hash chaîné (PIH, Previous Invoice Hash) qui relie chaque facture à la précédente et garantit l'intégrité de la série.
• Code QR avec des champs TLV (nom du vendeur, numéro de TVA, date, total, TVA et sceau cryptographique), lisible par l'application de la ZATCA.
• UUID unique par facture et compteur séquentiel (ICV) que la ZATCA vérifie pour détecter les trous.

Comment cela fonctionne dans Odoo 19

Notre module intègre tout ce cycle dans le flux de facturation natif d'Odoo, sans back-office externe. Quand vous confirmez une facture, Odoo génère le XML UBL, calcule le hash chaîné, l'envoie à signer avec le certificat de la ZATCA, construit le QR et lance l'appel de clearance ou de reporting selon le type de document.

Chaque facture conserve son statut vis-à-vis de la ZATCA (acceptée, acceptée avec avertissements ou rejetée), le message de l'administration et le sceau renvoyé. Si la ZATCA rejette un document, le motif est enregistré sur la facture elle-même pour pouvoir la corriger et la renvoyer, sans perdre la traçabilité.

Ce qu'il faut surveiller avant votre date limite

• Confirmez votre wave et la date exacte dans le courrier de notification de la ZATCA : la fenêtre d'intégration s'ouvre des mois à l'avance, mais le délai, lui, est ferme.
• Des données de base propres : le numéro de TVA, l'adresse, le code postal et le régime de TVA doivent être corrects dans Odoo, faute de quoi le clearance échouera.
• Testez d'abord dans le sandbox de la ZATCA : l'onboarding du certificat et les premières factures doivent être validés dans l'environnement de test avant de passer en production.
• Ne mélangez pas les séries : le hash chaîné (PIH) exige une numérotation continue ; un saut ou une facture en double rompt la chaîne.

La phase 2 de la ZATCA n'est pas un ajout cosmétique : elle change la façon d'émettre chaque facture. Bien réalisée dans Odoo, elle est transparente pour l'équipe de facturation ; réalisée à moitié, elle se traduit par des factures rejetées et du travail manuel chaque jour.

Ce que nous faisons à ce sujet