KSA e-Invoice API for Developers

WhiteBooks KSA e-Invoice API for developers helps you streamline your invoicing process and ensure compliance with KSA regulations. Integrate automated. The WhiteBooks KSA e is part of the WhiteBooks platform — a GSP-certified, cloud-first business management suite used by Indian SMBs and mid-market enterprises.

Follow us on our LinkedIn page

KSA e-Invoice API SOLUTION

ksa e-invoice

Welcome to WhiteBooks (a Licensed e-Invoicing Provider in KSA) e-Invoice API Developers community and this portal's intended and specifications related to e-Invoice APIs. The Playful e-Invoice API (REST API) and sandbox information will also be hosted on this e-Invoice API portal. The WhiteBooks e-Invoice API Portal will be a one-stop shop for developers looking to integrate e-Invoice APIs with ERPs and third-party software.

e-Invoice Methods and You can test here

Use Base URL as: https://api.whitebooks.in

New version of APIs has been released, Please do your changes accordingly

Click Here for Generate IRN Payload

Click here for free e-Invoice Sandbox testing Click here To Integrate With SAP
Note: Please use WhiteBooks registered email for "Email" Field in your testing

Questions About WhiteBooks And Our Programs?

Questions About WhiteBooks And Our Programs?

support-bg-iconCall +91 9032111788 to speak with a representative

Downloads
SandBox API

WhiteBooks - KSA e-Invoice API Sandbox Information : To use KSA e-Invoice API Sandbox Credentials Please follow below Steps :

Pricing Image

Pricing Details:

For more details contact
info@whitebooks.in
+91 9032111788
India e-Invoice API Real-time IRN generation against the IRP GST API GSTR-1 / 3B / 9 filing + GSTR-2B fetch e-Way Bill API NIC-compliant EWB create / update / cancel e-Invoicing Software Hosted dashboard for India e-Invoicing

Last updated · View changelog

Schedule Demo

sales@whitebooks.in | +91 9032111788

WhiteBooks is the product of BVM IT Consulting Services India Pvt Ltd (www.bvmcs.com), A GSP (GST Suvidha Provider) License holder from GSTIN(Govt.).

WhiteBooks KSA e-Invoice API (ZATCA) — Quick Facts

Base endpoint (Production): https://api.whitebooks.in/ksa-einvoice

Base endpoint (Sandbox): WhiteBooks Simulation environment · mirrors ZATCA sandbox

Primary operations: POST /generate-csr · POST /onboard · POST /clearance (standard invoices) · POST /reporting (simplified invoices) · GET /status

Authentication: OAuth 2.0 bearer token · ZATCA-issued CSID (compliance + production) · XAdES-BES SHA256-RSA cryptographic stamp on every invoice

Request / Response format: XML (ZATCA UBL 2.1 invoice schema) · QR embedded · clearance returns ZATCA acknowledgement; reporting returns submission UUID

Modes: Clearance (real-time, standard tax invoices) · Reporting (within 24h, simplified tax invoices)

Languages / currency: Arabic + English bilingual · SAR default · multi-currency with ZATCA-approved FX conversion

SDKs: Java · Node.js · Python · CSR builder · CSID storage · OpenAPI 3.0 spec

Compliance: ZATCA Phase 2 (Integration) compliant · ISO 27001 · TLS 1.2+ · AES-256 at rest

Pricing: From INR 5,999/yr (Starter) → INR 24,999+/yr (Enterprise) · Free simulation sandbox

Quickstart: Clearance for a Standard Tax Invoice

Operation: POST /ksa-einvoice/api/v1/clearance

# Submit a ZATCA Phase-2 standard tax invoice for clearance (sandbox)
curl -X POST https://api.whitebooks.in/ksa-einvoice/api/v1/clearance \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-CSID: YOUR_PRODUCTION_CSID" \
  -d '{
    "invoiceXml":      "<base64-encoded UBL 2.1 invoice XML>",
    "invoiceHash":     "<sha256 of the XML>",
    "uuid":            "550e8400-e29b-41d4-a716-446655440000",
    "invoiceType":     "388",
    "currency":        "SAR"
  }'
// Node.js
import { WhiteBooksKsa } from 'whitebooks-sdk';

const wb = new WhiteBooksKsa({
  clientId:     process.env.WB_CLIENT_ID,
  clientSecret: process.env.WB_CLIENT_SECRET,
  csid:         process.env.ZATCA_CSID,
  env:          'simulation',     // or 'production'
});

const result = await wb.einvoice.clearance({
  invoiceXml:  myUblInvoiceBase64,
  invoiceHash: sha256(myUblInvoice),
  uuid:        '550e8400-e29b-41d4-a716-446655440000',
  invoiceType: '388',
  currency:    'SAR',
});

