Dynamics 365 Business Central: checking the ZATCA e-invoice XML

The file Mutabiq needs

Mutabiq checks the e-invoice itself: the UBL 2.1 XML generated for each invoice, credit note and debit note under Phase 2 of e-invoicing with the Zakat, Tax and Customs Authority (ZATCA), whether your system generates it or an e-invoicing add-on or integration connected to it does. A PDF with the invoice XML embedded in it (PDF/A-3) works as well. A PDF without that XML, a printout, a spreadsheet export or a screenshot carries nothing Mutabiq can check.

What Microsoft documents

• Microsoft’s availability table lists Saudi Arabia as localized by a partner on the international base app, not by Microsoft (Country/regional availability and supported languages).
• Microsoft documents electronic invoicing in Business Central as a general framework, with each country’s requirements delivered by a localization app (Electronic Invoicing FAQ). So the ZATCA XML comes from a partner’s app, and that app decides what is written into each element. Its mapping is not something this guide can see, so it names no screen or field: the checks below are on the XML, and they apply whichever app wrote it.

Where the file usually is

Where the XML is kept depends on how your system is connected to ZATCA, not only on which system it is, and this guide names a screen or menu only where the vendor's own documentation states it, cited and dated. The usual places to look:

• The e-invoicing or ZATCA section of your system, or of the add-on that handles e-invoicing for it, which may list each document with its status and let you view or download its XML.
• The portal of your e-invoicing solution provider, if a provider sends your documents to ZATCA for you: the XML is often kept there beside each document’s clearance or reporting result.
• An export or download of the document after it was cleared or reported, sometimes packaged with the PDF sent to the customer.
• Your provider or implementer. If none of these shows the file, ask for the UBL XML of the document exactly as it was generated for ZATCA.

Check the file as your system generated it. A copy opened and saved again in another program may no longer be the file ZATCA receives.

What to check in the exported XML

• cbc:InvoiceTypeCode: confirm the text is 388, 381 or 383, and that its name attribute is seven, eight or nine characters such as 0100000. MTB-BR-KSA-05 reports a type code ZATCA does not accept. An export that pads the attribute to a fixed width, or a format derived from PEPPOL that has no field for the transaction code at all, produces what MTB-STRUCT-01 reports.
• cac:AccountingSupplierParty//cac:PartyTaxScheme/cbc:CompanyID: confirm it is the 15-digit VAT registration number, beginning and ending in 3, with no country prefix or spaces. A VAT registration number held with a prefix for European reporting is written as held unless the export strips it; MTB-BR-KSA-40 reports the shape.
• The invoice counter and previous invoice hash are not PEPPOL elements, so confirm the export writes them at all: a cac:AdditionalDocumentReference with cbc:ID of ICV and a digits-only cbc:UUID, reported by MTB-BR-KSA-33, and one with cbc:ID of PIH holding cac:Attachment/cbc:EmbeddedDocumentBinaryObject with mimeCode="text/plain" and a non-empty base64 value, reported by MTB-BR-KSA-61.
• On a simplified invoice, confirm a third reference with cbc:ID of QR carries the base64 QR payload the same way; MTB-BR-KSA-27 reports it missing.
• Totals. Confirm the document-level cac:TaxTotal/cbc:TaxAmount equals the sum of the cac:TaxSubtotal/cbc:TaxAmount values under it, and that cbc:TaxInclusiveAmount equals cbc:TaxExclusiveAmount plus that VAT, with rounding applied once after the sum rather than per category; MTB-BR-CO-14 and MTB-BR-CO-15 report a difference.
• Decimals. Confirm each cac:InvoiceLine/cbc:LineExtensionAmount is written with at most two decimal places; a line net that is a quantity in a fractional unit times a price held at more places than it prints is what MTB-BR-DEC-23 reports.
• Confirm whether the same export serves credit memos: a 381 that comes out with the invoice’s transaction code, or without cac:BillingReference and cac:PaymentMeans/cbc:InstructionNote, is that reuse.
• Confirm which file you are checking: a file generated for a test service with a different format is not the file ZATCA received.

What to do with the findings

• Fix the source, not the file. Each finding names an element of the XML, and the value in it came from your system: a setting, a master record such as the company, the customer, the item or the tax code, or the mapping that writes the XML. Correct it there, so the next document is generated right.
• Do not edit the XML by hand and send the edited copy. The file that goes to ZATCA is the one your system generates and signs, and an edited copy is not that file.
• Where the mapping itself is wrong, take the finding to whoever maintains your e-invoicing: the ERP vendor, the add-on or integration provider, or your implementer. The rule id, the element’s path and the rule’s page are what they need to find it.
• A document that has already been cleared or reported is not corrected by sending it again. Ask your accountant or provider how your system corrects it; usually that is a credit or debit note and, where needed, a new document.
• Once the source is fixed, check the next file your system generates.

Sources

• Microsoft Learn: Country/regional availability and supported languages (Business Central)
• Microsoft Learn: Electronic Invoicing FAQ (Business Central)

These pages were read on 2026-09-11. Vendor documentation changes.