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.
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 :
| Vague | Fenêtre de mise en production | Seuil de revenus | Période de référence |
|---|---|---|---|
| Vague 1 | 1er janv. 2023 | 3 milliards SAR+ | 2021 |
| Vague 2 | 1er juil. 2023 | 500 millions SAR+ | 2021 |
| Vague 3 | 1er oct. 2023 | 250 millions SAR+ | 2021 ou 2022 |
| Vagues 4-10 | Nov. 2023 - Déc. 2024 | 150M à 5M SAR | Divers |
| Vagues 11-22 | Janv. 2025 - Déc. 2025 | 4M à 1M SAR | 2022, 2023 ou 2024 |
| Vague 23 | 1er janv. - 31 mars 2026 | 750 000 SAR+ | 2022, 2023 ou 2024 |
| Vague 24 | 1er avr. - 30 juin 2026 | 375 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
nameencodant un flag binaire de 7 chiffres (ex.0100000pour 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 :
| Tag | Champ | Type |
|---|---|---|
| 1 | Nom du vendeur | Chaîne UTF-8 |
| 2 | Numéro d'enregistrement TVA (TRN) | Chaîne UTF-8 |
| 3 | Horodatage de la facture (ISO 8601) | Chaîne UTF-8 |
| 4 | Total de la facture (TVA incluse) | Chaîne UTF-8 |
| 5 | Total TVA | Chaîne UTF-8 |
| 6 | Hash SHA-256 du XML | Tableau d'octets |
| 7 | Signature ECDSA | Tableau d'octets |
| 8 | Clé publique | Tableau d'octets |
| 9 | Signature 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 :
- Construire la facture XML non signée avec tous les champs obligatoires
- Calculer le hash SHA-256 du XML canonicalisé
- Signer le hash en utilisant ECDSA avec votre clé privée
- Intégrer la signature XMLDSig dans l'élément
UBLExtensions - Calculer le payload TLV du QR code incluant la signature et le hash
- Définir le Previous Invoice Hash au hash de la facture précédente
- 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,WARNINGouERROR - infoMessages, warningMessages, errorMessages : tableaux avec les champs
type,code,category,messageetstatus
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 :
| Erreur | Cause | Correction |
|---|---|---|
Invalid Invoice Hash | Hash 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 CSR | CSR 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 exists | Réutilisation d'un UUID d'une facture précédemment soumise ou rejetée | Générez un UUID v4 frais pour chaque tentative de soumission, y compris les resoumissions après rejet. |
ICV sequence broken | L'Invoice Counter Value n'est pas strictement séquentiel ou a des lacunes | Assurez-vous que votre ICV est un compteur atomiquement incrémenté par unité EGS. Ne sautez et ne réutilisez jamais de valeurs. |
PIH mismatch | Le Previous Invoice Hash ne correspond pas au hash que ZATCA a en registre pour la facture précédente | Votre 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 signature | Signature calculée avec la mauvaise clé, ou le contenu signé ne correspond pas au XML soumis | Vé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 field | Un élément XML requis est absent ou vide | Croisez chaque champ avec le Dictionnaire de Données ZATCA. Omissions courantes : IssueTime, TaxCurrencyCode, BuildingNumber dans l'adresse. |
Certificate expired | Le CSID de production a dépassé sa date d'expiration | Implé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 :
- Générer une paire de clés et un CSR avec toutes les extensions requises
- Soumettre le CSR à l'endpoint de conformité sandbox ; vérifier que vous recevez un CCSID
- Construire et signer un exemple de facture standard XML ; soumettre pour vérification de conformité
- Construire et signer un exemple de facture simplifiée XML ; soumettre pour vérification de conformité
- Construire et signer des notes de crédit et de débit ; soumettre pour vérification de conformité
- Demander un CSID de production en utilisant l'endpoint sandbox
- Soumettre une facture standard via l'endpoint de reporting ; vérifier la réponse
PASS - Soumettre une facture simplifiée via l'endpoint de validation ; vérifier que vous recevez une
clearedInvoice - 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
- 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
notAfterdu 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
WARNINGetERROR, 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
clearedInvoiceretourné 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,PostalZoneetCountryCode. 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.