FatooraLite Pro — ZATCA Phase-2 Technical & Regulatory Integration Guide

[!NOTE]
Regulatory Purpose: This guide serves as the definitive technical and cryptographic reference for implementing Saudi Arabia ZATCA (Zakat, Tax and Customs Authority) Phase-2 E-Invoicing (Integration Phase) compliance. It covers OASIS UBL 2.1 XML specifications, ECDSA secp256k1 key structures, XAdES-BES digital signatures, Tag-Length-Value (TLV) QR codes, and ZATCA REST API gateway integration.

1. Regulatory Context & Phase-2 Requirements

Under the KSA E-Invoicing Regulations, Phase 2 (Integration Phase) mandates that taxpayers connect their Electronic Invoice Generation Solutions (EIGS) directly to ZATCA's central platform (Fatoora Portal).

flowchart LR
    A["E-Invoice Generation Solution (EIGS)"] -->|1. Generate UBL 2.1 XML| B["Cryptographic Signing Engine"]
    B -->|2. Compute ECDSA Signature & TLV QR| C{"Invoice Type?"}
    C -->|Standard B2B| D["ZATCA Real-Time Clearance API"]
    C -->|Simplified B2C| E["ZATCA 24-Hour Reporting API"]
    D -->|3. Approved Clearance Stamp| F["Client Delivery (Cleared XML + PDF/A-3)"]
    E -->|3. Reporting Confirmation| G["Client Delivery (Printed Receipt / PDF)"]

1.1 Summary of Technical Standards

2. UBL 2.1 XML Invoice Structure

All invoices generated by FatooraLite Pro follow the OASIS UBL 2.1 standard with mandatory KSA custom profile identifiers.

2.1 Invoice Header Elements

<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
         xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
         xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2"
         xmlns:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2">

    <!-- ZATCA Profile & Transaction Identifiers -->
    <cbc:ProfileID>reporting:1.0</cbc:ProfileID>
    <cbc:ID>INV-2026-00892</cbc:ID>
    <cbc:UUID>c38f12a9-6e4b-4b21-8910-47120aef7831</cbc:UUID>
    <cbc:IssueDate>2026-07-21</cbc:IssueDate>
    <cbc:IssueTime>11:30:00</cbc:IssueTime>

    <!-- Invoice Subtype Classification Code -->
    <!-- Bitmask: 0100000 = Standard (B2B), 0200000 = Simplified (B2C) -->
    <cbc:InvoiceTypeCode name="0100000">388</cbc:InvoiceTypeCode>
    <cbc:DocumentCurrencyCode>SAR</cbc:DocumentCurrencyCode>
    <cbc:TaxCurrencyCode>SAR</cbc:TaxCurrencyCode>

2.2 Accounting Supplier & Customer Party Elements

    <!-- Accounting Supplier Party (Seller Details) -->
    <cac:AccountingSupplierParty>
        <cac:Party>
            <cac:PartyIdentification>
                <cbc:ID schemeID="CRN">1010123456</cbc:ID>
            </cac:PartyIdentification>
            <cac:PostalAddress>
                <cbc:StreetName>King Fahd Road</cbc:StreetName>
                <cbc:BuildingNumber>8229</cbc:BuildingNumber>
                <cbc:PlotIdentification>4321</cbc:PlotIdentification>
                <cbc:CitySubdivisionName>Al Olaya</cbc:CitySubdivisionName>
                <cbc:CityName>Riyadh</cbc:CityName>
                <cbc:PostalZone>12643</cbc:PostalZone>
                <cac:Country><cbc:IdentificationCode>SA</cbc:IdentificationCode></cac:Country>
            </cac:PostalAddress>
            <cac:PartyTaxScheme>
                <cbc:CompanyID>310123456700003</cbc:CompanyID>
                <cac:TaxScheme><cbc:ID>VAT</cbc:ID></cac:TaxScheme>
            </cac:PartyTaxScheme>
            <cac:PartyLegalEntity>
                <cbc:RegistrationName>FatooraLite Enterprise Solutions LLC</cbc:RegistrationName>
            </cac:PartyLegalEntity>
        </cac:Party>
    </cac:AccountingSupplierParty>

3. Cryptographic Stamp & XAdES Signature Engine

Every e-invoice must contain an embedded digital signature constructed using the tenant's ZATCA-issued X.509 Certificate and ECDSA private key.

Raw UBL 2.1 XML
    │
    ├──► 1. Strip Existing Extension & QR Nodes
    ├──► 2. Canonicalize XML Structure (C14N-11)
    ├──► 3. Compute SHA-256 Digest
    ├──► 4. Sign Digest with ECDSA secp256k1 Key
    │
    └──► Inject <ext:UBLExtensions> with XAdES Signature & Certificate Base64

3.1 X.509 Certificate Signing Request (CSR) ASN.1 Specifications

When requesting a Cryptographic Stamp Identifier (CSID) from ZATCA, the generated CSR must contain explicit X.509 Subject Alt Names (SAN) and custom OIDs:

4. Tag-Length-Value (TLV) QR Code Specifications

ZATCA mandates a 9-Tag Tag-Length-Value (TLV) binary structure for invoice QR codes.

TLV Byte Layout
[Tag 1 Byte] [Length 1 Byte] [Value Bytes...] ──► Concatenate 9 Tags ──► Base64 Encode

4.1 TLV Tag Definition Table

5. ZATCA REST API Gateway Integration

FatooraLite Pro communicates directly with ZATCA's API infrastructure using mutual TLS / Basic Authentication headers containing the Base64-encoded Binary Security Token (CSID).

sequenceDiagram
    participant App as FatooraLite Service
    participant Gateway as ZATCA Portal Gateway API

    Note over App, Gateway: Phase A: Compliance Onboarding
    App->>Gateway: POST /compliance (CSR + OTP)
    Gateway-->>App: Return Compliance CSID (CCSID) + Secret
    App->>Gateway: POST /compliance/invoices (Submit Sample Invoices)
    Gateway-->>App: Return Compliance Validation Passed (7/7)
    App->>Gateway: POST /production/csid (Request Production Token)
    Gateway-->>App: Return Production CSID (PCSID) + Secret

    Note over App, Gateway: Phase B: Production Operation
    App->>Gateway: POST /invoices/clearance (B2B Real-time XML)
    Gateway-->>App: Return Cleared Status + ZATCA Clearance Stamp
    App->>Gateway: POST /invoices/reporting (B2C 24-hr Batch)
    Gateway-->>App: Return Reporting Acknowledged

5.1 API Endpoint Matrix

6. Error Remediation & Troubleshooting Matrix

7. Compliance Verification & Test Harness

FatooraLite Pro includes an independent, automated verification suite for ZATCA XMLDSig validation:

# Execute independent non-circular ZATCA validation harness
npx tsx scripts/validate-zatca.ts

Verification Output Checklist:

• [PASS] Keypair Generation (ECDSA secp256k1)
• [PASS] X.509 CSR Construction & OID Encoding
• [PASS] UBL 2.1 XML Invoice Generation
• [PASS] C14N-11 Exclusive XML Canonicalization (Ancestors Preserved)
• [PASS] SHA-256 Digesting & Signature Insertion
• [PASS] 9-Tag TLV QR Code Encoding & Base64 Verification
• [PASS] Previous Invoice Hash (PIH) Chaining