> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gobl.org/llms.txt
> Use this file to discover all available pages before exploring further.
# Saudi Arabia ZATCA
Key: `sa-zatca-v1`
Module: [github.com/invopop/gobl.sa.zatca](https://github.com/invopop/gobl.sa.zatca)
Support for the Saudi Arabia ZATCA (Zakat, Tax and Customs Authority) e-invoicing
requirements based on UBL 2.1 with EN 16931 as an intermediate layer and KSA-specific
extensions (BR-KSA-\* rules).
ZATCA e-invoicing covers both standard tax invoices (B2B/B2G) sent for clearance
and simplified tax invoices (B2C) sent for reporting through the FATOORA platform.
This addon extends EN 16931 with Saudi-specific fields and validations including
invoice type transactions, address requirements, and supply date handling.
## Sources
* [ZATCA E-Invoicing Developer Portal](https://zatca.gov.sa/en/E-Invoicing/SystemsDevelopers/Pages/E-Invoice-specifications.aspx)
## Scenarios
### bill/invoice
**Filters:**
* **Types:** `standard`
**Output:**
* **Extensions:** `untdid-document-type:388`
## Extensions
### ZATCA Invoice Transaction Type
Code used to describe the ZATCA invoice transaction type and flags (KSA-2).
The code is a 7-character string where positions 1-2 indicate the main type
(01 = Standard Tax Invoice, 02 = Simplified Tax Invoice) and positions 3-7
are binary flags for third-party, nominal, export, summary, and self-billed
transactions respectively.
Pattern: `^0[12][01]{5}$`
| Code | Name |
| --------- | ----------------------------------------------------------------- |
| `0100000` | Standard Tax Invoice |
| `0100001` | Standard Tax Invoice — Self-billed |
| `0100010` | Standard Tax Invoice — Summary |
| `0100011` | Standard Tax Invoice — Summary, Self-billed |
| `0100100` | Standard Tax Invoice — Export |
| `0100110` | Standard Tax Invoice — Export, Summary |
| `0101000` | Standard Tax Invoice — Nominal |
| `0101001` | Standard Tax Invoice — Nominal, Self-billed |
| `0101010` | Standard Tax Invoice — Nominal, Summary |
| `0101011` | Standard Tax Invoice — Nominal, Summary, Self-billed |
| `0101100` | Standard Tax Invoice — Nominal, Export |
| `0101110` | Standard Tax Invoice — Nominal, Export, Summary |
| `0110000` | Standard Tax Invoice — Third-party |
| `0110001` | Standard Tax Invoice — Third-party, Self-billed |
| `0110010` | Standard Tax Invoice — Third-party, Summary |
| `0110011` | Standard Tax Invoice — Third-party, Summary, Self-billed |
| `0110100` | Standard Tax Invoice — Third-party, Export |
| `0110110` | Standard Tax Invoice — Third-party, Export, Summary |
| `0111000` | Standard Tax Invoice — Third-party, Nominal |
| `0111001` | Standard Tax Invoice — Third-party, Nominal, Self-billed |
| `0111010` | Standard Tax Invoice — Third-party, Nominal, Summary |
| `0111011` | Standard Tax Invoice — Third-party, Nominal, Summary, Self-billed |
| `0111100` | Standard Tax Invoice — Third-party, Nominal, Export |
| `0111110` | Standard Tax Invoice — Third-party, Nominal, Export, Summary |
| `0200000` | Simplified Tax Invoice |
| `0200010` | Simplified Tax Invoice — Summary |
| `0201000` | Simplified Tax Invoice — Nominal |
| `0201010` | Simplified Tax Invoice — Nominal, Summary |
| `0210000` | Simplified Tax Invoice — Third-party |
| `0210010` | Simplified Tax Invoice — Third-party, Summary |
| `0211000` | Simplified Tax Invoice — Third-party, Nominal |
| `0211010` | Simplified Tax Invoice — Third-party, Nominal, Summary |
## Validation Rules
| Field | Test | Validation Code / Message |
| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `issue_time`
Calculated | | `GOBL-SA-ZATCA-BILL-INVOICE-01`
Invoice issue time must be present (BR-KSA-70) |
| `tax` | | `GOBL-SA-ZATCA-BILL-INVOICE-02`
Invoice tax must be present |
| `tax.ext` | - Ext require \[untdid-document-type]
| `GOBL-SA-ZATCA-BILL-INVOICE-03`
Invoice tax untdid-document-type extension is required |
| `tax.ext` | - Ext require \[sa-zatca-invoice-type]
| `GOBL-SA-ZATCA-BILL-INVOICE-04`
Invoice tax sa-zatca-invoice-type extension is required |
| `tax.ext` | - Ext 'untdid-document-type' in \[388, 386, 383, 381]
| `GOBL-SA-ZATCA-BILL-INVOICE-05`
Invoice tax untdid-document-type extension must be a valid ZATCA type (388, 386, 383, 381) (BR-KSA-05) |
| `tax.ext` | - Ext 'sa-zatca-invoice-type' in \[0100000, 0100001, 0100010, 0100011, 0100100, 0100110, 0101000, 0101001, 0101010, 0101011, 0101100, 0101110, 0110000, 0110001, 0110010, 0110011, 0110100, 0110110, 0111000, 0111001, 0111010, 0111011, 0111100, 0111110, 0200000, 0200010, 0201000, 0201010, 0210000, 0210010, 0211000, 0211010]
| `GOBL-SA-ZATCA-BILL-INVOICE-06`
Invoice tax sa-zatca-invoice-type extension must be valid (BR-KSA-06) |
| `preceding` | - Invoice type in \[credit-note, debit-note]
- Present
| `GOBL-SA-ZATCA-BILL-INVOICE-07`
Credit and debit notes must have a billing reference |
| `preceding[*].code` | - Invoice type in \[credit-note, debit-note]
- Present
| `GOBL-SA-ZATCA-BILL-INVOICE-08`
Credit or debit note billing reference must have an identifier (BR-KSA-56) |
| `preceding[*].reason` | - Invoice type in \[credit-note, debit-note]
- Present
| `GOBL-SA-ZATCA-BILL-INVOICE-09`
Credit and debit notes must contain the reason for issuance (BR-KSA-17) |
| `customer` | - Standard tax invoice
- Invoice customer must have a tax id code or a valid identification (TIN/CRN/MOM/MLS/700/SAG/NAT/GCC/IQA/PAS/OTH) for standard invoices (BR-KSA-14), (BR-KSA-81)
| `GOBL-SA-ZATCA-BILL-INVOICE-13`
Invoice customer must have a valid identification scheme for standard invoices |
| `customer.addresses[*].street` | - Standard tax invoice
- Present
| `GOBL-SA-ZATCA-BILL-INVOICE-10`
Invoice customer address must have a street name for standard tax invoices (BR-KSA-10) |
| `customer.addresses[*].locality` | - Standard tax invoice
- Present
| `GOBL-SA-ZATCA-BILL-INVOICE-11`
Invoice customer address must have a city name for standard tax invoices (BR-KSA-10) |
| `customer.addresses[*].country` | - Standard tax invoice
- Present
| `GOBL-SA-ZATCA-BILL-INVOICE-12`
Invoice customer address must have a country code for standard tax invoices (BR-KSA-10) |
| `lines[*].taxes` | - Standard tax invoice
- Present
| `GOBL-SA-ZATCA-BILL-INVOICE-14`
Invoice line taxes are required for standard tax invoices (BR-KSA-52) |
| `delivery` | - Standard tax invoice
- Present
| `GOBL-SA-ZATCA-BILL-INVOICE-15`
Invoice delivery must be present for standard tax invoices |
| `delivery.date` | - Standard tax invoice
- Present
| `GOBL-SA-ZATCA-BILL-INVOICE-16`
Invoice delivery must have a supply date for standard tax invoices (BR-KSA-15) |
| `customer.tax_id` | | `GOBL-SA-ZATCA-BILL-INVOICE-17`
Invoice customer must not have a tax id for export invoices (BR-KSA-46) |
| `delivery` | - Invoice is simplified and summary
- Present
| `GOBL-SA-ZATCA-BILL-INVOICE-18`
Invoice delivery must be present for simplified and summary invoices |
| `delivery.period` | - Invoice is simplified and summary
- Present
| `GOBL-SA-ZATCA-BILL-INVOICE-19`
Invoice supply must have a delivery period for simplified and summary invoices |
| `delivery.period.start` | - Invoice is simplified and summary
- Present
| `GOBL-SA-ZATCA-BILL-INVOICE-20`
Invoice delivery start date must be present for simplified and summary invoices (BR-KSA-72) |
| `delivery.period.end` | - Invoice is simplified and summary
- Present
| `GOBL-SA-ZATCA-BILL-INVOICE-21`
Invoice delivery end date must be present for simplified and summary invoices (BR-KSA-72) |
| `customer.identities` | - Has EDU or HEA tax exemption
- Has a type in \[NAT]
| `GOBL-SA-ZATCA-BILL-INVOICE-22`
Invoice customer must have a national ID (NAT) when tax exemption is VATEX-SA-EDU or VATEX-SA-HEA (BR-KSA-49) |
| `customer` | - Simplified and (EDU or HEA exemptions), or invoice is simplified and summary, or standard tax invoice
- Present
| `GOBL-SA-ZATCA-BILL-INVOICE-23`
Invoice customer must be present for standard tax invoices, simplified summary invoices, and simplified invoices with EDU or HEA exemptions |
| `customer.name` | - Simplified and (EDU or HEA exemptions), or invoice is simplified and summary, or standard tax invoice
- Present
| `GOBL-SA-ZATCA-BILL-INVOICE-24`
Invoice customer must be present for standard tax invoices, simplified summary invoices, and simplified invoices with EDU or HEA exemptions (BR-KSA-71), (BR-KSA-25), (BR-KSA-42) |
| `supplier.tax_id` | | `GOBL-SA-ZATCA-BILL-INVOICE-25`
Invoice supplier must have a tax id (BR-KSA-39) |
| `supplier.tax_id.code` | | `GOBL-SA-ZATCA-BILL-INVOICE-26`
Invoice supplier must have a tax id code (BR-KSA-39) |
| `supplier.identities` | - Identity must be one of: CRN/MOM/MLS/700/SAG/OTH
| `GOBL-SA-ZATCA-BILL-INVOICE-27`
Invoice supplier must have a valid identity (CRN/MOM/MLS/700/SAG/OTH) (BR-KSA-08) |
| `customer.tax_id` | - Invoice is self-billed
- Present
| `GOBL-SA-ZATCA-BILL-INVOICE-28`
Invoice customer must have a tax id when self-billed (BR-KSA-39) |
| `customer.tax_id.code` | - Invoice is self-billed
- Present
| `GOBL-SA-ZATCA-BILL-INVOICE-29`
Invoice customer must have a tax id code when self-billed (BR-KSA-39) |
| `customer.identities` | - Invoice is self-billed
- Identity must be one of: CRN/MOM/MLS/700/SAG/OTH
| `GOBL-SA-ZATCA-BILL-INVOICE-30`
Invoice customer must have a valid identity for self-billed invoices (CRN/MOM/MLS/700/SAG/OTH) (BR-KSA-08) |
| Field | Test | Validation Code / Message |
| --------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `charges` | | `GOBL-SA-ZATCA-BILL-LINE-01`
Invoice line charges are not allowed (BR-KSA-EN16931-06) |
| Field | Test | Validation Code / Message |
| -------------- | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `country` | | `GOBL-SA-ZATCA-ORG-ADDRESS-01`
Address must have a country code |
| `street` | - Country code is SA
- Present
| `GOBL-SA-ZATCA-ORG-ADDRESS-02`
Invoice addresses in SA must have a street name (BR-KSA-09), (BR-KSA-63) |
| `num` | - Country code is SA
- Present
- Matches ^\d{4}\$
| `GOBL-SA-ZATCA-ORG-ADDRESS-03`
Invoice addresses in SA must have a 4 digits building number (BR-KSA-09), (BR-KSA-63), (BR-KSA-37) |
| `code` | - Country code is SA
- Present
- Matches ^\d{5}\$
| `GOBL-SA-ZATCA-ORG-ADDRESS-04`
Invoice addresses in SA must have a 5 digits postal code (BR-KSA-09), (BR-KSA-63) (BR-KSA-67), (BR-KSA-66) |
| `locality` | - Country code is SA
- Present
| `GOBL-SA-ZATCA-ORG-ADDRESS-05`
Invoice addresses in SA must have a city name (BR-KSA-09), (BR-KSA-63) |
| `street_extra` | - Country code is SA
- Present
| `GOBL-SA-ZATCA-ORG-ADDRESS-06`
Invoice addresses in SA must have a district name (BR-KSA-09), (BR-KSA-63) |
| Field | Test | Validation Code / Message |
| ----- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ext` | - Valid SA VAT exemption code
| `GOBL-SA-ZATCA-TAX-COMBO-01`
Invoice line tax cef-vatex extension code must be present and valid for Z/E/O categories, and must not be set for Standard (BR-KSA-CL-04) |
| `ext` | - Ext 'untdid-tax-category' in \[S, Z, E, O]
| `GOBL-SA-ZATCA-TAX-COMBO-02`
Invoice line tax untdid-tax-category extension code must contain one of the values (S, Z, E, O) (BR-KSA-18) |
| `cat` | | `GOBL-SA-ZATCA-TAX-COMBO-03`
Tax schema id must be 'VAT' (BR-KSA-54) |