{ "source": "zip", "verdict": "FAIL", "rule_pack_version": "2.2.0", "reference_date": "2026-09-28", "zatca_sdk": "3.4.8", "run_id": null, "label": null, "coverage": { "checked_codes": 96, "total_codes": 242, "zatca_sdk": "3.4.8" }, "summary": { "entry_count": 5, "passed": 2, "failed": 2, "skipped": 1 }, "entries": [ { "position": 0, "name": "good-01-standard-388.xml", "verdict": "PASS", "document_identity": { "invoice_number": "MTB-G01", "issue_date": "2026-09-01", "invoice_type_code": "388", "invoice_type_name": "0100000", "seller_vat_number": "300000000000003", "icv": "1" }, "qr_consistent": null, "findings": [ { "rule_id": "MTB-BATCH-02", "zatca_codes": [], "severity": "WARNING", "xpath": "//*[local-name()='AdditionalDocumentReference']/*[local-name()='UUID']", "observed_value_class": "icv_repeated_in_archive", "explanation_key": "batch.counter.icv_repeated_in_archive", "explanation": { "en": { "title": "Invoice counter value is repeated inside this ZIP", "what_is_wrong": "Two or more members of the uploaded archive carry the same invoice counter value (KSA-16) under the same seller VAT registration number, and this note is on each of them. ZATCA's E-Invoicing Detailed Guideline (Annex 2 of the E-Invoicing Resolution) describes the counter as a tamper-resistant sequence that cannot be reset and increments for each invoice or note issued; the XML Implementation Standard itself requires only that the counter is present and written in digits. In Mutabiq's reading, the counter belongs to the e-invoicing solution that issues the documents, so two solutions of one seller can carry the same numbers, while one solution cannot repeat one. If these files come from different devices, this is expected. This is reported as a risk rather than as a rejection: ZATCA's published rules read one document at a time and check only that a counter is present, so no assertion sees the repeat. While a value is repeated, Mutabiq does not judge the previous invoice hash link into it or out of it, because there is no single document before or after it.", "what_to_check_in_your_erp": "If the files come from one device, the counter is not being advanced or is being reset: look for a counter kept per user session or per process rather than once for the device, a value reset by a restart, a reissue or a year end, a document exported twice into two files, and a copy of one file placed in the archive twice. If they come from different devices, nothing is wrong, and the clearest way to read the report is to upload each device's documents in an archive of its own." } } } ] }, { "position": 1, "name": "bad-31-tax-exclusive-mismatch.xml", "verdict": "FAIL", "document_identity": { "invoice_number": "MTB-G01", "issue_date": "2026-09-01", "invoice_type_code": "388", "invoice_type_name": "0100000", "seller_vat_number": "300000000000003", "icv": "1" }, "qr_consistent": null, "findings": [ { "rule_id": "MTB-BR-CO-13", "zatca_codes": [ "BR-CO-13" ], "severity": "WARNING", "xpath": "//*[local-name()='LegalMonetaryTotal']/*[local-name()='TaxExclusiveAmount']", "observed_value_class": "not_lines_plus_charges_less_allowances", "explanation_key": "br_co_13.not_lines_plus_charges_less_allowances", "explanation": { "en": { "title": "Tax-exclusive total does not match the lines, charges and allowances", "what_is_wrong": "The cbc:TaxExclusiveAmount in cac:LegalMonetaryTotal is not the line total plus the charge total less the allowance total. EN 16931 rule BR-CO-13, which ZATCA runs, checks whichever of those two optional totals your document carries, rounds the result to two decimals and requires an exact match. One case is stricter than the rest and catches people out: when the document has neither a charge total nor an allowance total, ZATCA requires the tax-exclusive amount to equal the line total with no rounding applied at all - so a line total written as 100.001 against a tax-exclusive amount of 100.00 fails, where in every other branch it would have been rounded first.", "what_to_check_in_your_erp": "Start by checking that the amounts entering this sum are the ones ZATCA expects: cbc:LineExtensionAmount for the lines, cbc:ChargeTotalAmount for document charges, cbc:AllowanceTotalAmount for document discounts. Then check the number of decimal places your system writes. If any amount carries three or more decimals, write it to two - the strict branch above compares those digits exactly, and a third decimal that rounds away in your reports does not round away here." } } }, { "rule_id": "MTB-BR-CO-15", "zatca_codes": [ "BR-CO-15" ], "severity": "ERROR", "xpath": "//*[local-name()='LegalMonetaryTotal']/*[local-name()='TaxInclusiveAmount']", "observed_value_class": "not_exclusive_plus_subtotals", "explanation_key": "br_co_15.not_exclusive_plus_subtotals", "explanation": { "en": { "title": "Tax-inclusive total does not equal the total before VAT plus the VAT", "what_is_wrong": "The cbc:TaxInclusiveAmount in cac:LegalMonetaryTotal is not the cbc:TaxExclusiveAmount plus the sum of the VAT breakdown amounts. EN 16931 rule BR-CO-15, which ZATCA runs, adds the tax-exclusive total to the cbc:TaxAmount of every cac:TaxSubtotal, rounds the result to two decimals and requires an exact match.", "what_to_check_in_your_erp": "The three figures usually come from different places, so check which one is out rather than adjusting the total to fit. A frequent cause is VAT computed per line and rounded there, while the breakdown is computed per category: ZATCA adds first and rounds once, so per-line rounding can differ by a hundredth or two. Another is a document-level discount applied after the VAT was computed. Note that this rule reads the VAT breakdown entries, so a document whose totals are right but whose breakdown is incomplete fails here too." } } }, { "rule_id": "MTB-BATCH-02", "zatca_codes": [], "severity": "WARNING", "xpath": "//*[local-name()='AdditionalDocumentReference']/*[local-name()='UUID']", "observed_value_class": "icv_repeated_in_archive", "explanation_key": "batch.counter.icv_repeated_in_archive", "explanation": { "en": { "title": "Invoice counter value is repeated inside this ZIP", "what_is_wrong": "Two or more members of the uploaded archive carry the same invoice counter value (KSA-16) under the same seller VAT registration number, and this note is on each of them. ZATCA's E-Invoicing Detailed Guideline (Annex 2 of the E-Invoicing Resolution) describes the counter as a tamper-resistant sequence that cannot be reset and increments for each invoice or note issued; the XML Implementation Standard itself requires only that the counter is present and written in digits. In Mutabiq's reading, the counter belongs to the e-invoicing solution that issues the documents, so two solutions of one seller can carry the same numbers, while one solution cannot repeat one. If these files come from different devices, this is expected. This is reported as a risk rather than as a rejection: ZATCA's published rules read one document at a time and check only that a counter is present, so no assertion sees the repeat. While a value is repeated, Mutabiq does not judge the previous invoice hash link into it or out of it, because there is no single document before or after it.", "what_to_check_in_your_erp": "If the files come from one device, the counter is not being advanced or is being reset: look for a counter kept per user session or per process rather than once for the device, a value reset by a restart, a reissue or a year end, a document exported twice into two files, and a copy of one file placed in the archive twice. If they come from different devices, nothing is wrong, and the clearest way to read the report is to upload each device's documents in an archive of its own." } } } ] }, { "position": 3, "name": "good-23-seller-address-incomplete.xml", "verdict": "PASS", "document_identity": { "invoice_number": "MTB-G01", "issue_date": "2026-09-01", "invoice_type_code": "388", "invoice_type_name": "0100000", "seller_vat_number": "300000000000003", "icv": "1" }, "qr_consistent": null, "findings": [ { "rule_id": "MTB-BR-KSA-09", "zatca_codes": [ "BR-KSA-09" ], "severity": "WARNING", "xpath": "//*[local-name()='AccountingSupplierParty']/*[local-name()='Party']/*[local-name()='PostalAddress']", "observed_value_class": "city_subdivision_missing", "explanation_key": "br_ksa_09.city_subdivision_missing", "explanation": { "en": { "title": "Seller address has no neighbourhood", "what_is_wrong": "The seller's postal address carries no cbc:CitySubdivisionName element, which ZATCA's message calls the Neighborhood (KSA-3). BR-KSA-09 asks for six fields on the seller's postal address, cac:AccountingSupplierParty/cac:Party/cac:PostalAddress: street name (BT-35, cbc:StreetName), building number (KSA-17, cbc:BuildingNumber), city (BT-37, cbc:CityName), postal code (BT-38, cbc:PostalZone), neighbourhood (KSA-3, cbc:CitySubdivisionName) and country code (BT-40, cac:Country/cbc:IdentificationCode). This is reported as a risk and not as a rejection. Under the SDK release the pack read before 2.0.0 (3.0.8), this was the one assertion ZATCA flagged as a warning rather than as an error; SDK 3.4.8, which the pack reads now, flags most of its assertions as warnings, and BR-KSA-09 stays among them: the platform records the shortfall and does not refuse the document for it, so this note does not turn the report to FAIL on its own. SDK 3.0.8 also asked for the additional number (KSA-23, cbc:PlotIdentification); SDK 3.4.8 does not (KSA:1216). The Data Dictionary marks the address subfields mandatory, and that does not change the flag the checker carries. The check is presence only - an empty element satisfies it - and it stops at the first field missing in ZATCA's own order (street name, building number, city, postal code, neighbourhood, country code), so more than one of the six may be absent and only the first is named here. It applies to standard and simplified invoices alike.", "what_to_check_in_your_erp": "The neighbourhood, or district, is part of the Saudi National Address and has no counterpart in the address formats most systems ship with, so it is either not captured at all or folded into the street line. Check the company or branch record for a district field; if there is none, adding a custom field and mapping it to cbc:CitySubdivisionName is the correct fix, and splitting it back out of the street text is not." } } }, { "rule_id": "MTB-BATCH-02", "zatca_codes": [], "severity": "WARNING", "xpath": "//*[local-name()='AdditionalDocumentReference']/*[local-name()='UUID']", "observed_value_class": "icv_repeated_in_archive", "explanation_key": "batch.counter.icv_repeated_in_archive", "explanation": { "en": { "title": "Invoice counter value is repeated inside this ZIP", "what_is_wrong": "Two or more members of the uploaded archive carry the same invoice counter value (KSA-16) under the same seller VAT registration number, and this note is on each of them. ZATCA's E-Invoicing Detailed Guideline (Annex 2 of the E-Invoicing Resolution) describes the counter as a tamper-resistant sequence that cannot be reset and increments for each invoice or note issued; the XML Implementation Standard itself requires only that the counter is present and written in digits. In Mutabiq's reading, the counter belongs to the e-invoicing solution that issues the documents, so two solutions of one seller can carry the same numbers, while one solution cannot repeat one. If these files come from different devices, this is expected. This is reported as a risk rather than as a rejection: ZATCA's published rules read one document at a time and check only that a counter is present, so no assertion sees the repeat. While a value is repeated, Mutabiq does not judge the previous invoice hash link into it or out of it, because there is no single document before or after it.", "what_to_check_in_your_erp": "If the files come from one device, the counter is not being advanced or is being reset: look for a counter kept per user session or per process rather than once for the device, a value reset by a restart, a reissue or a year end, a document exported twice into two files, and a copy of one file placed in the archive twice. If they come from different devices, nothing is wrong, and the clearest way to read the report is to upload each device's documents in an archive of its own." } } } ] }, { "position": 4, "name": "bad-04-vat-number-14-digits.xml", "verdict": "FAIL", "document_identity": { "invoice_number": "MTB-G01", "issue_date": "2026-09-01", "invoice_type_code": "388", "invoice_type_name": "0100000", "seller_vat_number": "30000000000003", "icv": "1" }, "qr_consistent": null, "findings": [ { "rule_id": "MTB-BR-KSA-40", "zatca_codes": [ "BR-KSA-40" ], "severity": "ERROR", "xpath": "//*[local-name()='AccountingSupplierParty']//*[local-name()='PartyTaxScheme']/*[local-name()='CompanyID']", "observed_value_class": "not_15_digits", "explanation_key": "br_ksa_40.not_15_digits", "explanation": { "en": { "title": "Seller VAT registration number is not 15 digits", "what_is_wrong": "The seller VAT registration number (BT-31), in cbc:CompanyID under the seller's VAT tax scheme, is not exactly 15 digits. ZATCA rejects it under BR-KSA-40, which requires 15 digits and nothing else - too few, too many, or any character that is not a digit all fail the same test.", "what_to_check_in_your_erp": "Send the 15 digits alone: no spaces, no dashes, no VAT or SA prefix, and no group separators. The common causes are a number stored with formatting for display and exported as stored, a value padded or truncated to a fixed column width, and the commercial registration number being mapped into this field by mistake - it is a different number and usually 10 digits. Correct it in the company record or the mapping, not in the exported file." } } } ] } ], "upload": { "file_names": [ "mutabiq-sample-batch.zip" ] } }