ZATCA e‑invoicing API: two endpoints between your software and Fatoora
Register a device with one call and submit invoices with another. You send plain JSON; we handle certificates, XML, signing and the QR code, and return ZATCA's answer in the same request.
ZATCA API quick start: a cleared invoice in three calls
Get a test key
Create an account and create a test key. Send it as a Bearer token on every request.
Register a device
Post the taxpayer's VAT number, CR number, address and the ZATCA OTP to /v1/devices. Keep the device_id that comes back.
Submit an invoice
Post the invoice to /v1/invoices with that device_id. Read the status from the response.
ZATCA e‑invoicing API endpoints
Two calls do the work. The rest let you look things up later.
Register a device or branch with ZATCA using an OTP.
List your registered devices.
Check one device's status and how many invoices it has sent.
Submit a tax invoice for clearance or reporting.
Submit a credit note against an accepted invoice.
Submit a debit note against an accepted invoice.
Fetch an invoice with its current ZATCA status.
Download the signed UBL 2.1 XML.
Check your wallet balance, price per invoice and rate limit.
API authentication
Every request carries your key in the Authorization header. A test key works with sandbox and simulation devices, a live key with production devices. The URLs are the same.
Authorization: Bearer ff_test_••••
Content-Type: application/json
Accept: application/jsonHandling ZATCA validation errors
You get ZATCA's own rule code and message, so you can show your user the real reason and fix the invoice.
{
"status": "REJECTED",
"number": "INV-2026-0419",
"zatca": {
"warnings": [],
"errors": [{
"type": "ERROR",
"code": "BR-CO-15",
"message": "Total with VAT must equal total without VAT plus VAT amount."
}]
}
}ZATCA invoice statuses and response codes
Standard invoice approved by ZATCA. Safe to send to the buyer.
Simplified invoice accepted by ZATCA's reporting service.
ZATCA refused it. Reasons are in zatca.errors. Correct and resubmit. Nothing is charged.
ZATCA could not be reached. Nothing is charged. Retry with the same number.
Wallet balance too low (402), or the API key is missing, wrong or revoked (401).
Rate limit reached. Wait for the Retry-After seconds, then retry.
ZATCA integration for ERP, POS and billing software
No certificates to manage
Keys, CSRs and CSIDs are created and stored per device on our side.
ZATCA's messages, unedited
Warnings and errors are passed through exactly as ZATCA issued them.
One account, many companies
Each client company and device has its own registration under your account.
Sandbox matches production
Go live with a live key and a production device. Request and response shapes stay the same.
The full field-by-field reference is in your account under Developers, API reference.
Send your first invoice to the sandbox today.
Create an account, register a test device and watch ZATCA's response come back. Move to production when you are ready.
