ZATCA XML Validation Errors: Why Fatoora Rejects Your Invoices and How to Fix Them

You post an invoice and the status comes back: Rejected, with a technical English message your accountant and cashier cannot make sense of. This happens in many businesses after they enter the integration phase, and every new wave brings more first-timers. This article explains how Fatoora validates an e-invoice XML, the difference between errors and warnings, the most common causes of rejection, and how to fix them without breaking your invoice chain.

How does ZATCA validate an invoice?

According to ZATCA’s Developer Portal Manual, an invoice file goes through several validation layers:

Error or warning? The difference matters

The manual distinguishes two outcomes: an error makes the document invalid and it is rejected; a warning means the document is accepted but not fully compliant. ZATCA’s Detailed Guidelines warn that warnings may become rejections in the future, so do not ignore them just because the invoice went through. Reporting and clearance responses come back as accepted, accepted with warnings, or rejected.

The most common causes of rejection, and the fixes

1. Missing or malformed seller or buyer data

VAT number, commercial registration and national address elements (building number, street, district, city, postal code). A standard tax invoice (B2B) needs the buyer’s full details, including VAT number and address. Fix: clean customer records and company data before integration, not after a rejection.

2. Totals that don’t reconcile

Line totals do not match the invoice total or VAT amount because of rounding or discounts. Fix: use one consistent calculation method in the system and never hand-edit amounts in the file.

3. Tax category or exemption reason

An exempt or zero-rated item without the right exemption reason code. Fix: set the tax type and exemption code once, at item or customer level.

4. Credit or debit note without a reference

A note must reference the original invoice. Fix: create returns from the original invoice, not as standalone documents.

5. A broken hash chain or counter

This happens when several devices issue invoices without coordination, an invoice is deleted, or a rejected invoice is regenerated with a new hash. The Detailed Guidelines note that a rejected document’s hash and counter value should not be changed. Fix: never delete, correct with the proper document, and let the system manage the sequence.

6. Signature or certificate problems

A file altered after signing, a certificate from a different environment (simulation vs production), or an expired certificate. Fix: check integration status and environment before sending, and renew certificates on time.

Why rejected invoices cannot be left alone

Under the clearance model, a standard tax invoice must be cleared by ZATCA before it is shared with the buyer, and simplified invoices must be reported within 24 hours of generation, per the E-Invoicing Implementation Resolution. ZATCA’s simplified violations guideline also has a separate item for failing to include all required data fields in invoices shared with ZATCA, starting with a warning and then fines on repetition.

ZATCA’s testing tools

Through the Developer Portal, ZATCA provides the Compliance and Enablement Toolbox: an offline SDK for validating files, a portal validator that accepts up to five XML files per run and checks the hash sequence between them, and an integration sandbox for testing onboarding, reporting and clearance. The manual stresses that passing SDK validation does not mean ZATCA has accepted the document; the platform’s response is the final word.

How RivDesktop handles validation

• Before onboarding: it validates seller data: VAT number (15 digits, starting and ending with 3), commercial registration, building number, street, district, city and a 5-digit postal code.
• During onboarding: it runs 6 compliance checks (invoice, credit note and debit note, for both simplified and standard), and the status indicator turns red if the selected environment does not match the actual certificate.
• Before sending: local validation of mandatory fields, such as buyer name, VAT number and national address on tax invoices, and the original invoice reference on notes.
• Automatic invoice type: a customer with a valid Saudi VAT number gets a standard tax invoice that goes through clearance; otherwise it is a simplified invoice sent for reporting. Returns become credit notes linked to the original.
• Sequence: ICV and PIH are maintained safely even with several cashier terminals.
• After the response: the integration report shows each invoice’s status and the rejection reason translated into plain language, with a validate-only option that does not send, resend selected or all pending, and a notification bell counting rejected and pending invoices.

Riv-ERP Cloud has a dedicated screen for invoices not yet uploaded or rejected by ZATCA. Details in the RivDesktop guide and the Riv-ERP Cloud guide.

Frequently Asked Questions