ZATCA Phase 2 E-Invoicing for ERPNext (Saudi Arabia)

Key Features

UBL 2.1 XML generation for both Standard (B2B) and Simplified (B2C) invoices, mapped from the ERPNext `Sales Invoice` DocType

Cryptographic invoice hash (SHA-256) with previous-invoice hash chaining and an incrementing ICV counter per device

XAdES digital signing with the device ECDSA private key, producing ZATCA-compliant signed XML

TLV-encoded, Base64 QR code (seller name, VAT number, timestamp, totals, hash, signature, public key) rendered on every invoice print format

Real-time clearance API call for B2B standard invoices — invoice marked valid only after ZATCA returns the counter-signed cleared XML

Reporting API submission for B2C simplified invoices, with queued/batch fallback via a Frappe scheduler event

Guided CSID onboarding — CSR generation, compliance CSID, and production CSID issuance exposed as whitelisted methods

Dedicated `ZATCA Device` and `ZATCA Invoice Log` DocTypes storing keys, payloads, hashes, QR and full request/response audit trail

Credit and debit note handling with correct billing-reference and instruction/reason codes back to the original invoice

`hooks.py` doc events (`on_submit`, `on_cancel`) drive generation and clearance without patching ERPNext core

Scheduler-based retry for pending/failed submissions so ZATCA outages or network blips never silently drop an invoice

Role profiles and permission rules restricting keys, logs and signing to Accounts/Compliance roles

Frappe REST API and whitelisted methods so POS, e-commerce or external systems can trigger clearance

Invoice retention and archival of signed XML and ZATCA responses for the statutory audit period

Multi-branch / multi-device support with per-device CSIDs and independent hash chains

Compatible with Frappe/ERPNext v15 and v16, packaged as a standalone app that survives `bench update`

Built to order, done for you

No DIY setup — a working app, built, installed and supported by ECOSIRE.

You order

Start with a one-time build price. We scope it with you at kickoff.

We build & install

ECOSIRE builds, configures and installs it on your ERPNext.

Go live + support

You go live in about 2–4 weeks, with a post-launch support window.

About this Product

Saudi VAT-registered businesses running ERPNext hit a wall the moment ZATCA's Integration Phase (Phase 2 / FATOORAH) applies to them. ERPNext core produces a compliant tax invoice and can print a basic Phase-1 QR code, but it does not generate the mandatory ZATCA UBL 2.1 XML, does not apply the cryptographic stamp and XAdES digital signature, does not manage the CSID onboarding lifecycle, and has no path to clear B2B standard invoices or report B2C simplified invoices to ZATCA's APIs in real time. Miss the clearance step and the invoice is legally invalid; get the XML hash chain or the signed QR wrong and ZATCA rejects it. Bolting this onto a live Sales Invoice workflow by hand is exactly where teams lose weeks and risk penalties.

ECOSIRE builds a proper Frappe app that installs cleanly on your bench alongside ERPNext, so nothing in core is patched and every future bench update stays safe. The app adds its own DocTypes — a per-branch/device ZATCA Device holding the CSR configuration, private key, compliance CSID and production CSID, and a ZATCA Invoice Log that stores the generated XML, the invoice hash, the previous-invoice hash for the chain, the signed QR TLV, the ZATCA request/response payloads, and the clearance or reporting status. Custom fields on Sales Invoice surface the ZATCA UUID, ICV counter, QR image and clearance status directly on the document, and a role profile keeps signing keys and logs visible only to Accounts and Compliance roles.

Technically, the flow is driven by hooks.py document events. On Sales Invoice on_submit, a server-side handler builds the UBL 2.1 XML from the invoice, computes the SHA-256 hash, chains it to the previous invoice's hash, canonicalizes and signs the document with the device private key (ECDSA), and generates the TLV-encoded, Base64 QR per the ZATCA spec. Standard (B2B) invoices are POSTed to the clearance API and only marked valid once ZATCA returns the cleared, counter-signed XML; simplified (B2C) invoices are reported and queued. A scheduler event retries any documents left in a pending state (network blips, ZATCA maintenance) so nothing is silently dropped, and credit/debit notes carry the correct reference and reason codes. Onboarding — CSR generation, compliance checks and production CSID issuance — is exposed as whitelisted methods callable from a guided setup screen, and the whole thing is reachable over the Frappe REST API for POS or external systems.

Because this is build-to-order, ECOSIRE builds the version scoped to your exact setup — your ERPNext/Frappe v15 or v16 bench, your branches and devices, your B2B/B2C mix, POS or not, and any print-format branding. After a short scoping call we confirm scope in writing, then build, test on a staging bench against the ZATCA sandbox, run UAT with your finance team, and cut over to production CSIDs. Typical delivery is 2–4 weeks from confirmed scope. You receive the full source, a git repository handover, documentation and training, and a post-go-live support window — no instant download, because a compliance integration this consequential should be built and verified for your environment, not shipped blind.

What you get

Installable source code for your scoped version of the ZATCA Phase 2 app, packaged as a standalone Frappe app

Installation and configuration on your bench (or handover instructions for your DevOps team), including custom fields, DocTypes and role profiles

CSID onboarding assistance: CSR generation, compliance checks against the ZATCA sandbox, and production CSID issuance

Technical documentation — architecture, DocType schemas, hooks, whitelisted methods and REST endpoints

