ZATCA API · Fatoora integration
ZATCA API & Fatoora integration — without the boilerplate
Developers and ERP teams search for a ZATCA API because Phase 2 requires live connection to the Fatoora platform: EGS onboarding, Production CSID, UBL 2.1 signing, PIH chain, B2B clearance, and B2C reporting. Esnad is middleware — you POST JSON, we return a cleared or reported invoice with UUID and QR code.
Why teams look for a Fatoora API integration
- ✓Phase 2 (Integration) is mandatory in waves — Wave 25 must integrate with Fatoora by 1 February 2027 if VAT-subject revenue exceeded SAR 187,500 in any of 2022–2025; penalties apply after deadlines.
- ✓Direct Fatoora integration means ECDSA keys, CSR with ZATCA OIDs, Compliance + Production CSID, and 3–6 compliance test invoices before go-live.
- ✓Every invoice needs UBL 2.1 XML, XAdES signing, ICV/PIH chain per EGS unit, TLV QR (B2C), clearance (B2B), or 24h reporting (B2C).
- ✓Building and maintaining this in-house takes weeks; a middleware API lets your product team ship in days.
What Esnad's ZATCA API handles for you
EGS & CSID lifecycle
Sandbox and production onboarding, OTP flow, cert renewal alerts, and renewal API.
UBL 2.1 + signing
Saudi profile XML, canonical hash, PIH chain, ECDSA stamp — from your JSON payload.
Fatoora clearance & reporting
B2B standard invoices cleared before delivery; B2C simplified reported within 24 hours.
Retries & webhooks
Queue when ZATCA is slow; HMAC-signed webhooks on cleared/reported/failed.
Example: one API call
const response = await fetch('https://api.esnadapi.com/v1/invoices/simplified', {
method: 'POST',
headers: {
'Authorization': 'Bearer zatca_live_xxxxxxxxxxxx',
'Idempotency-Key': crypto.randomUUID(),
'Content-Type': 'application/json',
},
body: JSON.stringify({
egs_unit_id: 'egs_abc123',
invoice_number: 'INV-2026-001',
invoice_date: '2026-01-15',
seller: { name: 'Al Noor Trading', vat_number: '310122393500003' },
line_items: [{ description: 'Cappuccino', quantity: 2, unit_price: 18.00, vat_category: 'S' }],
currency: 'SAR'
})
});
const data = await response.json();
// data.uuid, data.qr_code, data.status === 'reported'DIY Fatoora integration vs Esnad API
Calling gw-fatoora.zatca.gov.sa directly gives you full control but binds your team to ZATCA spec changes, certificate rotation, and invoice hash chains forever. Esnad keeps your integration surface stable: same REST endpoints while we absorb ZATCA updates.
ZATCA API integration — common questions
- Is there an official ZATCA API?
- Yes — ZATCA exposes the Fatoora platform via REST APIs for onboarding (Compliance/Production CSID), clearance (B2B), and reporting (B2C). Esnad wraps these so you integrate once with our JSON API.
- What is Fatoora API integration?
- It is connecting your billing or ERP system to ZATCA's Fatoora platform so invoices are cryptographically signed and submitted in real time (clearance or reporting) instead of only stored locally as in Phase 1.
- Do I need separate flows for B2B and B2C?
- Yes. Standard tax invoices (B2B/B2G) require synchronous clearance before the buyer receives the invoice. Simplified tax invoices (B2C/POS) are issued first and reported to ZATCA within 24 hours.
- Can I test before production?
- Esnad provides a sandbox environment with test API keys (zatca_test_*). Request a trial and we provision your dashboard within 24 hours.
- Does Esnad cover ZATCA Wave 25 (1 February 2027)?
- Yes. Wave 25 Phase 2 integration (VAT-subject revenue over SAR 187,500 in any of 2022–2025) uses the same Fatoora clearance and reporting APIs. Esnad’s JSON contract stays the same; you still complete Fatoora OTP for EGS/CSID before 1 February 2027.
ZATCA Phase 2 explained (compliance guide)Live dashboard demo