22 min de lecture

Guide d'intégration ZATCA Phase 2 : checklist développeur vague par vague

Un guide technique des exigences d'intégration ZATCA Phase 2, des calendriers de vagues, de la conformité XML/UBL, de la signature cryptographique et de l'onboarding API pour la facturation électronique saoudienne.

ZATCA Phase 2
Facturation électronique Arabie Saoudite
Plateforme FATOORA
UBL 2.1
Intégration e-invoicing
Conformité Arabie Saoudite
Signature numérique XML

1. Facturation électronique ZATCA : Phase 1 vs Phase 2

Le mandat de facturation électronique d'Arabie Saoudite, régi par la Zakat, Tax and Customs Authority (ZATCA), est déployé en deux phases distinctes.

La Phase 1 (Phase de Génération), effective depuis le 4 décembre 2021, exigeait de tous les contribuables assujettis à la TVA qu'ils génèrent des factures électroniques et des notes de crédit/débit dans un format numérique structuré via une Solution de Facturation Électronique (EGS) conforme. La Phase 1 portait principalement sur le format : arrêter d'émettre des factures manuscrites ou non structurées, commencer à produire des documents lisibles par machine avec des champs obligatoires, des QR codes et des UUID. Aucune connectivité API vers ZATCA n'était requise. Les factures étaient générées et stockées localement.