User guide plus a live training session for your finance and compliance team

UAT on a staging bench against the ZATCA sandbox, with a documented rollback plan before production cutover

Post-go-live support window for defect fixes and ZATCA-rejection triage

Git repository handover with full commit history so your team owns and can extend the code

Who this is for

Finance / Compliance Manager (Saudi SME or enterprise)

Accountable for ZATCA compliance and audit-readiness. Needs every invoice cleared or reported correctly, a full audit trail of signed XML and ZATCA responses, and confidence that a rejection won't go unnoticed. Buys the certainty that invoices are legally valid, not a half-finished integration.

ERPNext System Administrator / Bench Owner

Runs the ERPNext v15/v16 bench and worries about upgrade safety. Wants a clean standalone app that doesn't patch core, survives `bench update`, uses proper DocTypes and `hooks.py` events, and hands over as a git repo the team can maintain.

CFO / Finance Director

Wants Phase-2 compliance handled before the ZATCA wave deadline without derailing the finance team. Values a fixed, scoped build with UAT and a rollback plan over an open-ended in-house project, and a support window that de-risks go-live.

ERP Implementation Partner / IT Lead

Delivering ERPNext to Saudi clients and needing a reliable ZATCA layer to slot in per engagement. Needs source ownership, clean architecture, REST/whitelisted-method access for POS integrations, and documentation they can support downstream.

How ZATCA Phase 2 E-Invoicing for ERPNext (Saudi Arabia) Compares

Criterion	ECOSIRE	Custom Build	Competitor	ERPNext Native
ZATCA Phase-2 clearance & reporting	Built-in for both B2B clearance and B2C reporting, validated on sandbox	Possible but you build the whole API integration yourself	Varies by app; often reporting-only or partial	Not supported — ERPNext core has no ZATCA API integration
UBL 2.1 XML + digital signing	Full UBL 2.1 generation, hash chaining and XAdES signing	Must implement canonicalization, hashing and signing from spec	Usually present but a black box you can't audit	Not generated by core
Fit to your setup	Scoped to your branches, devices, B2B/B2C mix and POS	Fully bespoke, but at full in-house build cost and time	Generic; you adapt your process to the app	Generic tax invoice only
Upgrade safety	Standalone app, no core patches, survives `bench update`	Depends on your team's discipline; core patches risk breakage	Depends on vendor's engineering quality	N/A — it is core
Source & ownership	Full source + git repo handover, you own and can extend it	You own it, but you also built and must maintain all of it	Typically closed-source or license-locked	Open source but no ZATCA layer to own
Delivery model	Build-to-order, 2–4 weeks from confirmed scope, with UAT	Open-ended internal project, months typical	Instant install, but integration/config still on you	Already installed, but non-compliant for Phase 2
Support & spec updates	Post-go-live window + optional maintenance for FATOORAH changes	Your team tracks and implements every ZATCA revision	Vendor-dependent; may lag or charge per update	No ZATCA support
Audit trail & retention	`ZATCA Invoice Log` stores XML, hashes, QR, responses for retention	You design the logging and retention scheme	Often minimal logging	No ZATCA-specific audit trail

Frequently Asked Questions about ZATCA Phase 2 E-Invoicing for ERPNext (Saudi Arabia)

How long does delivery take?

This is a build-to-order product, not an instant download. After a short scoping call and written sign-off on scope, typical delivery is 2–4 weeks. The exact timeline depends on your branch/device count, B2B vs B2C mix, POS integration and print-format branding — we confirm it in writing before we start building.

Do you patch ERPNext core?

No. We ship a standalone Frappe app that installs alongside ERPNext and uses custom fields, its own DocTypes, `hooks.py` document events and whitelisted methods. Nothing in core is modified, so your `bench update` and future ERPNext upgrades stay safe.

How do updates and support work after go-live?

Every build includes a post-go-live support window for defect fixes and ZATCA-rejection triage. Because ZATCA occasionally revises its FATOORAH specification, we offer optional ongoing maintenance to keep your XML, signing and API integration aligned with the current standard. You receive the full git repository, so your team can also maintain and extend the code independently.

Does it handle both B2B standard and B2C simplified invoices?

Yes. Standard (B2B) invoices go through the real-time clearance API and are only marked valid once ZATCA returns the counter-signed cleared XML. Simplified (B2C) invoices are reported to the reporting API, with a scheduler-based retry queue so nothing is dropped during outages. Credit and debit notes are handled with the correct reference and reason codes.

Which ERPNext and Frappe versions are supported?

We build for Frappe/ERPNext v15 and v16. Tell us your exact version and edition (self-hosted, Frappe Cloud, or Frappe Cloud Private Bench) during scoping and we target that environment specifically, including any constraints your hosting imposes on custom apps.

Can it integrate with our POS or external systems?

Yes. Clearance and reporting are reachable through the Frappe REST API and whitelisted methods, so ERPNext POS, e-commerce checkouts or external billing systems can trigger ZATCA processing. We scope the specific integration points with you up front.

How do you handle CSID onboarding and go-live safely?

We generate the CSR, run the compliance checks against the ZATCA sandbox to obtain the compliance CSID, then issue the production CSID. Everything is validated on a staging bench with UAT by your team and a documented rollback plan before we cut over to production — so go-live is controlled, not a leap of faith.