Sign in Get started
For developers

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.

Base URLhttps://api.fatooraconnect.com/v1
Quick start

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.

POST /v1/devices

    
Reference

ZATCA e‑invoicing API endpoints

Two calls do the work. The rest let you look things up later.

POST/v1/devices

Register a device or branch with ZATCA using an OTP.

GET/v1/devices

List your registered devices.

GET/v1/devices/{device_id}

Check one device's status and how many invoices it has sent.

POST/v1/invoices

Submit a tax invoice for clearance or reporting.

POST/v1/credit-notes

Submit a credit note against an accepted invoice.

POST/v1/debit-notes

Submit a debit note against an accepted invoice.

GET/v1/invoices/{number}

Fetch an invoice with its current ZATCA status.

GET/v1/invoices/{number}/xml

Download the signed UBL 2.1 XML.

GET/v1/wallet

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.

Headers
Authorization: Bearer ff_test_••••
Content-Type: application/json
Accept: application/json

Handling 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.

422Rejected
{
  "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."
    }]
  }
}
Statuses

ZATCA invoice statuses and response codes

CLEARED200

Standard invoice approved by ZATCA. Safe to send to the buyer.

REPORTED200

Simplified invoice accepted by ZATCA's reporting service.

REJECTED422

ZATCA refused it. Reasons are in zatca.errors. Correct and resubmit. Nothing is charged.

FAILED503

ZATCA could not be reached. Nothing is charged. Retry with the same number.

402 / 4014xx

Wallet balance too low (402), or the API key is missing, wrong or revoked (401).

429429

Rate limit reached. Wait for the Retry-After seconds, then retry.

Built for integrators

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.