Skip to content
Xyncwave Corporation LLP

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

Finance professional in a Riyadh office at dusk watching digital invoices pass through a secure validation gateway.

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 typeModelPractical implication
Standard tax invoice (B2B)Clearance: submitted and cleared before sharing with the buyerInvoice issue becomes dependent on a successful API response
Simplified tax invoice (B2C)Reporting: submitted within the period ZATCA specifiesPOS and branch flows can continue while reporting happens asynchronously
Credit / debit notesFollow the original invoice typeMust 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

OptionStrengthWatch for
Community Frappe appFast start; designed for ERPNextMaintenance, version compatibility, test coverage
Commercial e-invoicing providerProvider manages spec changesContract, data residency, API reliability
Custom Frappe appFull control and fitYou 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

TestExpected result
Standard invoiceCleared; stamped XML and QR stored
Simplified invoiceReported within period
Credit noteLinked to original, accepted
Missing buyer VATBlocked before submission
API timeoutRetried safely without duplicate
Rejected invoiceVisible 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 Review

Define 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 questionEvidence to requestDecision consequence
Who controls deployment assets?Repository access, dependency inventory and deployment instructionsDecide whether internal engineers could maintain the implementation
What remains usable after termination?Export formats, access conditions and handover obligationsAssess switching effort before accepting dependency
How are specification changes funded?Defined maintenance scope and change approval processSeparate recurring ownership from initial delivery
What is excluded from the quote?Written assumptions covering environments and business variationsCompare 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.

Assign decision rights, not just task owners

An operational owner can resolve a queue without having authority to change invoice policy. Create a decision-rights matrix that separates execution, approval and consultation. The following allocation is a starting point to adapt, not a prescribed governance model. Each approval should identify the evidence reviewed and the scope of the decision.

DecisionResponsibleAccountableConsulted
Accept commercial scope and exclusionsProject managerBusiness sponsorFinance, procurement and engineering
Interpret invoice treatmentFinance process ownerFinance leadershipSaudi tax adviser
Approve technical changeIntegration engineerTechnical ownerSecurity and finance
Authorize customer-facing disruption responseOperations leadBusiness operations ownerFinance and customer service

Keep delegated authority visible when the usual approver is absent. An engineer should not invent a tax position to unblock delivery, and a salesperson should not instruct technical staff to bypass a control. Record disputed decisions with options, consequences and a named escalation route. The sponsor should resolve business tradeoffs while specialists retain responsibility for advice within their disciplines.

  • Require a decision log entry when an assumption changes the agreed scope.
  • Identify who may accept residual risk and who must be consulted first.
  • Define the evidence needed to close a decision so unresolved questions do not disappear into meeting notes.

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 choiceBenefitTradeoff to resolve
Central customer document serviceOne place to manage delivery evidenceAdditional component and ownership boundary
Delivery from each sales channelCloser fit to existing customer interactionsMore interfaces to govern consistently
Manual handling for exceptional customersAvoids automating rare variations immediatelyRequires 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.

RiskWarning evidenceBuyer response
Knowledge concentrated in one maintainerOnly one person can explain deployment or investigate incidentsRequire shared runbooks and a witnessed handover
Opaque proprietary dependencyDiagnostic exports or interface documentation unavailableNegotiate access or reconsider the dependency
Uncontrolled expansion of scopeNew sales variations appear without an ownerReturn each variation to the scope ledger
Business and technical responsibility confusedEngineers asked to approve invoice policyEscalate 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.

We use these details to respond to your enquiry. Please avoid confidential business data. Read our privacy policy.

Official sources and documentation