WhiteBooks logo
Sign inSign up
KSA e-Invoice API | ZATCA Phase 2 Compliant

KSA e-Invoice API — ZATCA Phase 2 integration without becoming a specialist.

Generate, sign, and clear ZATCA-compliant e-invoices via REST. CSID lifecycle managed for you. Bilingual invoice rendering, QR generation, FATOORAH clearance — all in one API call.

1import WhiteBooks from '@whitebooks/node'
2
3const client = new WhiteBooks({
4 apiKey: process.env.WB_API_KEY,
5 sandbox: false,
6});
7
8// Sign and clear a ZATCA standard tax invoice
9const inv = await client.ksaEinvoice.create({
10 vatNumber: "300000000000003",
11 invoiceType: "STANDARD",
12 invoiceNumber: "INV-001",
13 currency: "SAR",
14});
15
16console.log("UUID:", inv.uuid)
200 OK·142ms

Three reasons ZATCA Phase 2 integrations are painful to build alone.

01

Cryptographic signing is not a weekend project

ZATCA Phase 2 requires generating a CSR, retrieving a CSID from ZATCA, signing every invoice with the certificate, and managing renewal — all under specific cryptographic standards. WhiteBooks handles certificate lifecycle entirely.

02

FATOORAH integration is real-time and unforgiving

Standard tax invoices must be cleared by ZATCA before they reach the buyer. Latency, retries, and error handling matter. WhiteBooks runs production-grade infrastructure with documented SLAs.

03

Bilingual invoice generation is its own engineering problem

Right-to-left rendering, Arabic-English field pairing, currency formatting per ZATCA spec — most engineering teams underestimate this work. WhiteBooks ships it as a default.

The endpoints.

POST/v1/ksa/einvoice/create

Generate, sign, and submit a standard tax invoice to FATOORAH. Returns cleared invoice with QR code and signed XML.

POST/v1/ksa/einvoice/simplified

Generate simplified tax invoice (B2C, under SAR 1,000). Real-time signing, no clearance required (reported within 24 hours).

POST/v1/ksa/einvoice/credit-note

Issue credit note linked to a previously cleared invoice. Auto-populates buyer fields, applies reverse logic.

GET/v1/ksa/csid/status

Check CSID validity, expiry, and renewal schedule for your account.

POST/v1/ksa/csid/renew

Trigger CSID renewal before expiry. WhiteBooks handles the ZATCA portal interaction.

GET/v1/ksa/einvoice/{invoice_id}

Retrieve full invoice details, signed XML, QR code, and FATOORAH clearance receipt.

40+ ERP Integrations

SDKs and integration patterns for KSA.

SDKs in Node.js, Python, PHP, Java, Go. Integration guides for SAP S/4HANA KSA edition, Oracle NetSuite KSA, Microsoft Dynamics 365 Business Central, and Zoho Books KSA. Webhooks: invoice cleared, invoice rejected, CSID nearing expiry, credit note issued.

Real-time Sync

Native connectors for instant data flow

Always Up-to-date

Maintained against every ERP upgrade

Zero Manual Work

No CSV exports. No email uploads.

Enterprise Secure

Bank-grade security & data protection

40+
ERP Integrations
1000+
Customers using integrations
Real-time
Data Push
99.99%
Uptime SLA
Read integration guide
  • Node.js
  • Python
  • PHP
  • Java
  • Go
  • SAP S/4HANA KSA
  • Oracle NetSuite KSA
  • Microsoft Dynamics 365
  • Zoho Books KSA

Frequently asked Questions.

How does WhiteBooks handle the CSID lifecycle?+
WhiteBooks generates the CSR, submits it to ZATCA, retrieves the issued CSID, stores it encrypted, and manages renewal before expiry. Your team never directly handles the certificate or the cryptography.
What's the difference between standard and simplified tax invoices?+
Standard tax invoices (B2B and high-value B2C over SAR 1,000) must be cleared by ZATCA in real time before reaching the buyer. Simplified invoices (B2C under SAR 1,000) are signed locally and reported to ZATCA within 24 hours.
Does WhiteBooks generate the QR code automatically?+
Yes. Every cleared invoice includes the ZATCA-compliant QR code with the required fields (supplier VAT, timestamp, total, VAT amount, hash) embedded in both XML and rendered output.
Can I use this API alongside the Indian e-Invoice API?+
Yes. The same WhiteBooks account supports both APIs with separate keys per jurisdiction. Indian-headquartered businesses with KSA operations commonly use both.
How does sandbox differ from production?+
Sandbox is bit-for-bit identical to production behavior, including ZATCA simulator responses for clearance, rejection, and certificate states. What works in dev works in prod.
What KSA-specific compliance does WhiteBooks track?+
WhiteBooks tracks ZATCA wave notifications, schema version updates, CSID renewal windows, and VAT rate changes. Customers are alerted to compliance changes before they take effect.

ZATCA Phase 2, behind six clean endpoints.

If your product sells into Saudi Arabia or your business operates there, ZATCA Phase 2 is non-optional. WhiteBooks is one of the few API providers operating ZATCA-approved infrastructure alongside a GSTN GSP license.

Get sandbox keys

See pricing · Full API reference