ZATCA Clearance API

01Overview & flow

ERPNext is the e-invoice generation solution (EGS) registered with ZATCA. The KSA Compliance app owns the CSID, invoice counter (ICV) and previous-invoice hash chain (PIH). The client ERP stays the customer-facing system and calls ERPNext for every tax invoice.

1. Sync masters Client ERPMake sure the customer, address and items exist in ERPNext. Upsert before each invoice or sync on a schedule.
2. Create and submit the invoice Client ERPPOST a Sales Invoice with docstatus: 1. Submission triggers the ZATCA process.
3. Sign, hash and send to ZATCA ERPNextThe app builds UBL 2.1 XML, signs it, embeds the QR, stores everything in a Sales Invoice Additional Fields record, and calls the clearance API (B2B) or reporting API (B2C).
4. Read the result Client ERPPoll the Additional Fields record or receive a webhook. Wait for Accepted or Accepted with warnings.
5. Print and share Client ERPRender the invoice using ERPNext's invoice number, UUID and QR. For B2B, attach the XML or the ZATCA PDF/A-3.

02Authentication

Use token authentication with a dedicated API user. Generate keys in ERPNext under User → API Access → Generate Keys. Give the user a restricted role that can create and read Customers, Addresses, Items and Sales Invoices, and read Sales Invoice Additional Fields and ZATCA Integration Log.

Authorization: token <api_key>:<api_secret>
Content-Type: application/json
Accept: application/json

{ "message": "zatca-api@client.sa" }

03Conventions

Every DocType is exposed at /api/resource/{DocType}. URL-encode spaces in DocType names (Sales%20Invoice). Resource calls return {"data": …}; method calls return {"message": …}.

ZATCA field names on this site

Confirmed against ksa_compliance v0.61.11. Re-check after an app upgrade with GET /api/method/frappe.desk.form.load.getdoctype?doctype=<DocType>.

04Reference data

Read these once and cache the names. They are used as link values in invoices.

Companies on this site

With Live sync the result is written right after submit. With Batches the scheduler sends invoices later, so expect Ready For Batch for a while.

05Customers & items

B2B (standard) invoices need the buyer's VAT number and full Saudi national address. B2C (simplified) invoices can use a walk-in customer.

Customer

{
  "customer_name": "Al Noor Trading Co.",
  "customer_type": "Company",
  "customer_group": "Commercial",
  "custom_vat_registration_number": "310122393500003",
  "tax_id": "310122393500003",
  "custom_additional_ids": [
    { "type_name": "Commercial Registration number", "type_code": "CRN", "value": "1010123456" }
  ]
}

Address

{
  "address_title": "Al Noor Trading Co.",
  "address_type": "Billing",
  "address_line1": "King Fahd Road",
  "custom_building_number": "7765",
  "custom_area": "Al Olaya",
  "city": "Riyadh",
  "pincode": "12214",
  "country": "Saudi Arabia",
  "is_primary_address": 1,
  "links": [
    { "link_doctype": "Customer", "link_name": "Al Noor Trading Co." }
  ]
}

Item

{
  "item_code": "SKU-1042",
  "item_name": "Thermal paper roll 80mm",
  "item_group": "Products",
  "stock_uom": "Nos",
  "is_stock_item": 0
}

06Tax invoice

One endpoint covers standard invoices, simplified invoices, credit notes and debit notes. Submitting the document (docstatus: 1) starts the ZATCA process.

Create & submit

{
  "customer": "Al Noor Trading Co.",
  "company": "Demo Company",
  "set_posting_time": 1,
  "posting_date": "2026-10-17",
  "posting_time": "10:24:00",
  "currency": "SAR",
  "custom_external_ref": "INV-ERP-88213",
  "taxes_and_charges": "KSA VAT 15% - Demo",
  "items": [
    { "item_code": "SKU-1042", "qty": 20, "rate": 12.50, "uom": "Nos",
      "custom_zatca_item_tax_category": "Standard rate" },
    { "item_code": "SKU-2210", "qty": 2, "rate": 340.00, "uom": "Nos",
      "custom_zatca_item_tax_category": "Standard rate" }
  ],
  "docstatus": 1
}

{
  "data": {
    "name": "Demo-SINV-2026-00009",
    "docstatus": 1,
    "net_total": 930.0,
    "total_taxes_and_charges": 139.5,
    "grand_total": 1069.5,
    "custom_external_ref": "INV-ERP-88213"
  }
}

{ "docstatus": 1 }

Simplified (B2C) invoice

Same call. Use a walk-in customer of type Individual with no VAT number. With Let the system decide (both) in ZATCA Business Settings, the app detects it as simplified (invoice_type_transaction starting 02) and reports it instead of clearing it. It can be shared with the buyer straight away and must be reported to ZATCA within 24 hours.

Credit note

{
  "customer": "Al Noor Trading Co.",
  "company": "Demo Company",
  "is_return": 1,
  "return_against": "Demo-SINV-2026-00009",
  "custom_return_reason": "Damaged goods returned",
  "taxes_and_charges": "KSA VAT 15% - Demo",
  "items": [
    { "item_code": "SKU-1042", "qty": -5, "rate": 12.50 }
  ],
  "docstatus": 1
}

Debit note

