UBL 2.1
UBL 2.1 is the XML standard ZATCA Phase 2 invoices are written in, validated with the XSD, the EN 16931 rules and ZATCA's own KSA rules.
UBL 2.1 (Universal Business Language) is an open OASIS XML standard for business documents. In Phase 2 an e-invoice must be XML in this standard, with Saudi additions such as ICV, PIH and the QR code.
An invoice passes three validation layers in ZATCA's SDK: the XSD schema (element names and order), the European EN 16931 rules (prefixed BR- and BR-CO-) and the Saudi rules (prefixed BR-KSA-). Matheel writes credit and debit notes on the same Invoice root, distinguished by InvoiceTypeCode.
Saudi specifics that surprise people coming from EN 16931: cbc:ProfileID must be reporting:1.0 (BR-KSA-EN16931-01), cbc:TaxCurrencyCode must be SAR (BR-KSA-EN16931-02), and there are two cac:TaxTotal elements, one with the per-category breakdown and one without (BR-KSA-EN16931-08 and 09). Arithmetic mistakes surface in the BR-CO rules, such as BR-CO-10 when the line amounts do not add up.
On Matheel you do not write XML: you send JSON, and Matheel builds the UBL and derives the totals from the lines so the BR-CO rules hold. The output passes all three layers of ZATCA's SDK.
Example
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2" ...>
<cbc:ProfileID>reporting:1.0</cbc:ProfileID>
<cbc:ID>SME00010</cbc:ID>
<cbc:UUID>8e6000cf-1a98-4174-b3e7-b5d5954bc10d</cbc:UUID>
<cbc:IssueDate>2022-08-17</cbc:IssueDate>
<cbc:IssueTime>17:41:08</cbc:IssueTime>
<cbc:InvoiceTypeCode name="0200000">388</cbc:InvoiceTypeCode>
<cbc:DocumentCurrencyCode>SAR</cbc:DocumentCurrencyCode>
<cbc:TaxCurrencyCode>SAR</cbc:TaxCurrencyCode>
FAQ
Can I submit a PDF instead of XML?
No. Submission to ZATCA is XML; PDF/A-3 with the XML embedded is a format for sharing with the buyer and archiving.
What is the difference between BR- and BR-KSA- rules?
BR- and BR-CO- come from the European EN 16931 standard; BR-KSA- are rules ZATCA added for Saudi Arabia.
Related ZATCA rules
Related terms
Let Matheel handle this for you
Matheel signs the invoice, files it with ZATCA and keeps the counter and hash in one request, and returns the PDF with the QR.
Try Matheel, no signup Matheel API docs