SAP Business One: 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 SAP documents

• SAP documents the electronic documents of SAP Business One as XML produced by a general electronic-document framework, which some localizations customise for local legal requirements (Electronic Documents and Reporting).
• Its documentation for the Central MENA localization, which covers Saudi Arabia, carried no topic on ZATCA e-invoicing when it was read on 2026-09-11 (Localization for Central MENA). SAP Business One installations in the Kingdom typically produce the ZATCA XML through a partner add-on or integration, and each has its own way of building the XML and of mapping the system’s data onto its elements; some use SAP’s electronic-document framework and some do not. That 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 add-on 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 the name attribute is seven, eight or nine characters, such as 0100000. A mapping that pads the attribute to a fixed width, or writes the type code and the transaction code from separate lookups where one lookup returns blank, produces the values MTB-BR-KSA-05 and MTB-STRUCT-01 report.
• cac:AccountingSupplierParty//cac:PartyTaxScheme/cbc:CompanyID: confirm it is the 15-digit VAT registration number, beginning and ending in 3, with no spaces or prefix, and that it belongs to the company or branch that issued the document. MTB-BR-KSA-40 reports a number of another shape.
• The invoice counter: confirm a cac:AdditionalDocumentReference with cbc:ID of ICV exists and that its cbc:UUID is a plain integer and not the document number, a prefixed series or a GUID. MTB-BR-KSA-33 reports the block missing. The element name reads like a GUID field; a mapping written from the element name rather than from the field definition will put one there.
• The previous invoice hash: confirm the PIH reference carries cac:Attachment/cbc:EmbeddedDocumentBinaryObject with mimeCode="text/plain" and a non-empty base64 value, including on the first document of a chain. MTB-BR-KSA-61 reports the block or its payload missing.
• Simplified invoices. Cash and counter sales are usually simplified invoices, whose transaction code in the name attribute begins 02, so check one of those as well as a standard one. Confirm it carries a third reference with cbc:ID of QR holding the base64 QR payload in cac:Attachment/cbc:EmbeddedDocumentBinaryObject, which MTB-BR-KSA-27 reports missing, and a cac:Signature block, which MTB-BR-KSA-60 reports missing. A mapping built for standard invoices and reused for simplified ones is the usual reason neither is there.
• 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. The header total and the breakdown often come from different tables, and a difference of a halalah from rounding each category before the sum is what MTB-BR-CO-14 reports.
• Decimals. Confirm every VAT amount is written with at most two decimal places, including the cac:TaxTotal/cbc:TaxAmount inside each cac:InvoiceLine, which is the copy least likely to pass through the routine that formats the header totals. MTB-BR-DEC-13 reports a third decimal on a VAT amount in the document currency.
• Credit and debit notes. Confirm a 381 or 383 carries cac:BillingReference/cac:InvoiceDocumentReference/cbc:ID naming the original invoice; a note raised against a customer rather than against an invoice has nothing to write there, and MTB-BR-KSA-56 reports it.
• Confirm whether the mapping was built for one document type and reused for the others: a credit note that comes out with the invoice’s transaction code, or without its billing reference, is that reuse.

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

• SAP Help Portal, SAP Business One 10.0: Electronic Documents and Reporting
• SAP Help Portal, SAP Business One 10.0: Localization for Central MENA/AE/EG/LB/OM/QA/SA

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