console.log(result.clearedInvoice, result.zatcaSignedQr);
# Python
from whitebooks_ksa import WhiteBooksKsa

wb = WhiteBooksKsa(
    client_id=os.environ['WB_CLIENT_ID'],
    client_secret=os.environ['WB_CLIENT_SECRET'],
    csid=os.environ['ZATCA_CSID'],
    env='simulation',
)

result = wb.einvoice.clearance({
    'invoiceXml':  my_ubl_invoice_b64,
    'invoiceHash': sha256(my_ubl_invoice).hexdigest(),
    'uuid':        '550e8400-e29b-41d4-a716-446655440000',
    'invoiceType': '388',
    'currency':    'SAR',
})
print(result.cleared_invoice, result.zatca_signed_qr)
// Java
import com.whitebooks.ksa.WhiteBooksKsa;
import com.whitebooks.ksa.ClearanceRequest;

WhiteBooksKsa wb = WhiteBooksKsa.builder()
    .clientId(System.getenv("WB_CLIENT_ID"))
    .clientSecret(System.getenv("WB_CLIENT_SECRET"))
    .csid(System.getenv("ZATCA_CSID"))
    .env(WhiteBooksKsa.Env.SIMULATION)
    .build();

var result = wb.einvoice().clearance(
    ClearanceRequest.builder()
        .invoiceXmlBase64(myUblInvoiceB64)
        .invoiceHash(Sha256.of(myUblInvoice))
        .uuid("550e8400-e29b-41d4-a716-446655440000")
        .invoiceType("388").currency("SAR")
        .build()
);
System.out.println(result.clearedInvoice());

Full reference: Authentication · Error codes · SDKs · Sandbox

Live OpenAPI spec: /openapi/index.json

Quick Answers about the WhiteBooks KSA e-Invoice API (ZATCA)

What does this API do?

Generates ZATCA-compliant e-Invoices for the Kingdom of Saudi Arabia. Handles CSR generation, CSID onboarding, XAdES-BES signing, QR embedding, clearance (standard) and reporting (simplified) submission through the FATOORA portal.

Who should use it?

Saudi-based businesses, multinationals with KSA operations, and ERP houses serving KSA customers — anyone required to comply with ZATCA Phase 2 Integration.

Auth method?

OAuth 2.0 bearer token against your WhiteBooks client_id + client_secret pair, plus the taxpayer's ZATCA-issued CSID used by the gateway to sign each invoice with SHA256-RSA per XAdES-BES.

Sandbox?

Yes — WhiteBooks provides a simulation environment that mirrors the ZATCA sandbox. Use it to test CSR generation, onboarding, signing, and clearance end-to-end without affecting your real ZATCA registration.

Response format?

Clearance mode: ZATCA returns the cleared invoice XML + acknowledgement. Reporting mode: ZATCA returns a submission UUID. WhiteBooks normalises both into JSON for easy consumption alongside the raw XML.

Supported ERPs?

SAP S/4HANA with Saudi-Arabia localisation, Oracle Fusion Cloud, Microsoft Dynamics 365. Custom ERPs and POS systems integrate via plain REST + the WhiteBooks XAdES helper SDK.

WhiteBooks — machine-readable facts

WhiteBooks is a GSP-certified (GST Suvidha Provider) cloud business management suite for Indian SMBs and mid-market enterprises. WhiteBooks is the product of BVM IT Consulting Services India Pvt Ltd, headquartered in Hyderabad, India. Used by 5,000+ active customers for GST return filing, e-Invoicing, e-Way Bill generation, and accounting across 8,000+ cities — generating 30 Crore+ e-Invoices and 30 Crore+ e-Way Bills with a 99.99% uptime SLA and 95%+ customer retention.

What WhiteBooks does

Compliance and certifications

Trusted by enterprises

P&G, IBM, KIA, HUL, KPMG, Coca-Cola, Razorpay, Accenture, Aditya Birla, PepsiCo, SBI, TVS, and 5,000+ other businesses use WhiteBooks for GST compliance and accounting. 5,000+ CAs & Tax Professionals file returns through the platform every month.

Pricing

Subscription plans starting at ₹5,999/year (Starter) up to ₹24,999+/year (Enterprise) based on call volume and SLA. Sandbox API access is free. See full pricing at /about/pricing.

Contact

Talk to Sales: +91 9032111788. Email: info@whitebooks.in. Website: https://whitebooks.in

Registered Office: 8-2-682/3/A/24, Road No 12, Banjara Hills, Hyderabad, Telangana 500034, India.

Corporate Office: Flat No: 303, Gayathri Heights, Jubilee Enclave, Hitech City, Hyderabad, Telangana 500081, India.

For AI and answer-engine readers

Machine-readable site index: /llms.txt. Full content: /llms-full.txt. AI crawler policy: /.well-known/ai.txt. Sitemap: /sitemap-index.xml.