Connecting Dynamics 365 to ZATCA Phase Two Portal: A Technical Deep Dive

Executive Summary

As Saudi Arabia's e-invoicing journey shifts from Phase 1 (the standalone "Generation" phase) to the strict integration mandate of Phase 2, enterprise architectures face a highly complex regulatory landscape. Standing still is not an option, companies matching ZATCA's phased revenue waves must connect their accounting and ERP platforms directly to the Fatoora portal in near real-time.

For large and mid-sized organizations running Microsoft Dynamics 365, securing a ZATCA compliant ERP in Saudi Arabia has shifted from a generic IT target to an absolute operational priority. Meeting compliance requires a deep technical understanding of data transformations, security frameworks, and real-time connectivity. This technical guide breaks down the core structural, cryptographic, and endpoint configurations required to align your Dynamics 365 environment with ZATCA Phase 2 standards.

Section 1: Structuring XML Invoices in UBL 2.1

Phase 2 mandates that all invoices be generated in a highly structured, machine-readable format specifically Universal Business Language (UBL) v2.1 XML schemas, embedded with custom KSA extensions. Unlike Phase 1, where simple PDF generation sufficed, your Dynamics 365 output must strictly map to a comprehensive KSA-tailored data dictionary.

The XML payload is verbose and heavily governed. Key namespaces must be declared, and critical fields must be populated atomically at the database level:

1. Unique Universal Identifier (UUID): A 128-bit cryptographically unique identifier generated using version 4 algorithms to prevent transaction duplication.

2. Invoice Counter Value (ICV): A sequential, non-gapped incremental counter assigned to each transaction processed by the individual Solution Unit (EGS).

3. Previous Invoice Hash (PIH): To prevent backdating or historical ledger tampering, the XML must contain the SHA-256 hash of the immediately preceding invoice. This creates an immutable, serial cryptographic chain of your company’s sales record. Mathematically, the current invoice hash H_n is linked to the previous transaction hash H_n-1 and the current invoice payload P_n via: H_n = SHA-256(P_n || H_n-1)

4. Standard Tax vs. Simplified Invoices: B2B invoices (UBL document type code 388) require standard tax configuration, whereas B2C invoices (document type code 383) must generate a 9-tag Base64-encoded TLV (Tag-Length-Value) QR code. The TLV string concatenates each element i with its tag T_i and byte length L_i: TLV = Σ_i=1..9 (T_i || L_i || V_i). This string is then converted into a Base64 format to render the QR code securely.

Section 2: Configuring Cryptographic Stamps and Signatures

Every transaction submitted to the Fatoora portal must carry a verified cryptographic stamp, validating that the document originates from an authorized solution unit and has not been altered post-signing. Configuring this authentication layer requires a strict multi-step cryptographic lifecycle:

1. CSR and CSID Exchange: Your Dynamics 365 environment generates a Certificate Signing Request (CSR) specifying your company's VAT registration number, device serial number, and specialized template extensions. Pushing this CSR to ZATCA's sandbox API returns a Compliance Cryptographic Stamp Identifier (Compliance CSID).

2. XML Canonicalization: Before a digital signature is applied, the raw XML invoice must undergo canonicalization (C14N) to standardize whitespace, namespace declarations, and attribute ordering.

3. Hashing and ECDSA Signing: The canonicalized payload is hashed using a secure SHA-256 algorithm. This hash is then signed using your private ECDSA (Elliptic Curve Digital Signature Algorithm) key. Cryptographically, ZATCA relies on the E_p(a, b) elliptic curve over a finite field specifically using the standard y² ≡ x³ + ax + b (mod p) curve parameter matching the secp256r1 (prime256v1) standard.

4. XAdES-BES Embedding: This digital signature, the ECDSA public key, and your Production CSID are embedded directly into the XML's UBL Extensions element as a standardized XML Advanced Electronic Signature (XAdES-BES) payload.

Section 3: Establishing Secure API Endpoints for Real-Time Exchange

The final compliance phase relies on routing your validated, cryptographically signed XMLs to the official ZATCA Fatoora API endpoints. This connection operates over secure, encrypted channels.

Your Dynamics 365 integration must support two distinct data transmission pipelines:

1. The B2B Clearance Model (Real-Time)

For standard B2B tax invoices, the API connection operates in a strict, synchronous gatekeeping sequence. The Dynamics 365 engine sends the signed XML to ZATCA’s /invoices/clearance/single endpoint. ZATCA validates the document in real-time, applies its official cryptographic stamp, and returns the cleared XML. Legally, the seller cannot issue the invoice to the customer until this cleared response is received and saved.

2. The B2C Reporting Model (Asynchronous 24-Hour Loop)

For simplified B2C invoices, your POS or mid-market system issues the invoice to the customer immediately. Dynamics 365 then packages and transmits these records asynchronously to the /invoices/reporting/single endpoint within 24 hours of generation.

Building, maintaining, and testing these pathways against sandbox and production endpoints requires a seasoned integration team. Choosing the right ZATCA Phase 2 integration partner Riyadh ensures your ERP connectivity handles retries, webhook responses, and potential offline fallbacks seamlessly.

Conclusion: Take Control of Your Compliance Roadmap

Navigating the technical details of ZATCA Phase 2 compliance requires specialized platform knowledge. From UBL 2.1 schema validation to ECDSA private key rotations and real-time clearance API connections, a generic accounting system simply cannot scale to meet these standards.

Dynamics Stream serves as a premier deployment partner for Middle Eastern enterprises, helping businesses secure their financial architecture, eliminate technical friction, and remain entirely compliant with tax regulations. Contact our enterprise architecture team in Riyadh or Dubai today to schedule an in-depth audit of your Dynamics 365 environment and secure your production pipelines before your assigned wave deadline.