Table des matières
Dissipons immédiatement un énorme malentendu : Vous ne pouvez pas générer une facture électronique saoudienne officielle simplement en tapant des données dans un générateur de code QR en ligne.
La création d'un système ERP ou POS conforme à l'Autorité Zakat, Tax and Customs Authority (ZATCA) d'Arabie Saoudite est une entreprise d'ingénierie logicielle complexe. En tant qu'architecte systèmes ayant récemment conçu des solutions techniques reliant la Phase 1 à la Phase 2, je peux vous dire que le véritable défi n'est pas le rendu graphique du QR, c'est la stricte logique cryptographique requise pour générer la chaîne sous-jacente.
La Réalité de la Conformité ZATCA
Si un client scanne votre reçu imprimé avec l'application mobile officielle ZATCA et qu'elle affiche une erreur "Code QR Invalide", le problème ne vient pas de votre imprimante. Le problème vient de votre code.
ZATCA exige que votre ERP prenne des données de facturation spécifiques, les encode dans un tableau d'octets précis en utilisant la méthode Tag-Length-Value (TLV), les hache, les signe, et convertisse enfin ce tableau en une chaîne Base64. C'est seulement alors que cette chaîne Base64 est convertie en code QR.
L'Anatomie du Codage TLV
Dans la Phase 1, l'exigence était relativement simple. Vous deviez construire un tableau d'octets mappant 5 balises principales. Le TLV fonctionne exactement comme son nom l'indique :
- Tag (Balise) (1 octet) : L'identifiant (ex.,
01pour le Nom du Vendeur). - Length (Longueur) (1 octet) : La longueur de la valeur en octets (ex.,
0Fpour 15 octets). - Value (Valeur) (Variable) : Les données réelles encodées en UTF-8 (ex.,
Mahwar KSA).
def get_tlv_hex(tag: int, value: str) -> str:
val_bytes = value.encode('utf-8')
tag_hex = f"{tag:02x}"
length_hex = f"{len(val_bytes):02x}"
val_hex = val_bytes.hex()
return tag_hex + length_hex + val_hex
Le Changement Cryptographique en Phase 2 (Intégration)
La Phase 2 (Phase d'Intégration) connecte votre ERP directement au portail FATOORA. Les règles de génération de codes QR sont devenues exponentiellement plus difficiles. ZATCA exige désormais des balises supplémentaires (Balises 6 à 9) pour garantir l'authenticité de la facture :
- Balise 6 (Hachage de Facture XML) : Un hachage SHA-256 de la facture XML générée.
- Balise 7 (Signature ECDSA) : Une signature cryptographique générée à l'aide de la clé privée du contribuable.
- Balise 8 (Clé Publique ECDSA) : La clé publique correspondant à la clé privée utilisée pour signer la facture.
- Balise 9 (Timbre Cryptographique) : Fourni par ZATCA lui-même après autorisation réussie de l'API.
Si votre tableau d'octets diffère d'un seul caractère, ou si vous essayez d'encoder la chaîne en utilisant un ASCII standard au lieu de conversions hexadécimales UTF-8 strictes, la chaîne Base64 résultante sera rejetée par l'application ZATCA.
Le Dilemme des Tests QA pour les Développeurs
Lorsque vous écrivez la logique backend dans Odoo, Salla ou un wrapper Python personnalisé, vous générez des centaines de chaînes Base64 de test. Pour vous assurer que votre cryptographie est correcte, vous devez physiquement scanner les codes QR avec l'application officielle ZATCA. Mais comment tester rapidement 500 chaînes Base64 sans construire votre propre outil de rendu front-end à partir de zéro ?
Tests par Lots de Chaînes Base64 en Local
C'est exactement là que le Générateur BulkBarcode agit comme un environnement de test (sandbox) critique pour les développeurs.
Nous n'avons pas conçu cet outil pour créer des factures. Nous l'avons construit pour que les ingénieurs logiciels puissent tester rapidement les sorties de leur ERP. En utilisant notre espace de travail côté client, votre équipe peut se concentrer purement sur la correction de sa cryptographie.
Le Flux de Travail de Test Sécurisé :
- Extraire les Hachages : Interrogez la base de données de votre ERP et récupérez une liste de 500 chaînes Base64 de test.
- Coller et Rendre : Collez cette liste directement dans notre espace de travail. Étant donné que notre moteur fonctionne entièrement sur WebAssembly dans votre navigateur, vos hachages et données TLV ne quittent jamais votre ordinateur.
- Scanner et Vérifier : L'espace de travail rend instantanément 500 codes QR haute résolution sur votre écran. Prenez votre téléphone, ouvrez l'application ZATCA officielle et scannez-les pour vérifier votre encodage.
Une fois que votre logiciel a passé les tests QA, votre ERP gérera automatiquement la facturation électronique ZATCA au niveau du point de vente. Vous pourrez alors utiliser BulkBarcode pour ce qu'il fait de mieux : le formatage d'étiquettes de rayonnage d'entrepôt et le suivi GS1.
Testez (QA) vos Hachages Base64
Collez la sortie Base64 de votre ERP dans notre moteur de rendu sécurisé côté client pour générer instantanément des codes QR scannables.