Comply with ZATCA e-Invoicing using B2Brouter API

The ZATCA e-Invoicing Resolution (Zakat, Tax and Customs Authority) mandates that businesses operating in Saudi Arabia must generate and submit electronic invoices in UBL XML format. B2Brouter's REST API allows your business to be fully compliant with ZATCA, handling XML generation, hash chaining, and clearance on your behalf.

What is ZATCA e-Invoicing?

ZATCA e-Invoicing (Fatoorah) requires:

• Generating invoices in UBL 2.1 XML format, with Saudi-specific extensions.
• Computing a SHA-256 hash chain linking each invoice to the previous one.
• Submitting each invoice to the ZATCA Clearance API for validation and digital signing.
• Embedding the QR code returned by ZATCA in the issued invoice.

With B2Brouter you can offload all of this. You issue invoices or create tax reports via REST calls, and B2Brouter handles chaining, clearance, and QR code generation.

Account (Company) Requirements

ZATCA invoices are issued by Saudi Arabian companies. The account must have country: "sa". The following fields are required for SA accounts:

Note: The fields address2 and province correspond to the Saudi address concepts of building number and district respectively. Use address2 and province as the API param names — the API will return errors referencing these names.

Contact Requirements

Contacts (buyers) for ZATCA invoices must also have correct address data. The following fields apply when country is "sa":

Invoice Requirements

ZATCA invoices use SAR (Saudi Riyal) as currency. Taxes must use name: "VAT" and category: "S" for the standard 15% rate.

Minimal invoice example:

curl --request POST \
     --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/invoices \
     --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
     --header 'Content-Type: application/json' \
     --data '{
       "send_after_import": true,
       "invoice": {
         "date": "2025-01-15",
         "number": "INV-001",
         "currency": "SAR",
         "payment_method": 1,
         "contact": {
           "name": "Buyer Company Ltd",
           "address": "King Fahd Road",
           "address2": "1234",
           "city": "Riyadh",
           "postalcode": "12345",
           "province": "Riyadh",
           "country": "sa",
           "tin_value": "310175397400003",
           "tin_scheme": 9760,
           "language": "en",
           "currency": "SAR"
         },
         "invoice_lines_attributes": [
           {
             "quantity": 1.0,
             "description": "Professional services",
             "price": 100.0,
             "taxes_attributes": [
               {
                 "name": "VAT",
                 "percent": 15.0,
                 "category": "S"
               }
             ]
           }
         ]
       }
     }'

Tax Categories and Exemption Codes

ZATCA defines four VAT categories. For categories E (Exempt) and Z (Zero rated), a valid exemption reason code (comment on the tax line) is required — the invoice will be rejected without it.

The exemption code is set in the comment field of the tax line:

{
  "name": "VAT",
  "percent": 0.0,
  "category": "Z",
  "comment": "VATEX-SA-32"
}

Valid VATEX-SA-* Codes

Category E — Exempt from VAT

Category Z — Zero rated

Category O — Out of scope

Buyer ID Types

For foreign buyers (non-SA), use tin_scheme to specify the identifier type:

Tax Report Lifecycle

After creating or sending an invoice, ZATCA clearance is asynchronous. The tax_report will be in processing state initially.

Monitor progress via:

• Webhook (recommended): Subscribe to the tax report state change webhook. Final states are registered, error, registered_with_errors.
• Polling: Call the get tax report endpoint until the state is final.

Field Mapping: Invoice API → ZATCA XML