{
  "customer": "Al Noor Trading Co.",
  "company": "Demo Company",
  "is_debit_note": 1,
  "return_against": "Demo-SINV-2026-00009",
  "custom_return_reason": "Freight charge not billed",
  "taxes_and_charges": "KSA VAT 15% - Demo",
  "items": [
    { "item_code": "FREIGHT", "qty": 1, "rate": 150.00 }
  ],
  "docstatus": 1
}

07ZATCA result & QR

Treat an invoice as issued only when ZATCA has accepted it. The status is the integration_status field of the latest Sales Invoice Additional Fields record.

B2B or B2C: invoice_type_transaction starting 01 is standard (B2B), 02 is simplified (B2C). invoice_type_code is 388 for an invoice, 381 for a credit note and 383 for a debit note.

GET /api/resource/Sales Invoice Additional Fields
  ?filters=[["sales_invoice","=","Demo-SINV-2026-00009"],["is_latest","=",1]]
  &fields=["name","integration_status","uuid","qr_code","invoice_hash",
           "invoice_counter","invoice_type_code","invoice_type_transaction",
           "validation_errors","validation_messages","last_attempt"]

{
  "data": [{
    "name": "Demo-SINV-2026-00009-AdditionalFields-8",
    "integration_status": "Accepted",
    "uuid": "7065bbcd-b2f5-4dd8-9aa2-9aa823132794",
    "qr_code": "AQxEZW1vIENvbXBhbnkCDzMwMDAw…",
    "invoice_counter": 8,
    "invoice_type_code": "388",
    "invoice_type_transaction": "0100000"
  }]
}

GET /api/resource/Sales Invoice Additional Fields
  ?filters=[["is_latest","=",1],
            ["integration_status","in",["Ready For Batch","Resend","Rejected"]]]
  &fields=["name","sales_invoice","integration_status","last_attempt","modified"]
  &order_by=modified asc
  &limit=100

GET /api/resource/Sales Invoice Additional Fields
  ?filters=[["sales_invoice","=","Demo-SINV-2026-00009"],["is_latest","=",1]]
  &fields=["name","invoice_xml"]

08Retry

If ZATCA was unreachable, the record goes to Resend and the app sends it again on its schedule. Don't create a new invoice, or the hash chain will break.

GET /api/resource/ZATCA Integration Log
  ?filters=[["invoice_reference","=","Demo-SINV-2026-00009"]]
  &fields=["name","status","zatca_status","zatca_http_status_code","zatca_message","creation"]
  &order_by=creation desc

09Webhook callback

Instead of polling, ERPNext can call the client ERP when the app updates the ZATCA status. Hook the Sales Invoice Additional Fields DocType, not Sales Invoice. Set it up once, in the UI or via the API.

{
  "webhook_doctype": "Sales Invoice Additional Fields",
  "webhook_docevent": "on_update_after_submit",
  "request_url": "https://client-erp.example.sa/hooks/zatca",
  "request_method": "POST",
  "request_structure": "JSON",
  "condition": "doc.is_latest and doc.integration_status in ('Accepted','Accepted with warnings','Rejected')",
  "enable_security": 1,
  "webhook_secret": "<shared-secret>",
  "webhook_json": "{\"invoice\": \"{{ doc.sales_invoice }}\", \"record\": \"{{ doc.name }}\", \"status\": \"{{ doc.integration_status }}\", \"uuid\": \"{{ doc.uuid }}\"}"
}

10Errors

Frappe returns the error type in exc_type and readable messages in _server_messages (a JSON-encoded list).

ZATCA's own rejection messages (for example BR-KSA-… rule codes) are not returned as HTTP errors. Read them from validation_errors and validation_messages on the Additional Fields record, or zatca_message on the ZATCA Integration Log.

11Sharing with customers

The client ERP can print and send invoices itself, as long as what it sends matches what ZATCA accepted.

• B2B: share only after status is Accepted or Accepted with warnings. Deliver electronically as XML, or PDF/A-3 with the XML embedded.
• B2C: share immediately at the point of sale with the Phase 2 QR printed on it.
• QR: always use qr_code from ERPNext. Never generate one in the client ERP.
• Content: number, date, seller and buyer details, lines, VAT and totals must match the XML exactly.
• Invoice number: print ERPNext's number (e.g. Demo-SINV-2026-00009) as the tax invoice number, with the client ERP number as a reference. Alternatively configure ERPNext naming to use the client ERP's sequential number.
• Cancellation: accepted invoices can't be cancelled. Issue a credit note.

12Go-live checklist

• ZATCA onboarding completed for each VAT registration: ZATCA Business Settings, CLI set up, CSR, OTP from Fatoora portal, compliance checks, production CSID
• 3 AI Minds, Rawasi and Spare7Plus onboarded if they will issue invoices (none has ZATCA Business Settings yet; 3 AI Minds has no VAT number)
• Seller company has VAT number, CR and full national address
• custom_external_ref custom field created on Sales Invoice, marked Unique
• Field names in Conventions re-checked after any ksa_compliance upgrade
• Dedicated API user with a restricted role; keys stored in a secrets vault
• Invoices submitted in a single queue, one at a time, so the hash chain stays in order
• Integration tested on Demo Company (Sandbox) before any call to the Production company
• Rejected and Resend handling, and alerting, tested in Sandbox or Simulation
• Print layout shows ERPNext invoice number, UUID and a readable Phase 2 QR
• B2B delivery includes the XML or PDF/A-3
• Credit and debit notes tested end to end
• Delivery and format rules re-checked against ZATCA's latest implementation guidelines