An account on the ZATCA developer portal (linked from the official site)<\/li>\n\n<\/ul>\n\n\n\nStep 1: Understand the two phases<\/h3>\n\n\n\n
The Saudi e-invoicing program is called Fatoora<\/strong>. It came in two phases.<\/p>\n\n\n\n\n- Phase 1, “Generation”<\/strong> (started December 2021). Businesses must create invoices with a computer system, not by hand. Simplified invoices need a QR code. The invoice does not go to ZATCA yet.<\/li>\n\n\n
- Phase 2, “Integration”<\/strong> (started January 2023). Your system connects to ZATCA’s platform and sends invoices to it. Businesses join in waves, and ZATCA tells each group its date.<\/li>\n\n<\/ol>\n\n\n\n
Step 2: Know the two invoice types<\/h3>\n\n\n\n\n- Standard tax invoice<\/strong>: for business to business (B2B). The buyer is a registered company.<\/li>\n\n\n
- Simplified tax invoice<\/strong>: for business to customer (B2C), like a shop receipt.<\/li>\n\n<\/ul>\n\n\n\n
In Phase 2 they travel in different ways:<\/p>\n\n\n\n
\n- Clearance<\/strong> (standard invoices): you send the invoice to ZATCA first<\/strong>. ZATCA checks it and adds its stamp. Only then do you give it to the buyer. Like passport control: no stamp, no entry.<\/li>\n\n\n
- Reporting<\/strong> (simplified invoices): you give the invoice to the customer right away, and then report it to ZATCA within 24 hours.<\/li>\n\n<\/ul>\n\n\n\n
Step 3: Learn the invoice format<\/h3>\n\n\n\n
In Phase 2, the official invoice is an XML file in the UBL 2.1<\/strong> format. XML is text with labels around each value, like <Amount>100.00<\/Amount><\/code>. UBL is an international standard for those labels, and ZATCA adds its own rules. You can give the customer a PDF, but for Phase 2 it should be a PDF\/A-3 file with the XML inside it.<\/p>\n\n\n\nEach invoice also has a UUID<\/strong> (a unique ID), an invoice counter<\/strong> that goes up by one each time, and a QR code<\/strong>.<\/p>\n\n\n\nStep 4: Build a Phase 1 QR code<\/h3>\n\n\n\n
The QR code content uses a format called TLV<\/strong>: Tag, Length, Value. Think of boxes in a row: each has a number (tag), a size (length) and content (value). The five Phase 1 tags are: seller name, VAT number, time stamp, total with VAT, and VAT amount. The result is encoded as Base64 text.<\/p>\n\n\n\nimport base64\n\ndef tlv(tag, value):\n data = value.encode(\"utf-8\") # length is in bytes, not letters\n return bytes([tag, len(data)]) + data\n\ndef phase1_qr(seller, vat_number, timestamp, total, vat):\n payload = (\n tlv(1, seller)\n + tlv(2, vat_number)\n + tlv(3, timestamp)\n + tlv(4, total)\n + tlv(5, vat)\n )\n return base64.b64encode(payload).decode(\"ascii\")\n\n# Example values only\nprint(phase1_qr(\"Example Trading Co\", \"300000000000003\",\n \"2026-06-07T12:30:00Z\", \"115.00\", \"15.00\"))<\/code><\/pre>\n\n\n\nPut the printed text into any QR code library. Arabic names also work, because length is counted in UTF-8 bytes. In Phase 2, the QR code gets more tags, such as the invoice hash and the digital signature.<\/p>\n\n\n\n
Step 5: Understand the stamp and the hash chain<\/h3>\n\n\n\n
Phase 2 adds two security ideas.<\/p>\n\n\n\n
\n- Cryptographic stamp<\/strong>: your system signs each invoice with a private key. Like a wax seal, it proves the invoice is yours and unchanged.<\/li>\n\n\n
- Hash chain<\/strong>: a hash is a short “fingerprint” of a file (ZATCA uses SHA-256). Each new invoice includes the hash of the previous invoice. If someone deletes or changes an old invoice, the chain breaks and it shows.<\/li>\n\n<\/ul>\n\n\n\n
For the exact hashing and signing steps, follow ZATCA’s technical documents and sample files.<\/p>\n\n\n\n
Step 6: Onboarding with a CSID<\/h3>\n\n\n\n
Your system must be registered first. The certificate ZATCA gives you is called a CSID<\/strong> (Cryptographic Stamp Identifier). The flow is:<\/p>\n\n\n\n\n- Create a private key and a certificate request (CSR) with your company details.<\/li>\n\n\n
- Get a one-time password (OTP) from the Fatoora portal.<\/li>\n\n\n
- Ask for a compliance CSID<\/strong> and send test invoices. ZATCA checks them.<\/li>\n\n\n
- When the tests pass, ask for a production CSID<\/strong> and start live work.<\/li>\n\n<\/ol>\n\n\n\n
Practice first in the sandbox<\/strong> on the developer portal. Nothing you send there counts as a real invoice.<\/p>\n\n\n\nCommon problems<\/h3>\n\n\n\n\n- The QR code does not scan in the official app.<\/strong> Check that each length is in bytes, and that the amounts have two decimals.<\/li>\n\n\n
- ZATCA rejects the invoice hash.<\/strong> The XML was changed after hashing, even by one space. Hash the final file.<\/li>\n\n\n
- The counter or chain breaks after a crash.<\/strong> Save the counter and last hash in your database, in the same step as the invoice.<\/li>\n\n<\/ul>\n\n\n\n
Wrap-up<\/h3>\n\n\n\n
Now the strange words have meaning: two phases, two invoice types, UBL XML, a QR code, a stamp, a chain, and a CSID. If the official site says something different from this post, trust the official site.<\/p>\n\n\n\n
Next idea: download the official sample invoices and SDK from the developer portal, and test your XML against them.<\/p>\n","protected":false},"excerpt":{"rendered":"
A simple map of Saudi e-invoicing rules for developers who build billing systems.<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[61,12,64,63,62],"class_list":["post-63","post","type-post","status-publish","format-standard","hentry","category-uncategorized","tag-e-invoicing","tag-python","tag-saudi","tag-xml","tag-zatca"],"_links":{"self":[{"href":"https:\/\/fsaeed.blog\/index.php\/wp-json\/wp\/v2\/posts\/63","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/fsaeed.blog\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/fsaeed.blog\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/fsaeed.blog\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/fsaeed.blog\/index.php\/wp-json\/wp\/v2\/comments?post=63"}],"version-history":[{"count":1,"href":"https:\/\/fsaeed.blog\/index.php\/wp-json\/wp\/v2\/posts\/63\/revisions"}],"predecessor-version":[{"id":70,"href":"https:\/\/fsaeed.blog\/index.php\/wp-json\/wp\/v2\/posts\/63\/revisions\/70"}],"wp:attachment":[{"href":"https:\/\/fsaeed.blog\/index.php\/wp-json\/wp\/v2\/media?parent=63"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/fsaeed.blog\/index.php\/wp-json\/wp\/v2\/categories?post=63"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/fsaeed.blog\/index.php\/wp-json\/wp\/v2\/tags?post=63"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}