ZATCA

La résolution ZATCA sur la facturation électronique (Zakat, Tax and Customs Authority) impose aux entreprises opérant en Arabie saoudite de générer et soumettre des factures électroniques au format UBL XML. La REST API de B2Brouter permet à votre entreprise d’être totalement conforme à la ZATCA, en prenant en charge pour vous la génération XML, le chaînage de hash et le processus de clearance.

Qu’est-ce que la facturation électronique ZATCA ?

La facturation électronique ZATCA (Fatoorah) exige :

• La génération de factures au format UBL 2.1 XML, avec des extensions spécifiques à l’Arabie saoudite.
• Le calcul d’une chaîne de hash SHA-256 reliant chaque facture à la précédente.
• L’envoi de chaque facture à la ZATCA Clearance API pour validation et signature numérique.
• L’intégration dans la facture émise du code QR retourné par la ZATCA.

Avec B2Brouter, vous pouvez externaliser tout cela. Vous émettez des factures ou créez des déclarations fiscales via des appels REST, et B2Brouter gère le chaînage, le clearance et la génération du QR code.

Exigences du compte (entreprise)

Les factures ZATCA sont émises par des entreprises saoudiennes. Le compte doit avoir country: "sa". Les champs suivants sont obligatoires pour les comptes SA :

Paramètre API	Description	Notes
name	Raison sociale de l’entreprise	Obligatoire
country	Doit être "sa"	Obligatoire
address	Nom de rue	Obligatoire
address2	Numéro du bâtiment	Obligatoire, entier à 4 chiffres
city	Ville	Obligatoire
postalcode	Code postal	Obligatoire
province	District	Obligatoire
tin_value	Numéro d’immatriculation TVA (15 chiffres)	Obligatoire
tin_scheme	Doit être 9760 (TVA saoudienne)	Obligatoire

Remarque : Les champs address2 et province correspondent respectivement aux notions saoudiennes de numéro du bâtiment et de district. Utilisez address2 et province comme noms de paramètres dans l’API ; les erreurs de validation feront référence à ces noms.

Exigences des contacts

Les contacts (acheteurs) des factures ZATCA doivent également avoir des données d’adresse correctes. Les champs suivants s’appliquent lorsque country est "sa" :

Paramètre API	Description	Notes
name	Raison sociale de l’acheteur	Obligatoire
country	Code pays ISO-2	Obligatoire
address	Nom de rue	Obligatoire pour les contacts SA avec ZATCA activé
address2	Numéro du bâtiment	Obligatoire pour les contacts SA avec ZATCA activé
city	Ville	Obligatoire pour les contacts SA avec ZATCA activé
postalcode	Code postal	Obligatoire pour les contacts SA avec ZATCA activé
province	District	Obligatoire pour les contacts SA avec ZATCA activé
tin_value	Numéro d’immatriculation TVA	Obligatoire pour les factures B2B
tin_scheme	9760 pour la TVA saoudienne ; voir types d’identifiant de l’acheteur pour les acheteurs étrangers	Obligatoire

Exigences de facture

Les factures ZATCA utilisent SAR (riyal saoudien) comme devise. Les taxes doivent utiliser name: "VAT" et category: "S" pour le taux standard de 15 %.

Exemple minimal de facture :

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/invoices \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '{
    "send_after_import": true,
    "invoice": {
      "date": "2025-01-15",
      "number": "INV-001",
      "currency": "SAR",
      "payment_method": 1,
      "contact": {
        "name": "Buyer Company Ltd",
        "address": "King Fahd Road",
        "address2": "1234",
        "city": "Riyadh",
        "postalcode": "12345",
        "province": "Riyadh",
        "country": "sa",
        "tin_value": "310175397400003",
        "tin_scheme": 9760,
        "language": "en",
        "currency": "SAR"
      },
      "invoice_lines_attributes": [
        {
          "quantity": 1.0,
          "description": "Professional services",
          "price": 100.0,
          "taxes_attributes": [
            {
              "name": "VAT",
              "percent": 15.0,
              "category": "S"
            }
          ]
        }
      ]
    }
  }'

