How to Integrate ZATCA E-Invoicing Into Your Existing ERP (Without Rebuilding)
You do not need to replace your ERP to become ZATCA Phase 2 compliant. This guide explains how to add a compliant e-invoicing integration layer on top of your existing system — architecture, data mapping, signing, clearance/reporting, and rollout.
The most common question from Saudi finance and IT teams is simple: do we have to throw away our ERP to satisfy ZATCA Phase 2? The answer is no. In the vast majority of cases, the fastest and safest route is to add a dedicated e-invoicing integration layer that sits between your existing system and ZATCA.
Your ERP, POS, or billing platform already knows how to create an invoice. What it usually cannot do is produce UBL 2.1 XML, apply a cryptographic stamp, onboard devices via CSR/CSID, and talk to the ZATCA clearance and reporting APIs. The integration layer handles exactly those jobs.
This guide covers the architecture, data mapping, signing, transmission, error handling, and rollout — with notes on how the approach applies to SAP, Odoo, Oracle, Microsoft Dynamics, NetSuite, and custom systems.
Who this applies to
SAP Shops (S/4HANA, ECC, Business One)
Large and mid-market enterprises needing a certified ZATCA bridge.
Odoo Users
Open-source ERP deployments requiring localization plus ZATCA APIs.
Oracle (EBS, Fusion, NetSuite)
Complex multi-entity setups with strict governance.
Microsoft Dynamics (365, AX, GP)
Businesses standardised on the Microsoft ERP stack.
Custom-built ERPs
In-house or bespoke platforms that need a compliance wrapper.
POS Chains & Retail
Multi-branch operations where each terminal must be onboarded.
Billing & Subscription Systems
Recurring invoicing platforms requiring automated reporting.
Clinics & Hospitals
Healthcare systems with insurance and self-pay billing flows.
Restaurants & F&B
POS-driven invoicing with delivery-platform reconciliation.
Car Workshops & Dealerships
DMS and workshop systems with parts and labour lines.
Wholesale & Distribution
High-volume B2B supply requiring clearance before delivery.
Manufacturing
Production ERPs with complex multi-line invoices.
Logistics & Freight
Per-shipment billing systems with automated reporting.
Real Estate & Property
Lease and service-charge systems with recurring invoices.
Professional Services
PSA and time-tracking tools that generate retainer invoices.
eCommerce Platforms
Shopify, Salla, Zid, and custom storefronts needing per-order invoices.
Government Contractors
Entities with governance-heavy approval workflows.
SME Startups
Fast-growing businesses on lightweight accounting or POS tools.
Why adding a layer beats rebuilding
Replacing an ERP is a 12-to-24-month journey that touches finance, operations, and every department that depends on the system. ZATCA compliance does not require it. An integration layer is a focused component that does one job extremely well.
It also insulates you from future regulatory change. When ZATCA updates rules, XML versions, or APIs, you update the layer — not your entire ERP.
- No migration risk to your core financial and operational data.
- Faster time to compliance — weeks, not years.
- Lower cost than a full ERP replacement or major module upgrade.
- Isolated from regulatory change: update the layer, not the ERP.
- Works with SAP, Odoo, Oracle, Dynamics, NetSuite, and custom systems.
Reference architecture
A compliant integration has six responsibilities: ingest, map, generate, sign, transmit, and archive. Separating these concerns keeps the system maintainable and auditable.
- Ingest: receive invoice events from the ERP, POS, or billing system via API, database trigger, or file drop.
- Map: translate internal fields into the ZATCA UBL 2.1 structure.
- Generate: build compliant UBL 2.1 XML and the human-readable PDF/A-3 with embedded XML.
- Sign: apply the cryptographic stamp using the device CSID certificate.
- Transmit: call the ZATCA clearance API (standard) or reporting API (simplified).
- Archive: store XML, PDF/A-3, QR codes, UUIDs, and ZATCA responses for audit.
Data mapping: the hard part
Integration succeeds or fails on data mapping. ERPs store data in their own structures; ZATCA expects a precise UBL 2.1 shape. The mapping layer must reconcile these, including edge cases like discounts, multiple VAT categories, and credit notes.
- Seller/buyer legal name, VAT number, and full structured address.
- Invoice type code (standard, simplified, credit note, debit note).
- Line items: description, quantity, unit price, discount, VAT rate, VAT amount.
- Tax categories: standard-rate (S), zero-rated (Z), exempt (E), out-of-scope (O).
- Totals: line extension, tax exclusive/inclusive, VAT total, payable amount.
- Currency and, where applicable, exchange rate.
- Issue timestamp with the correct timezone.
- References to original invoices for credit and debit notes.
Signing, QR codes and hash chaining
Each invoicing device must hold its own CSID certificate and sign invoices with the corresponding private key. Keys must live in a secure store — an HSM, secure element, or encrypted keystore — never in the ERP database in plain text.
The QR code must be TLV-encoded and Base64 encoded, and each invoice must carry a UUID, an invoice counter value (ICV), and the previous invoice hash (PIH) to form a valid chain.
- One CSID per device/branch/EGS — never share certificates.
- Store private keys in an HSM or equivalent secure store.
- Generate the QR in TLV format and verify it with a decoder in testing.
- Maintain a monotonic ICV and correct PIH for every invoice.
- Rotate certificates before expiry and have a rollover plan.
Clearance and reporting flows
The integration layer must route invoice types to the correct ZATCA flow. Standard tax invoices go through clearance before delivery; simplified invoices are issued immediately and reported within 24 hours.
Both flows need robust retry logic. A network interruption must never lose an invoice or break the hash chain.
- Clearance flow (standard/B2B): submit, wait for ZATCA validation, only then deliver.
- Reporting flow (simplified/B2C): issue first, report within 24 hours.
- Persist every response, including warnings, for audit.
- Queue outbound calls with retries and idempotency keys.
- Alert on rejection spikes so root causes are fixed immediately.
Platform notes: SAP, Odoo, Oracle, Dynamics, NetSuite
The layer approach is platform-agnostic, but each ERP has its own integration surface. Knowing which to use shortens the project.
- SAP: use standard billing document outputs, BAPIs, or middleware (SAP PI/PO, BTP) to emit invoice events.
- Odoo: leverage the localization modules, custom modules, and scheduled actions; connect via XML-RPC/JSON-RPC.
- Oracle: integrate via Fusion REST APIs, EBS interface tables, or NetSuite SuiteScript and RESTlets.
- Microsoft Dynamics: use Business Central/D365 APIs, Power Automate, or dual-write connectors.
- Custom systems: expose an invoice event API or a secure database trigger to feed the layer.
- All platforms: keep the layer decoupled so ERP upgrades do not break compliance.
Rollout plan and testing
Treat the rollout as a phased project with a sandbox phase that mirrors production. Most failures surface in testing, where they are cheap to fix.
- Phase 1: discovery — inventory all invoice sources and types.
- Phase 2: build mapping and XML generation; validate against ZATCA schema.
- Phase 3: sandbox onboarding (CSR/CSID) and compliance testing across all invoice types.
- Phase 4: pilot with one branch or entity, then production CSID.
- Phase 5: roll out to remaining branches; train staff.
- Phase 6: monitor, then optimise retries, alerts, and archives.
Frequently asked questions
Do I need to replace my ERP to comply with ZATCA?+
No. You can keep your existing ERP, POS, or billing system and add a ZATCA e-invoicing integration layer that generates UBL 2.1 XML, applies the cryptographic stamp, transmits to ZATCA, and archives results. This is faster and lower-risk than a full replacement.
What is a ZATCA integration layer?+
A ZATCA integration layer is a component that sits between your existing invoicing systems and ZATCA. It ingests invoices, maps them to UBL 2.1, signs them with the device CSID, calls the clearance or reporting API, and stores the results for audit.
Can you integrate ZATCA with SAP?+
Yes. SAP integration typically uses billing document outputs, BAPIs, or middleware such as SAP PI/PO or BTP to emit invoice events to the ZATCA layer. The layer then handles XML generation, signing, and API transmission.
Does Odoo support ZATCA e-invoicing?+
Odoo can be made ZATCA-compliant through localization modules combined with a ZATCA integration layer. The layer connects via Odoo’s APIs and scheduled actions to generate, sign, and transmit invoices to ZATCA.
How does ZATCA integration work with Oracle or NetSuite?+
Oracle Fusion, EBS, and NetSuite expose REST APIs, interface tables, SuiteScript, and RESTlets. The integration layer uses these to receive invoice events and return ZATCA UUIDs and QR data for storage and reprinting.
Can ZATCA integrate with Microsoft Dynamics?+
Yes. Dynamics 365 and Business Central offer APIs, Power Automate, and dual-write connectors that feed the ZATCA integration layer, which handles compliance and transmission.
How long does ERP ZATCA integration take?+
Most integrations take 6 to 12 weeks, covering discovery, data mapping, XML generation, sandbox testing, production CSID onboarding, and rollout. Complex multi-entity ERPs can take longer.
Do I need one integration per branch or device?+
The integration layer is centralised, but each invoicing device or EGS must be onboarded individually with its own CSID certificate. This is managed by the layer, which tracks certificates per device and branch.
Will ZATCA integration break my ERP during upgrades?+
A well-designed integration layer is decoupled from the ERP. It consumes invoice events through stable interfaces, so ERP upgrades and regulatory changes can be handled independently without affecting the core system.
What about POS and billing systems, not just ERP?+
The same approach applies. POS terminals, e-commerce platforms, and subscription billing systems can all feed the ZATCA integration layer, which handles UBL 2.1 generation, signing, clearance or reporting, and archiving on their behalf.
Topics covered
Related reading
Need help building this?
CODEXTERS designs and builds software across ERP and ERPNext, ZATCA e-invoicing compliance, AI and data platforms, SaaS products, and startup MVPs — for companies of every size.