Insights · Saudi Arabia · E-Invoicing
ERPNext & ZATCA Phase 2: FATOORA Integration Readiness, Testing and Rollout
ZATCA Phase 2 is not a checkbox in an ERP. It is an integration programme touching master data, invoice states, credentials and operational error handling. This guide sets out how to prepare an ERPNext deployment—without assuming a certified connector or a single national deadline.
Written by: Haziq Hasan — Application Modernization Engineer

Short answer
To prepare ERPNext for ZATCA Phase 2, confirm your wave notification and integration date, clean the master data invoices depend on, choose an integration path (community app, provider or custom Frappe app), onboard each invoicing unit to obtain a CSID, test clearance and reporting in ZATCA's sandbox, and define how rejected invoices are corrected. A Saudi tax adviser should validate the final design.
Key takeaways
- Phase 2 rolls out in waves; your date comes from your own ZATCA notification.
- Standard (B2B) invoices need clearance; simplified (B2C) invoices are reported.
- Most effort sits in master data, invoice-state design and error handling.
- Treat credentials and cryptographic material as production secrets.
- Plan observability: you must know which invoices were rejected and why.
How wave notices work
ZATCA moves taxpayers into the integration phase in waves defined by revenue thresholds in a reference year. ZATCA notifies taxpayers in scope ahead of their integration date. For example, the Wave 25 announcement published on 24 July 2026 sets 1 February 2027 for the group it describes. Always confirm the current wave list on ZATCA's site—this guide does not determine your obligation.
Clearance vs reporting
| Invoice type | Model | Practical implication |
|---|---|---|
| Standard tax invoice (B2B) | Clearance: submitted and cleared before sharing with the buyer | Invoice issue becomes dependent on a successful API response |
| Simplified tax invoice (B2C) | Reporting: submitted within the period ZATCA specifies | POS and branch flows can continue while reporting happens asynchronously |
| Credit / debit notes | Follow the original invoice type | Must reference the original invoice |
Technical details—UBL 2.1 XML, invoice hash chaining, QR code content and cryptographic stamping—must follow the current ZATCA specifications and SDK, which change over time.
Master data and invoice-state model
- Seller VAT registration, CR number and address per company and branch.
- Buyer VAT numbers and structured addresses for B2B customers.
- Item tax categories and exemption reasons.
- A clear state model: draft → submitted → cleared/reported → rejected → corrected.
ERPNext's sales invoice is the natural source document, but the state of each submission should be stored explicitly so finance can see which invoices are legally issued.
Integration architecture options
| Option | Strength | Watch for |
|---|---|---|
| Community Frappe app | Fast start; designed for ERPNext | Maintenance, version compatibility, test coverage |
| Commercial e-invoicing provider | Provider manages spec changes | Contract, data residency, API reliability |
| Custom Frappe app | Full control and fit | You own spec changes and testing |
Whichever path you choose, keep it in a separate app or service—never in ERPNext core—so upgrades remain possible. The architecture descriptions here are illustrative, not a description of a delivered XWC ZATCA project.
Security and credentials
Private keys, CSIDs and API secrets must be stored outside the codebase, access-controlled and rotated according to ZATCA's renewal rules.
Sandbox, simulation and production validation
| Test | Expected result |
|---|---|
| Standard invoice | Cleared; stamped XML and QR stored |
| Simplified invoice | Reported within period |
| Credit note | Linked to original, accepted |
| Missing buyer VAT | Blocked before submission |
| API timeout | Retried safely without duplicate |
| Rejected invoice | Visible to finance with reason |
Error handling, retries and observability
- Idempotent submission so a retry never creates a duplicate.
- A queue of failed submissions with owner and reason.
- Alerts when rejection rates rise.
- Daily reconciliation between ERPNext invoices and ZATCA status.
Go-live checklist and specialist roles
- Wave date confirmed.
- All invoicing units onboarded with production CSIDs.
- Master data validated.
- Test matrix passed in simulation.
- Error queue owner named.
- Tax adviser sign-off obtained.
Regional context: ERPNext for GCC · Arabic ERPNext page · System Integration.
Discuss a ZATCA Integration Readiness ReviewDefine the investment boundary before procurement
Separate the business decision to change ERP from the technical decision to connect invoicing. A company satisfied with its operational processes may need a narrowly bounded integration, while another may need broader ERPNext implementation work. Combining both without explicit boundaries makes it difficult to distinguish regulatory dependencies from optional process improvements. Ask bidders to identify assumptions, exclusions and dependencies rather than promising a single undifferentiated compliance outcome.
Questions for the investment sponsor
- Which sales channels and customer commitments would be affected by changes to invoice delivery? Identify downstream dependencies such as dispatch approval, customer portals and collections before accepting a scope.
- Which existing systems remain authoritative? Name the system responsible for commercial terms, invoice creation and customer communication so integration work does not quietly become a replacement programme.
- Which decisions require specialist advice rather than software configuration? Record those dependencies separately and avoid treating engineering acceptance as a substitute for tax interpretation.
Use the ERPNext implementation discussion to separate platform changes from integration deliverables. Xyncwave is an implementation and engineering firm; ERPNext is third-party Frappe software. Evaluate the proposed engineering scope on its own evidence rather than inferring approval of the software or connector.
Compare proposals through evidence and exit rights
A connector demonstration establishes little about the buyer's ability to operate or replace it. Request evidence tied to your proposed deployment and have procurement distinguish software access, implementation work and continuing maintenance. Where a supplier cannot provide evidence before selection, make the missing item an explicit condition rather than an assumed capability.
| Procurement question | Evidence to request | Decision consequence |
|---|---|---|
| Who controls deployment assets? | Repository access, dependency inventory and deployment instructions | Decide whether internal engineers could maintain the implementation |
| What remains usable after termination? | Export formats, access conditions and handover obligations | Assess switching effort before accepting dependency |
| How are specification changes funded? | Defined maintenance scope and change approval process | Separate recurring ownership from initial delivery |
| What is excluded from the quote? | Written assumptions covering environments and business variations | Compare equivalent scope rather than headline price |
Ask for a walkthrough in which your team retrieves an example submission record and its supporting artefacts without supplier intervention. This is an evaluation exercise, not a claim that any particular connector offers that capability. If proprietary components are proposed, agree which diagnostic information and export tools remain available when the commercial relationship changes.
Design the customer delivery contract
The boundary between invoice processing and customer communication deserves its own business decision. Buyers may receive documents through email, portals or procurement systems, and those channels may expect particular references or attachments. Inventory those expectations without assuming that a successful integration response completes the customer journey. Separate the authoritative invoice artefact from convenience copies and explanatory messages.
| Delivery choice | Benefit | Tradeoff to resolve |
|---|---|---|
| Central customer document service | One place to manage delivery evidence | Additional component and ownership boundary |
| Delivery from each sales channel | Closer fit to existing customer interactions | More interfaces to govern consistently |
| Manual handling for exceptional customers | Avoids automating rare variations immediately | Requires controlled work instructions and cover |
Have customer service and finance agree how staff explain a pending document without implying that an unapproved copy is final. Define how customer reference changes are requested and assessed after processing has begun. The objective is not another submission-state model; it is a clear promise about what the buyer receives, where questions go and who authorizes communication when the normal journey is interrupted.
- List customer portals and document recipients that need separate acceptance evidence.
- Identify commercial dependencies, such as a delivery release awaiting an invoice reference.
- Agree a controlled communication template for unresolved cases, reviewed by the appropriate business owner.
Use a scope ledger to control integration economics
Budget discussions should expose units of work rather than rely on a single connector price. Business variations can create separate analysis, configuration and acceptance effort even when they share software. Build a scope ledger in which each variation has a business rationale, an owner and a decision to include, defer or remove it. Do not infer savings without comparing the actual proposed work.
- Separate reusable integration work from channel-specific adaptation and customer-specific delivery requirements.
- Distinguish work needed for the initial boundary from optional automation that can follow once the operating model is understood.
- Record external dependencies whose access, approvals or commercial terms could change the engineering estimate.
- Ask who funds investigation when a production issue crosses ERP, connector and provider boundaries; avoid unowned diagnostic work.
Compare proposals using the same scope ledger. A lower initial quote may exclude maintenance, operational tooling or transition assistance, while a broader quote may contain work the buyer does not need. Require suppliers to explain these differences in plain language. Keep unresolved quantities as assumptions to validate during discovery, not as invented precision in a purchasing spreadsheet.
Define the commercial boundary for future releases
Initial delivery and future change are separate purchasing decisions. Ask how a proposed release is assessed for business impact before it reaches the production environment. The buyer needs a way to distinguish an urgent corrective change from an optional improvement, and to understand whether either changes the agreed scope of service.
- Require a plain-language change note identifying affected business journeys, dependencies and any operator action. Technical release notes alone may not explain the consequence for finance or customer service.
- Identify who can authorize release-related expenditure and who can reject optional changes. Do not let an automatically renewed maintenance arrangement obscure the ownership of business decisions.
- Agree how deferred changes are recorded, including the reason for deferral and the person responsible for revisiting the decision. Avoid an informal backlog that nobody is empowered to prioritize.
Request a sample change proposal during procurement. Review whether it explains alternatives, implementation assumptions and the consequences of doing nothing. This gives the sponsor a practical way to assess future supplier communication without claiming that a particular release process guarantees compliance or uninterrupted operation.
Assess concentration and continuity risks
Beyond individual transaction failures, consider whether the operating model depends on assets or knowledge the buyer cannot access. Use a risk register with an owner, an observable warning and a response that can actually be authorized. Review residual exposure with the business sponsor instead of treating a documented risk as automatically accepted.
| Risk | Warning evidence | Buyer response |
|---|---|---|
| Knowledge concentrated in one maintainer | Only one person can explain deployment or investigate incidents | Require shared runbooks and a witnessed handover |
| Opaque proprietary dependency | Diagnostic exports or interface documentation unavailable | Negotiate access or reconsider the dependency |
| Uncontrolled expansion of scope | New sales variations appear without an owner | Return each variation to the scope ledger |
| Business and technical responsibility confused | Engineers asked to approve invoice policy | Escalate through the decision-rights matrix |
Before committing, prepare a short decision pack containing the scope ledger, proposal comparison, unresolved specialist questions and dependency register. Use contact to discuss a bounded engineering review. The useful outcome is a defensible implementation decision, including reasons to defer work, rather than a generic assurance that every compliance or operational risk has been removed.
Frequently asked questions
Does ERPNext support ZATCA Phase 2 out of the box?+
Not in core as a guaranteed compliant feature. Community apps, providers or custom apps are used; each must be validated.
Is XWC ZATCA accredited?+
No. We design, build and test the integration; compliance validation stays with your tax adviser.
What happens if the FATOORA API is unavailable?+
Standard invoices cannot be cleared until it responds; your process needs a defined fallback and retry approach per ZATCA rules.
Do we need one CSID per branch?+
Each invoicing unit/solution must be onboarded; how you define units depends on your setup and ZATCA rules.
Can we test before our wave date?+
Yes, ZATCA provides sandbox and simulation environments.
Start the conversation
Discuss a ZATCA Integration Readiness Review
Share your wave status, entities and current invoicing setup. We will discuss the technical path.
