Saudi Arabia ZATCA

Key: sa-zatca-v1 Module: 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

Scenarios

bill/invoice

standard

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.

sa-zatca-invoice-type

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

bill.Invoice

Field	Test	Validation Code / Message
`issue_time` Calculated	Present	`GOBL-SA-ZATCA-BILL-INVOICE-01` Invoice issue time must be present (BR-KSA-70)
`tax`	Present	`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`	Export invoice Empty	`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`	Present	`GOBL-SA-ZATCA-BILL-INVOICE-25` Invoice supplier must have a tax id (BR-KSA-39)
`supplier.tax_id.code`	Present	`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)

bill.Line

Field	Test	Validation Code / Message
`charges`	Length between 0 and 0	`GOBL-SA-ZATCA-BILL-LINE-01` Invoice line charges are not allowed (BR-KSA-EN16931-06)

org.Address

Field	Test	Validation Code / Message
`country`	Present	`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$	`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$	`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)

tax.Combo

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`	One of [VAT]	`GOBL-SA-ZATCA-TAX-COMBO-03` Tax schema id must be ‘VAT’ (BR-KSA-54)

​Sources

​Scenarios

​bill/invoice

​Extensions

​ZATCA Invoice Transaction Type

​Validation Rules