ZATCA Phase 2 integration is not PDF uploading. A developer must generate compliant XML, onboard each invoicing solution unit, manage identifiers and security features, connect to FATOORA APIs, handle clearance or reporting responses, and retain audit evidence. Integration is introduced in waves; verify the business’s notice and the latest official ZATCA material before implementation.
The taxpayer remains responsible when a vendor supplies the software. Finance must approve transaction classification, and engineering must trace each event through XML, Authority response, and archive. “ZATCA ready” is not an acceptance test without representative files, validation results, state handling, and operating controls.
This article gives a general technical framework. Wave thresholds, deadlines, schemas, fields, and procedures can change. Use the business’s official notification and current authority documentation, and obtain tax advice for its activity.
Phase 1 and Phase 2 compared
The generation phase established electronic issuance and storage. The integration phase adds technical controls and connection to the FATOORA platform for taxpayers notified in the staged rollout. It does not replace Phase 1; it extends the invoicing process with structured data, security features, additional fields, and defined sharing routes.
Requirement | Phase 1: generation and storage | Phase 2: integration |
Electronic solution | Generate and retain invoices with a compliant system | Continue generation with onboarding and integration |
Format | Phase 1 fields and controls | Structured XML; PDF/A-3 with embedded XML may provide a readable copy |
Authority connection | No per-invoice FATOORA API integration | Connect to FATOORA using the prescribed route |
Security | Baseline anti-tampering controls | Identifiers, counters, hashing, and cryptographic features as specified |
Standard tax invoice | Generate and store | Submit for clearance before sharing through the applicable process |
Simplified tax invoice | Generate with required QR data and store | Apply required security and report within the official period |
Testing | Validate content and output | Validate schema, onboard, test APIs, and monitor responses |
Archive | Organized electronic retention | Retain XML, responses, status, and traceable business references |
ZATCA’s detailed guidance explains API integration, the required XML or PDF/A-3 with embedded XML format, and the differing clearance and reporting treatment. Always check the current technical specifications linked from the developer portal.
Classify the commercial event before coding
Engineering cannot infer tax treatment from a screen name. Finance or the tax adviser should approve a transaction matrix. Is the sale business-to-business or consumer-facing? Is the buyer VAT-registered? Does the event represent an advance, supply, cancellation, full refund, or partial refund? Is the platform the seller or an intermediary?
Map each business event to the correct invoice or note. Order creation is not necessarily the tax-invoice moment. Payment authorization is not always settlement. A refund should not delete the original fiscal record; it may require a linked credit or debit note according to the facts and current rules.
Create a data dictionary mapping commerce fields to invoice elements: seller, buyer, tax identifiers, currency, lines, quantity, price, discount, VAT category, totals, supply data, and order reference. Give every field a source of truth and correction owner. If checkout captures free text but the XML expects structured data or an approved code, fix the source model rather than patching the serializer.
What the development scope must contain
Do not bury integration in a generic “backend work” line. Make each outcome testable and assign ownership of accounts, credentials, approval, and production operations.
- Classify invoice and note types for every supported transaction.
- Build XML generation against the published data dictionary and implementation standard.
- Implement UUIDs, counters, hashes, stamps, and QR content where required.
- Onboard invoicing solution units through the current official process.
- Connect clearance and reporting endpoints and parse their responses.
- Handle timeouts, retries, idempotency, connectivity loss, and sequencing.
- Archive XML, responses, status, and business references for audit retrieval.
- Test valid and invalid invoices, notes, refunds, cancellation, and recovery.
ZATCA publishes the XML implementation standard and data dictionary and a developer compliance toolkit. Passing a local SDK check is useful evidence, but the authority explicitly notes that it is not itself approval of an invoice and does not remove the taxpayer’s responsibility.
Speak with the CloudTopia team on WhatsApp to review store readiness and request a Saudi-riyal scope covering XML, API states, testing, and handover.
Device onboarding, credentials, and secrets
Every electronic generating solution unit in scope needs onboarding through the prescribed FATOORA process. The workflow generally includes generating a certificate-signing request, using organization-controlled onboarding information, completing compliance steps, and obtaining the relevant production credentials. Follow portal documentation rather than copying a token flow from an old project.
Keep private keys, certificates, tokens, and passwords in a managed secret store, not source control or a visible database column. Limit access, log administrative use, and define renewal, replacement, and revocation procedures. Isolate simulation and production so a developer cannot send test data with live credentials.
Time and sequence are part of correctness. Signing, hashes, invoice counters, and previous-invoice links interact with retries, offline operation, branches, and concurrent checkout workers. Two nodes must not issue the same sequence state. Restore tests must prove that a backup recovers the latest valid state rather than reintroducing an old counter.
The taxpayer should own the portal identity and credentials. Vendor access should be scoped, monitored, and removable at handover. Record which solution unit and certificate produced each document.
Clearance and reporting are distinct workflows
Standard tax invoices and simplified tax invoices do not follow one generic “send invoice” path. Under the integration model, the standard tax-invoice workflow submits the invoice for clearance before it is shared with the buyer. The simplified workflow generates and secures the document and reports it within the period stated by the authority.
The software must interpret acceptance, warnings, rejection, authentication failure, throttling, and network failure. A rejected amount or XML rule needs data correction, not unlimited retries. A transient outage may justify a controlled retry, but that retry must not create a second fiscal record for the same commerce event.
Use an immutable internal transaction key and explicit states such as draft, ready, submitted, cleared or reported, rejected, and intervention required. Store the response code and attempt time while keeping secrets and unnecessary personal data out of logs. Give finance an exception queue; do not leave rejected invoices inside an engineering log nobody reviews.
Test the official contingency rules. The design should state what may be generated during disruption, what waits, and how queued documents resume without breaking sequence or duplication.
What integration changes in an online store
Order, payment, fulfilment, and invoice records should be distinct but strongly linked. The order represents goods and delivery. Payment represents authorization, capture, and refund. The invoice records the fiscal event. In a simple purchase they may happen seconds apart, yet they require different correction and retention behavior.
At minimum, test these cases:
- Test a successful order containing delivery and a line discount.
- Test payment failure followed by success without duplicate invoicing.
- Test full and partial refunds with the appropriate linked note.
- Test every tax category or treatment approved for the business.
- Test business-buyer and consumer-buyer data requirements.
- Test cancellation before and after fiscal issuance.
- Test external-platform downtime and controlled recovery.
- Test reconciliation across order, payment, invoice, and settlement totals.
The customer portal may display a readable representation, but the system should preserve the legal XML and authority result associated with issuance. Do not regenerate an old document from today’s mutable product, address, or tax configuration.
Design for integration before the wave arrives
A store that keeps only a final grand total is hard to make compliant. Invoice lines need quantities, unit prices, discounts, tax categories, and consistent totals. Refunds require a link to the source. Branches need defined generating units. Production accounts need organizational ownership.
CloudTopia builds commerce data models ready for FATOORA integration from the first release: orders, payments, and invoices are separated; Arabic RTL is native; and the client owns source code under contract. A fixed readiness review can be proposed from SAR 990 before implementation estimation, identifying data and workflow gaps without committing the business to a full build. The final scope confirms price and excludes third-party fees unless listed.
Readiness does not mean silently connecting a business before notification or without onboarding. It means the data and event model will not obstruct integration when required. Centralize schema mappings and configuration so an official update does not require manual edits across many unrelated modules.
Questions to ask a ZATCA integration developer
Ask for evidence with each answer: a de-identified sample, SDK result, state diagram, test register, secret-management design, and screenshot of the exception queue.
- Ask how the system distinguishes clearance, reporting, and document type.
- Ask which XML specification and data-dictionary version it implements.
- Ask how credentials are protected and environments are separated.
- Ask how retries preserve idempotency, counter, hash, and sequence.
- Ask how rejection and warnings reach finance for resolution.
- Ask how credit and debit notes reference their source document.
- Ask which records are retained and how an audit export is produced.
- Ask who owns the code, accounts, credentials, and documentation at handover.
Run representative tests in the actual product. A slide showing a green connector is not proof that refunds, branch concurrency, certificate renewal, or restoration work.
Penalties, responsibility, and operating evidence
Saudi rules provide for violations and penalties where e-invoicing duties are not met, records are generated or retained incorrectly, or prohibited tampering occurs. Do not copy a fixed amount from an old secondary article. The rule, violation type, facts, and authority procedure matter. Consult ZATCA’s official laws and VAT material and an appropriate adviser.
Build retrievable evidence: original XML, submission state, authority response, timestamp, commerce reference, later notes, and a controlled audit log. An issued document should not return to an editable draft. Corrections must use the process appropriate to the document and transaction.
Monitor rejected, warned, or stalled items every operating day and escalate them before the applicable limit. Reconcile samples between commerce, payments, invoices, and accounts. Test restore, credential replacement, and new-branch onboarding. Integration is an operating capability, not a one-time connector that can be forgotten after launch.
Contact CloudTopia on WhatsApp for a low-cost readiness review and documented integration plan, then confirm your wave and final obligations through ZATCA’s official channels.
Frequently asked questions
What is ZATCA Phase 2 e-invoicing?
Phase 2 integrates a taxpayer’s electronic invoicing solution with ZATCA’s FATOORA platform. It is introduced through notified waves and adds structured XML, specified fields, security features, and clearance or reporting workflows. Check the organization’s official notice and current ZATCA developer material because technical details and rollout criteria can change.
Does my online store have to integrate with FATOORA?
That depends on whether the legal entity is subject to e-invoicing and has entered a notified Phase 2 wave, not merely on having an online store. Check the VAT identity, official revenue criteria, relevant periods, and direct notice. Marketplaces and agency models may need transaction-specific tax advice.
What does a developer need for ZATCA integration?
The developer needs an approved transaction map, accurate source data, compliant XML generation, solution-unit onboarding, credentials, identifiers, security features, and clearance and reporting APIs. The implementation must also handle rejection, outages, retry idempotency, notes, archiving, monitoring, and tests using current ZATCA specifications and supported environments.
What is the penalty for not completing ZATCA integration?
Non-compliance can lead to action or fines under the applicable rules, depending on the violation and circumstances. Failures may involve issuance, retention, required content, integration, or tampering. Do not rely on an old fixed figure from a secondary source; check the authority’s current violation material and obtain advice for the business’s case.
Read also
Need a CRM, ERP, or dashboard built around your workflow?
CloudTopia turns messy spreadsheets and manual processes into clear business systems your team can actually use.
Share this article
Written by
Mohamad Shahm | محمد شـهم
Mohamad Shahm founded CloudTopia after a decade building web platforms, e-commerce systems, and bilingual (Arabic + English) experiences for Gulf businesses. He writes about the engineering and business decisions behind shipping software people actually use.
