DocsArchitecture

ZATCA Compliance

A technical dive into how Prime Fatoora natively handles Phase 1 and Phase 2 ZATCA integration without external middleware.

Prime Fatoora was built natively around the Saudi ZATCA e-invoicing framework. Unlike legacy ERPs that require expensive third-party middleware to transform and sign invoices, we handle all cryptographic hashing, XML canonicalization, and API clearance natively inside our backend.

Phase 1 & Phase 2 Overview

Phase 1 (Generation): Prevents manual tampering and mandates a standard QR code on B2C invoices. We strictly enforce this by disabling manual deletion of issued invoices at the database layer.
Phase 2 (Integration): Requires a direct technical integration with the Fatoora Portal API to clear or report invoices in real-time.

The Phase 2 Workflow

Automated Onboarding

You generate a 6-digit OTP from the official Fatoora Portal.
We securely generate a local ECDSA secp256k1 private key and Certificate Signing Request (CSR).
We exchange the CSR for a Compliance CSID, perform mandatory ZATCA checks, and upgrade it to a Production CSID entirely in the background.

Cryptographic Hashing

Every invoice must mathematically link to the previous invoice to prevent historical tampering.
We take the SHA-256 hash of the previous XML document and embed it directly into the current UBL 2.1 XML document before signing (PIH Chaining).

Clearance & Reporting

B2B Invoices: Sent to the ZATCA Clearance API. We embed the returned cryptographic stamp onto your PDF.
B2C Invoices: Signed locally by our offline ECDSA keys, handed to the buyer instantly, and reported to ZATCA within 24 hours.

UBL 2.1 XML Example

Prime Fatoora constructs highly validated, EN16931-compliant UBL 2.1 XML documents directly. Before signing, the XML is canonicalized using the xml-c14n11 algorithm.

Embedded Signature Snippet (UBL 2.1)

<ext:UBLExtension>
  <ext:ExtensionURI>urn:oasis:names:specification:ubl:dsig:enveloped:xades</ext:ExtensionURI>
  <ext:ExtensionContent>
    <sig:UBLDocumentSignatures>
      <sac:SignatureInformation>
        <cbcv:ID>urn:oasis:names:specification:ubl:signature:1</cbcv:ID>
        <sbc:ReferencedSignatureID>urn:oasis:names:specification:ubl:signature:Invoice</sbc:ReferencedSignatureID>
        <ds:Signature Id="signature">
          <ds:SignedInfo>
            <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2006/12/xml-c14n11"/>
            <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256"/>
            <!-- XML Hashing and Base64 Signature Value -->
          </ds:SignedInfo>
        </ds:Signature>
      </sac:SignatureInformation>
    </sig:UBLDocumentSignatures>
  </ext:ExtensionContent>
</ext:UBLExtension>

Frequently Asked Questions

Do I need to hire a developer to integrate with ZATCA?

No! The Prime Fatoora backend is a native Phase 2 engine. All you have to do is paste the 6-digit OTP from the Fatoora Portal into your dashboard, and our servers handle the complex cryptography.

What happens if the ZATCA portal goes offline?

For B2B Standard invoices, you must wait for the portal to come back online to achieve Clearance. For B2C Simplified invoices, our background queue workers will automatically retry reporting the offline-signed invoices for up to 24 hours.