La Phase 2 (Phase d'Intégration), déployée par vagues depuis le 1er janvier 2023, est fondamentalement différente. Elle exige une intégration en temps réel ou quasi-temps réel avec la plateforme Fatoora de ZATCA via API. Selon le type de facture, les documents doivent être soit déclarés (transmis à ZATCA sous 24 heures) soit validés (validés et tamponnés par ZATCA avant d'être partagés avec l'acheteur). La Phase 2 introduit aussi des exigences de signature cryptographique, une validation de schéma XML plus stricte et un processus d'onboarding formel impliquant des Certificate Signing Requests (CSR) et des Cryptographic Stamp Identifiers (CSID).

Si vous construisez ou maintenez un système de facturation pour le marché saoudien, c'est dans la Phase 2 que réside la complexité d'ingénierie. Le reste de ce guide se concentre sur ce que vous devez implémenter.

2. Calendrier des vagues : qui est concerné et quand

ZATCA déploie la Phase 2 par vagues, chacune ciblant les contribuables en fonction de leur chiffre d'affaires imposable sur des années civiles spécifiques. Les contribuables sont notifiés au moins six mois avant leur deadline de mise en production. Voici le calendrier des vagues les plus récentes, pertinentes pour les entreprises se mettant en conformité maintenant :

VagueFenêtre de mise en productionSeuil de revenusPériode de référence
Vague 11er janv. 20233 milliards SAR+2021
Vague 21er juil. 2023500 millions SAR+2021
Vague 31er oct. 2023250 millions SAR+2021 ou 2022
Vagues 4-10Nov. 2023 - Déc. 2024150M à 5M SARDivers
Vagues 11-22Janv. 2025 - Déc. 20254M à 1M SAR2022, 2023 ou 2024
Vague 231er janv. - 31 mars 2026750 000 SAR+2022, 2023 ou 2024
Vague 241er avr. - 30 juin 2026375 000 SAR+2022, 2023 ou 2024

Note : ZATCA continue d'annoncer de nouvelles vagues périodiquement. Vérifiez votre affectation de vague spécifique sur la page officielle de déploiement de ZATCA. Si votre revenu a dépassé le seuil dans l'une des années civiles de référence, vous êtes dans le périmètre.

La tendance est claire : le seuil baisse à chaque vague. Pratiquement toutes les entreprises assujetties à la TVA en Arabie Saoudite auront éventuellement besoin de l'intégration Phase 2. Si vous êtes un éditeur de logiciel servant le marché saoudien, traiter cela comme une fonctionnalité core plutôt qu'un projet ponctuel est la bonne approche.

3. Exigences techniques : structure XML UBL 2.1

3.1 Format

Toutes les factures électroniques Phase 2 doivent être générées au format UBL 2.1 XML, conforme au Standard d'Implémentation XML de ZATCA (lui-même un profil contraint de la norme ISO EN 16931). Alternativement, un PDF/A-3 avec un payload XML UBL 2.1 intégré est accepté, mais le XML est la donnée faisant autorité ; le PDF est la représentation visuelle.

3.2 Types de factures

ZATCA distingue deux types de factures, chacun avec des flux de traitement différents :

  • Facture fiscale standard (B2B) : émise pour les transactions inter-entreprises. Soumise au reporting (soumission asynchrone à ZATCA sous 24 heures).
  • Facture fiscale simplifiée (B2C) : émise pour les transactions entreprise-consommateur. Soumise à la validation (validation synchrone par ZATCA avant que la facture puisse être partagée avec l'acheteur).

3.3 Champs XML obligatoires

Les champs suivants sont obligatoires dans chaque facture XML Phase 2. Ce n'est pas exhaustif ; consultez le Dictionnaire de Données ZATCA pour la spécification complète.

1<?xml version="1.0" encoding="UTF-8"?> 2<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2" 3 xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" 4 xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" 5 xmlns:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2"> 6 7 <!-- UBL Extensions: contient la signature numérique --> 8 <ext:UBLExtensions> 9 <ext:UBLExtension> 10 <ext:ExtensionContent> 11 <!-- Bloc de signature XMLDSig inséré ici --> 12 </ext:ExtensionContent> 13 </ext:UBLExtension> 14 </ext:UBLExtensions> 15 16 <cbc:ProfileID>reporting:1.0</cbc:ProfileID> 17 <cbc:ID>INV-2026-00042</cbc:ID> 18 <cbc:UUID>6f4d20e0-6bfe-4a80-9389-7dabe6620f12</cbc:UUID> 19 <cbc:IssueDate>2026-04-15</cbc:IssueDate> 20 <cbc:IssueTime>14:30:00</cbc:IssueTime> 21 <cbc:InvoiceTypeCode name="0100000">388</cbc:InvoiceTypeCode> 22 <cbc:DocumentCurrencyCode>SAR</cbc:DocumentCurrencyCode> 23 <cbc:TaxCurrencyCode>SAR</cbc:TaxCurrencyCode> 24 25 <!-- Hash de la facture précédente (intégrité de la chaîne) --> 26 <cac:AdditionalDocumentReference> 27 <cbc:ID>PIH</cbc:ID> 28 <cac:Attachment> 29 <cbc:EmbeddedDocumentBinaryObject mimeCode="text/plain"> 30 NWZlY2ViNjZmZmM4NmYzOGQ5NTI3ODZjNmQ2OTZjNzlj... 31 </cbc:EmbeddedDocumentBinaryObject> 32 </cac:Attachment> 33 </cac:AdditionalDocumentReference> 34 35 <!-- QR Code --> 36 <cac:AdditionalDocumentReference> 37 <cbc:ID>QR</cbc:ID> 38 <cac:Attachment> 39 <cbc:EmbeddedDocumentBinaryObject mimeCode="text/plain"> 40 <!-- Données QR TLV encodées en Base64 --> 41 </cbc:EmbeddedDocumentBinaryObject> 42 </cac:Attachment> 43 </cac:AdditionalDocumentReference> 44 45 <!-- Vendeur (AccountingSupplierParty) --> 46 <cac:AccountingSupplierParty> 47 <cac:Party> 48 <cac:PartyIdentification> 49 <cbc:ID schemeID="CRN">1234567890</cbc:ID> 50 </cac:PartyIdentification> 51 <cac:PostalAddress> 52 <cbc:StreetName>King Fahd Road</cbc:StreetName> 53 <cbc:BuildingNumber>1234</cbc:BuildingNumber> 54 <cbc:CityName>Riyadh</cbc:CityName> 55 <cbc:PostalZone>12345</cbc:PostalZone> 56 <cac:Country><cbc:IdentificationCode>SA</cbc:IdentificationCode></cac:Country> 57 </cac:PostalAddress> 58 <cac:PartyTaxScheme> 59 <cbc:CompanyID>300000000000003</cbc:CompanyID> 60 <cac:TaxScheme><cbc:ID>VAT</cbc:ID></cac:TaxScheme> 61 </cac:PartyTaxScheme> 62 <cac:PartyLegalEntity> 63 <cbc:RegistrationName>Acme Trading Co</cbc:RegistrationName> 64 </cac:PartyLegalEntity> 65 </cac:Party> 66 </cac:AccountingSupplierParty> 67 68 <!-- Lignes de facture, totaux de taxes, totaux monétaires suivent --> 69</Invoice>

Points clés :

  • UUID doit être un UUID v4 valide, unique par facture. Après un rejet, vous devez générer un nouvel UUID ; ne réutilisez jamais un UUID.
  • InvoiceTypeCode utilise un attribut name encodant un flag binaire de 7 chiffres (ex. 0100000 pour une facture fiscale standard).
  • Previous Invoice Hash (PIH) chaîne chaque facture à la précédente, créant une séquence inviolable. La première facture d'une chaîne utilise l'encodage Base64 du SHA-256 de 0.
  • Invoice Counter Value (ICV) doit être un entier séquentiel qui ne décroît jamais et ne se répète jamais au sein d'une unité EGS.

3.4 QR Code avec encodage TLV

Le QR code intégré dans les factures Phase 2 utilise l'encodage Tag-Length-Value (TLV), puis est encodé en Base64. Les tags TLV requis sont :

TagChampType
1Nom du vendeurChaîne UTF-8
2Numéro d'enregistrement TVA (TRN)Chaîne UTF-8
3Horodatage de la facture (ISO 8601)Chaîne UTF-8
4Total de la facture (TVA incluse)Chaîne UTF-8
5Total TVAChaîne UTF-8
6Hash SHA-256 du XMLTableau d'octets
7Signature ECDSATableau d'octets
8Clé publiqueTableau d'octets
9Signature du certificat (tampon CSID)Tableau d'octets

Les tags 1-5 étaient requis en Phase 1. Les tags 6-9 sont des ajouts Phase 2 et sont ce qui rend le QR code vérifiable cryptographiquement.

1# Pseudocode : encodage TLV pour QR 2def tlv_encode(tag: int, value: bytes) -> bytes: 3 return bytes([tag]) + bytes([len(value)]) + value 4 5qr_payload = b"" 6qr_payload += tlv_encode(1, seller_name.encode("utf-8")) 7qr_payload += tlv_encode(2, vat_number.encode("utf-8")) 8qr_payload += tlv_encode(3, timestamp_iso.encode("utf-8")) 9qr_payload += tlv_encode(4, str(total_with_vat).encode("utf-8")) 10qr_payload += tlv_encode(5, str(vat_amount).encode("utf-8")) 11qr_payload += tlv_encode(6, invoice_hash_bytes) 12qr_payload += tlv_encode(7, ecdsa_signature_bytes) 13qr_payload += tlv_encode(8, public_key_bytes) 14qr_payload += tlv_encode(9, certificate_signature_bytes) 15 16qr_base64 = base64.b64encode(qr_payload).decode("ascii")

Important : Pour les valeurs de plus de 127 octets (courant pour les tags 7-9), l'encodage de la longueur TLV utilise plusieurs octets. Consultez les directives techniques de ZATCA pour les règles exactes d'encodage de longueur multi-octets.

4. Signature cryptographique : ECDSA, CSR et CSID

4.1 Génération de clés

ZATCA impose ECDSA avec la courbe elliptique secp256k1 pour la signature des factures. Générez votre clé privée avec OpenSSL :

1# Générer la clé privée EC 2openssl ecparam -name secp256k1 -genkey -noout -out ec-secp256k1-priv-key.pem 3 4# Générer un Certificate Signing Request (CSR) 5openssl req -new -sha256 \ 6 -key ec-secp256k1-priv-key.pem \ 7 -out taxpayer.csr \ 8 -subj "/CN=EGS-Unit-01/OU=MyBranch/O=MyCompany/C=SA" \ 9 -addext "subjectAltName=DNS:egs1.mycompany.com,dirName:cn=TST-886431145-399999999900003,serialNumber=1-TST|2-TST|3-ed22f1d8-e6a2-1118-9b58-d9a8f11e445f" \ 10 -addext "certificateTemplateName=ZATCA-Code-Signing" \ 11 -addext "1.3.6.1.4.1.311.20.2=ASN1:UTF8String:TSTZATCA-Code-Signing"

Le CSR doit contenir des extensions spécifiques mandatées par ZATCA, incluant :

  • Organization Identifier (OID 2.5.4.97) : formaté comme TST-{TIN}-{CRN} pour le sandbox ou le préfixe production équivalent.
  • Certificate Template Name : doit être ZATCA-Code-Signing.
  • EGS Serial Number : une chaîne délimitée par des pipes contenant le nom de la solution, l'identifiant matériel et un UUID pour l'unité EGS.

4.2 Onboarding : du CSID de conformité au CSID de production

Le processus d'onboarding comporte trois étapes :

Étape 1 : Obtenir un CSID de conformité (CCSID)

Soumettez votre CSR à l'endpoint de conformité de ZATCA. Vous recevez un CSID de conformité (certificat) et un ID de requête.

1curl -X POST \ 2 https://gw-fatoora.zatca.gov.sa/e-invoicing/core/compliance \ 3 -H "Content-Type: application/json" \ 4 -H "Accept-Version: V2" \ 5 -H "OTP: 123456" \ 6 -d '{ 7 "csr": "<CSR encodé en Base64>" 8 }'

Le header OTP contient un mot de passe à usage unique fourni par ZATCA pendant le processus d'enregistrement. La réponse inclut binarySecurityToken (votre certificat CCSID, encodé en Base64), secret (votre mot de passe API) et requestID.

Étape 2 : Passer les vérifications de conformité

En utilisant les identifiants CCSID, soumettez des factures exemples pour la validation de conformité :

1curl -X POST \ 2 https://gw-fatoora.zatca.gov.sa/e-invoicing/core/compliance/invoices \ 3 -H "Content-Type: application/json" \ 4 -H "Accept-Version: V2" \ 5 -H "Accept-Language: en" \ 6 -u "<CCSID-Base64>:<secret>" \ 7 -d '{ 8 "invoiceHash": "<hash SHA-256 du XML de la facture>", 9 "uuid": "<UUID de la facture>", 10 "invoice": "<XML signé encodé en Base64>" 11 }'

Vous devez passer les vérifications de conformité pour tous les sous-types de factures que votre EGS va gérer : factures standard, factures simplifiées, notes de débit, notes de crédit.

Étape 3 : Obtenir un CSID de production (PCSID)

Une fois les vérifications de conformité passées, échangez votre CCSID contre un CSID de production :

1curl -X POST \ 2 https://gw-fatoora.zatca.gov.sa/e-invoicing/core/production/csids \ 3 -H "Content-Type: application/json" \ 4 -H "Accept-Version: V2" \ 5 -u "<CCSID-Base64>:<secret>" \ 6 -d '{ 7 "compliance_request_id": "<requestID de l'étape 1>" 8 }'

Le CSID de production est ce que votre EGS utilise pour la soumission de factures en production. Il a une date d'expiration ; planifiez le renouvellement avant son expiration.

4.3 Flux de signature de facture

Pour chaque facture que votre système génère :

  1. Construire la facture XML non signée avec tous les champs obligatoires
  2. Calculer le hash SHA-256 du XML canonicalisé
  3. Signer le hash en utilisant ECDSA avec votre clé privée
  4. Intégrer la signature XMLDSig dans l'élément UBLExtensions
  5. Calculer le payload TLV du QR code incluant la signature et le hash
  6. Définir le Previous Invoice Hash au hash de la facture précédente
  7. Incrémenter l'Invoice Counter Value

5. Intégration API : reporting vs validation

Avec votre CSID de production en main, le flux de soumission dépend du type de facture.

5.1 Reporting (factures standard / B2B)

Les factures fiscales standard sont déclarées de manière asynchrone. Vous soumettez la facture signée à ZATCA, et ZATCA retourne un résultat de validation. La facture est valide et peut être partagée avec l'acheteur indépendamment du résultat du reporting, mais la non-conformité déclenche des pénalités.

1curl -X POST \ 2 https://gw-fatoora.zatca.gov.sa/e-invoicing/core/invoices/reporting/single \ 3 -H "Content-Type: application/json" \ 4 -H "Accept-Version: V2" \ 5 -H "Accept-Language: en" \ 6 -H "Clearance-Status: 0" \ 7 -u "<PCSID-Base64>:<secret>" \ 8 -d '{ 9 "invoiceHash": "<hash SHA-256>", 10 "uuid": "<UUID de la facture>", 11 "invoice": "<XML signé encodé en Base64>" 12 }'

Le header Clearance-Status: 0 indique explicitement qu'il s'agit d'une requête de reporting.

5.2 Validation (factures simplifiées / B2C)

Les factures simplifiées nécessitent une validation : ZATCA valide la facture, la tamponne et retourne une version validée. Vous devez utiliser le XML retourné par ZATCA (pas votre original) comme document fiscalement valide.

1curl -X POST \ 2 https://gw-fatoora.zatca.gov.sa/e-invoicing/core/invoices/clearance/single \ 3 -H "Content-Type: application/json" \ 4 -H "Accept-Version: V2" \ 5 -H "Accept-Language: en" \ 6 -H "Clearance-Status: 1" \ 7 -u "<PCSID-Base64>:<secret>" \ 8 -d '{ 9 "invoiceHash": "<hash SHA-256>", 10 "uuid": "<UUID de la facture>", 11 "invoice": "<XML signé encodé en Base64>" 12 }'

La réponse inclut clearedInvoice (le XML tamponné par ZATCA, encodé en Base64) et un objet validationResults. Stockez et utilisez toujours la version validée.

5.3 Gestion des réponses

L'API de ZATCA retourne un objet validationResults contenant :

  • status : PASS, WARNING ou ERROR
  • infoMessages, warningMessages, errorMessages : tableaux avec les champs type, code, category, message et status

Un statut WARNING signifie que la facture a été acceptée mais a des problèmes à corriger. Un statut ERROR signifie que la facture a été rejetée. En cas de rejet, vous devez corriger le problème, générer un nouvel UUID et resoumettre.

6. Erreurs de validation courantes et comment les corriger

Voici les erreurs que les développeurs rencontrent le plus fréquemment pendant l'intégration :

ErreurCauseCorrection
Invalid Invoice HashHash calculé sur un XML non canonicalisé, ou hash de la mauvaise version XML (décalage pré-signature vs post-signature)Le hash doit être calculé sur le XML de la facture avant l'insertion du bloc UBLExtensions/Signature. Utilisez la canonicalisation XML exclusive (C14N).
Invalid CSRCSR manquant les extensions ZATCA requises (OID, nom du template, numéro de série)Régénérez le CSR avec toutes les extensions obligatoires. Vérifiez le format de l'Organization Identifier.
UUID already existsRéutilisation d'un UUID d'une facture précédemment soumise ou rejetéeGénérez un UUID v4 frais pour chaque tentative de soumission, y compris les resoumissions après rejet.
ICV sequence brokenL'Invoice Counter Value n'est pas strictement séquentiel ou a des lacunesAssurez-vous que votre ICV est un compteur atomiquement incrémenté par unité EGS. Ne sautez et ne réutilisez jamais de valeurs.
PIH mismatchLe Previous Invoice Hash ne correspond pas au hash que ZATCA a en registre pour la facture précédenteVotre système doit stocker le hash de chaque facture soumise avec succès et l'utiliser comme PIH pour la suivante. Si votre chaîne se casse, vous devrez peut-être contacter le support ZATCA.
Invalid signatureSignature calculée avec la mauvaise clé, ou le contenu signé ne correspond pas au XML soumisVérifiez que vous signez avec la clé privée correspondant à votre certificat CSID. Assurez-vous qu'aucun changement d'espacement ou d'encodage ne se produit entre la signature et la soumission.
Missing mandatory fieldUn élément XML requis est absent ou videCroisez chaque champ avec le Dictionnaire de Données ZATCA. Omissions courantes : IssueTime, TaxCurrencyCode, BuildingNumber dans l'adresse.
Certificate expiredLe CSID de production a dépassé sa date d'expirationImplémentez le renouvellement du CSID avant l'expiration. Surveillez le champ notAfter dans votre certificat.

7. Tests avec le sandbox ZATCA

ZATCA fournit un environnement sandbox qui reflète l'API de production. L'URL de base du sandbox est :

https://gw-fatoora.zatca.gov.sa/e-invoicing/developer-portal

Le sandbox supporte le flux d'onboarding complet (soumission CSR, émission CCSID, vérifications de conformité, émission PCSID) et la soumission en mode reporting et validation. Utilisez la valeur OTP 123456 pour l'onboarding sandbox.

Checklist de test :

  1. Générer une paire de clés et un CSR avec toutes les extensions requises
  2. Soumettre le CSR à l'endpoint de conformité sandbox ; vérifier que vous recevez un CCSID
  3. Construire et signer un exemple de facture standard XML ; soumettre pour vérification de conformité
  4. Construire et signer un exemple de facture simplifiée XML ; soumettre pour vérification de conformité
  5. Construire et signer des notes de crédit et de débit ; soumettre pour vérification de conformité
  6. Demander un CSID de production en utilisant l'endpoint sandbox
  7. Soumettre une facture standard via l'endpoint de reporting ; vérifier la réponse PASS
  8. Soumettre une facture simplifiée via l'endpoint de validation ; vérifier que vous recevez une clearedInvoice
  9. Soumettre délibérément une facture invalide (mauvais hash, champ manquant) et vérifier que la réponse d'erreur correspond à votre logique de gestion d'erreurs
  10. Tester la chaîne de factures : soumettre 10+ factures séquentielles et vérifier l'intégrité du PIH et de l'ICV

Conseil : Le Portail Développeur de ZATCA fournit aussi un validateur XML web et un SDK. Utilisez le validateur pour débugger les problèmes de structure XML avant de tester via API.

8. Factur-X, Peppol et contexte transfrontalier

Si votre activité ou vos clients opèrent à travers les frontières, comprendre comment l'approche de ZATCA s'inscrit dans le paysage mondial de la facturation électronique est utile.

8.1 Factur-X / ZUGFeRD

Factur-X (France) et ZUGFeRD (Allemagne) sont le même standard sous deux noms. Ils définissent un format de facture hybride : un PDF lisible par l'homme avec un payload XML structuré intégré utilisant le format UN/CEFACT Cross Industry Invoice (CII). C'est fondamentalement différent de l'approche de ZATCA :

  • ZATCA utilise le XML UBL 2.1 comme format faisant autorité, avec un enveloppement PDF/A-3 optionnel
  • Factur-X utilise le XML CII intégré dans un PDF/A-3, avec le PDF comme format de livraison principal
  • ZATCA nécessite une intégration API en temps réel avec l'autorité fiscale
  • Factur-X (en 2026) ne nécessite pas de validation en temps réel ; le modèle Plateforme de Dématérialisation Partenaire (PDP) de la France est encore en cours de déploiement

Les deux standards sont des sous-ensembles de EN 16931, la norme sémantique européenne pour la facturation électronique. Si vous construisez un système de conformité multi-pays, EN 16931 est le dénominateur commun.

8.2 Peppol

Peppol n'est pas un format ; c'est un réseau de livraison. Les factures sur Peppol utilisent le format Peppol BIS Billing 3.0, qui est basé sur UBL 2.1 (le même standard de base que ZATCA, bien qu'avec des contraintes et extensions différentes). Peppol définit comment les factures sont routées de l'expéditeur au destinataire via des Points d'Accès certifiés.

Différences clés avec ZATCA :

  • Peppol est un réseau B2B ; il n'y a pas de modèle de validation par l'autorité fiscale
  • Peppol utilise un routage à 4 coins (Point d'Accès expéditeur vers Point d'Accès destinataire) ; ZATCA utilise un modèle à 2 coins (contribuable vers ZATCA)
  • Peppol est obligatoire pour le B2G dans de nombreux pays de l'UE et de plus en plus pour le B2B (la Belgique l'impose à partir de 2026)

8.3 Implications pratiques

Si vous servez des clients qui facturent à la fois en Arabie Saoudite et dans l'UE, votre système doit gérer :

  • La génération de XML UBL 2.1 (partagée entre ZATCA et Peppol, bien que les profils diffèrent)
  • La génération de XML CII (pour les marchés Factur-X/ZUGFeRD)
  • La signature et soumission API spécifiques à ZATCA
  • La connectivité aux Points d'Accès spécifiques à Peppol
  • Des ensembles de règles de validation différents par juridiction

La bonne décision architecturale est de séparer les responsabilités : construire un modèle de données de facture de base conforme à la sémantique EN 16931, puis implémenter des sérialiseurs et adaptateurs de soumission spécifiques par juridiction.

9. Checklist de mise en production

Avant que votre EGS ne passe en production pour un contribuable spécifique, vérifiez chaque élément de cette liste :

  • Enregistrement ZATCA confirmé. Le contribuable a été notifié de son affectation de vague et de sa deadline de mise en production.
  • Unité EGS enregistrée. Chaque unité de facturation physique ou virtuelle a son propre CSR, CSID et compteur ICV séquentiel.
  • CSID de production obtenu. Vous avez échangé le CSID de conformité contre un CSID de production via l'API de production (pas le sandbox).
  • Renouvellement du CSID planifié. Vous avez automatisé ou calendé le renouvellement avant la date notAfter du certificat.
  • Chaîne de factures initialisée. Le PIH de la première facture est défini au Base64 de SHA-256(0). Les factures suivantes référencent le hash de la facture précédente.
  • Tous les types de factures testés. Factures standard, factures simplifiées, notes de crédit et notes de débit ont toutes passé les vérifications de conformité.
  • Génération du QR code vérifiée. Les QR codes encodés en TLV sont lisibles et contiennent les 9 tags. Testez avec l'application mobile de vérification de ZATCA.
  • Gestion d'erreurs implémentée. Votre système gère correctement les réponses WARNING et ERROR, génère de nouveaux UUID en cas de rejet et ne casse pas la chaîne ICV/PIH.
  • Flux de validation testé. Pour les factures simplifiées, votre système stocke et utilise le XML clearedInvoice retourné par ZATCA, pas la soumission originale.
  • Logique de réessai en place. Les échecs réseau, les timeouts et les réponses 5xx de l'API ZATCA sont gérés avec un backoff exponentiel. Les factures sont mises en file d'attente et réessayées sans perte de données.
  • Piste d'audit maintenue. Chaque tentative de soumission, réponse, UUID, ICV, hash et CSID utilisé est loggé pour l'audit de conformité.
  • Validation du schéma XML. Votre sortie XML passe la validation contre les schémas XSD publiés par ZATCA avant la soumission.
  • Champs d'adresse complets. Les adresses saoudiennes nécessitent StreetName, BuildingNumber, CityName, PostalZone et CountryCode. En manquer un est une cause courante de rejet.
  • Calculs de TVA vérifiés. Les totaux de TVA au niveau de la ligne et du document sont cohérents. L'arrondi suit les règles prescrites par ZATCA (2 décimales pour les montants en SAR).

10. Besoin d'aide pour l'intégration ?

Si vous construisez la conformité ZATCA Phase 2 dans votre logiciel, ou si votre entreprise doit devenir conforme sans remplacer votre système de facturation existant, je peux vous aider.

J'ai construit et livré l'intégration ZATCA Phase 2 pour des systèmes en production, incluant le pipeline complet de l'extraction de documents à la signature cryptographique jusqu'à la soumission et validation API. Je travaille avec les cas particuliers que les solutions génériques ratent : facturation progressive de construction, consolidation multi-entités, wrappers de systèmes legacy et intégrations ERP personnalisées.

Je couvre aussi la conformité Factur-X, Peppol et XRechnung pour les entreprises opérant entre les marchés saoudien et européen.

En savoir plus sur mes services de consulting en facturation électronique, ou réservez un appel pour discuter de vos besoins spécifiques.


Ce guide reflète les réglementations ZATCA et les calendriers de vagues en date d'avril 2026. ZATCA met à jour ses exigences périodiquement. Vérifiez toujours les affectations de vagues actuelles et les spécifications techniques sur le portail officiel de facturation électronique de ZATCA et la communauté développeur Fatoora.

© 2026 Abdelbaki Berkati. Tous droits réservés.