Catégories fiscales et codes d’exonération

La ZATCA définit quatre catégories de TVA. Pour les catégories E (exonérée) et Z (taux zéro), un code de motif d’exonération valide (comment sur la ligne de taxe) est obligatoire ; sinon la facture sera rejetée.

Catégorie	Description	Taux	Code d’exonération requis ?
S	Taux standard	15%	Non
E	Exonérée de TVA	0%	Oui — VATEX-SA-29, VATEX-SA-29-7 ou VATEX-SA-30
Z	Taux zéro	0%	Oui — voir tableau ci-dessous
O	Hors champ	0%	Non

Le code d’exonération se définit dans le champ comment de la ligne de taxe :

{
  "name": "VAT",
  "percent": 0.0,
  "category": "Z",
  "comment": "VATEX-SA-32"
}

Codes VATEX-SA-* valides

Catégorie E — Exonérée de TVA

Code	Description
VATEX-SA-29	Services financiers mentionnés à l’article 29 du règlement TVA
VATEX-SA-29-7	Services d’assurance-vie mentionnés à l’article 29 du règlement TVA
VATEX-SA-30	Opérations immobilières mentionnées à l’article 30 du règlement TVA

Catégorie Z — Taux zéro

Code	Description
VATEX-SA-32	Exportation de biens
VATEX-SA-33	Exportation de services
VATEX-SA-34-1	Transport international de marchandises
VATEX-SA-34-2	Transport international de passagers
VATEX-SA-34-3	Services directement liés et accessoires à un transport international de passagers
VATEX-SA-34-4	Fourniture d’un moyen de transport qualifié
VATEX-SA-34-5	Tout service lié au transport de biens ou de passagers
VATEX-SA-35	Médicaments et équipements médicaux
VATEX-SA-36	Métaux qualifiés
VATEX-SA-EDU	Enseignement privé au citoyen
VATEX-SA-HEA	Santé privée au citoyen
VATEX-SA-MLTRY	Fourniture de biens militaires qualifiés
VATEX-SA-DIPLOMAT	Fournitures qualifiées à des missions diplomatiques
VATEX-SA-DUTYFREE	Fourniture qualifiée de biens en zone duty free
VATEX-SA-32(bis)	Fourniture sous régime de suspension douanière
VATEX-SA-ROYALDECREE	Fourniture sur laquelle le gouvernement supporte la TVA

Catégorie O — Hors champ

Code	Description
VATEX-SA-OOS	Services hors champ de la taxe / non soumis à la TVA

Types d’identifiant de l’acheteur

Pour les acheteurs étrangers (hors SA), utilisez tin_scheme pour préciser le type d’identifiant :

tin_scheme	Description
9760	Numéro d’immatriculation TVA saoudien
0002	Numéro de TVA UE
0003	Numéro de passeport
0004	Identifiant officiel (pays de résidence)
0005	Certificat de résidence
0006	Autre document
0007	Non enregistré

Cycle de vie du tax report

Après la création ou l’envoi d’une facture, le clearance ZATCA est asynchrone. Le tax_report sera d’abord en état processing.

Suivez la progression via :

• Webhook (recommandé) : abonnez-vous au webhook de changement d’état du tax report. États finaux : registered, error, registered_with_errors.
• Polling : appelez le endpoint de récupération d’un tax report jusqu’à obtenir un état final.

Mappage des champs : Invoice API → XML ZATCA

Champ de l’Invoice API	Élément XML ZATCA
number	cbc:ID
date	cbc:IssueDate
company.tin_value	cbc:CompanyID du fournisseur
company.address2	cbc:BuildingNumber du fournisseur
company.province	cbc:District du fournisseur
contact.tin_value	cbc:CompanyID du client
contact.address2	cbc:BuildingNumber du client
contact.province	cbc:District du client
tax.percent	cbc:Percent
tax.category	cbc:ID dans cac:TaxCategory
tax.comment	cbc:TaxExemptionReasonCode
invoice.total	cbc:TaxInclusiveAmount
invoice.subtotal	cbc:TaxExclusiveAmount