The Complete ZATCA End-to-End Process

Onboarding & ZATCA registration

Taxpayer onboarding, CSID request, and environment setup (sandbox → simulation → production) before any invoice is generated.

Extracting invoice data from the ERP

dsFatoora reads invoice data at the point of posting — from SAP, D365, Oracle, Sage, Odoo, or a legacy system — via API, OData, or staging tables.

Determining invoice type

Standard tax invoice vs. simplified invoice, and whether it's a credit or debit note, is resolved before any XML is generated.

Generating ZATCA-compliant XML

Source data is mapped into the ZATCA invoice schema.

Common pitfall: Decimal precision mismatches between the ERP's stored values and ZATCA's expected precision are one of the most common failure points here.

Applying UBL 2.1 structure

The XML is structured to the UBL 2.1 standard ZATCA requires, including all mandatory namespaces and extensions.

Performing ZATCA business validations

Rules covering VAT numbers, mandatory fields, totals, and tax breakdowns are checked before submission.

Common pitfall: Rounding differences on tax totals — especially across a large number of line items — are a frequent validation rejection.

Generating UUID

A unique invoice identifier is generated and embedded, distinct from the ERP's own invoice number.

Calculating invoice hash

A cryptographic hash of the invoice content is calculated for integrity verification.

Managing Previous Invoice Hash (PIH)

Each invoice's hash chains to the hash of the one before it, forming an auditable, tamper-evident sequence.

Common pitfall: Out-of-order submissions (common with retry queues) can break the PIH chain if sequencing isn't enforced at the middleware level.

Applying cryptographic stamping

The invoice is signed using the taxpayer's cryptographic certificate.

Managing certificates

CSID, CCSID and PCSID lifecycle — issuance, renewal before expiry, and secure storage — is handled centrally.

Generating QR code information

A QR code encoding the mandatory invoice fields is generated for both B2B and B2C formats.

Calling ZATCA APIs

The signed invoice is submitted to the appropriate Clearance or Reporting endpoint depending on invoice type.

Processing ZATCA responses

Responses are parsed into accepted, accepted-with-warnings, or rejected, each routed differently.

Common pitfall: Credit notes referencing an original invoice that itself had warnings can produce confusing downstream rejections if not tracked carefully.

Updating invoice status in the ERP

Clearance status, QR code, and any warnings are written back to the source ERP against the original transaction.

Handling failures

Failures are classified — data error, connectivity error, or authority-side error — and routed to the right remediation path.

Implementing retry mechanisms

Exponential backoff and a dead-letter queue prevent transient failures from becoming lost invoices.

Preventing duplicate submissions

Idempotency keys ensure a retried submission can never be cleared twice.

Maintaining audit logs

Every stage is logged immutably with timestamps, satisfying both internal audit and ZATCA's own record-keeping expectations.

Monitoring & reconciliation

A dashboard continuously matches ERP records against ZATCA's cleared records, surfacing any gap for resolution.

Common pitfall: At high line-item volumes — large consolidated invoices with hundreds of SKUs — reconciliation timing needs to account for ZATCA's own batch-processing windows.

Jump to a known issue

Decimal precision (Stage 4)
Rounding on large line-item sets (Stage 6)
PIH chain sequencing (Stage 9)
Credit note edge cases (Stage 14)
High-volume reconciliation timing (Stage 20)

Talk through your ZATCA edge cases

The complete ZATCA journey, stage by stage.