Introduction

Saudi Arabia's e-invoicing mandate (ZATCA Phase II) requires real-time clearance of all B2B invoices through the Fatoora platform before issuing them to buyers. After completing this integration across multiple ERPNext installations, we are sharing every technical lesson we learned.

What Is ZATCA Phase II?

ZATCA Phase II is the clearance stage of Saudi Arabia's e-invoicing regulation. Unlike Phase I (generation only), Phase II requires submitting each invoice to ZATCA's Fatoora portal and receiving a cleared stamp before the invoice can be shared with the buyer.

Technical Requirements Overview

• UBL 2.1 compliant XML with Saudi Arabia extensions
• Cryptographic signing using ECDSA (secp256k1)
• QR code generation (TLV encoded)
• Previous invoice hash chaining
• API integration with Fatoora (simulation → compliance → production)

Step 1 — Generate Your Cryptographic Key Pair

Generate an ECDSA key pair and create a Certificate Signing Request (CSR) using OpenSSL. Submit the CSR through the ZATCA Fatoora portal to obtain your Compliance CSID (CCSID).

openssl ecparam -name secp256k1 -genkey -noout -out private.pem
openssl req -new -key private.pem -out csr.pem

Step 2 — Build the UBL 2.1 XML Invoice

The invoice XML must follow the ZATCA UBL 2.1 profile with specific Saudi extensions. Key elements include the seller cryptographic stamp extension, the previous invoice hash, and the QR code data embedded in the XML.

Step 3 — Compute the Invoice Hash

Canonicalize the XML, compute its SHA-256 hash, then base64-encode the result. This hash is included in the next invoice (chaining) and in the API request payload.

Step 4 — Sign the Invoice

Sign the invoice hash using your ECDSA private key. The signature and your certificate are embedded in the XML as a UBL extension before submission.

Step 5 — Submit to Fatoora API

Construct the API payload with the base64-encoded invoice XML and hash, then POST to the Fatoora clearance endpoint. Handle the clearance response — ZATCA stamps the invoice and returns a cleared XML you attach to the buyer copy.

Common Pitfalls We Encountered

• Whitespace sensitivity: The XML canonicalization must be exact — extra spaces or newlines will invalidate the hash.
• Timezone issues: All timestamps must be in UTC with the exact ZATCA format.
• Certificate renewal: Production CSIDs expire. Build automated renewal into your system.

Conclusion

ZATCA Phase II is complex but achievable with a structured approach. At Methologik, we offer full ERPNext + ZATCA integration for businesses operating in Saudi Arabia. Contact us to discuss your requirements.