Partner API Reference

Introduction

The Partner API is organized around REST. It has two surfaces, both authenticated by your single partner key:

All requests and responses are JSON, UTF-8. Send Arabic content as-is — names and addresses end up inside signed XML documents, exactly as you provide them. A conceptual walkthrough in Arabic lives in the Partner Guide; the merchant-facing invoice API has its own page at /docs/api.

Authentication

Authenticate every request with your partner key as a bearer token. Keys start with ztkp_live_, are shown once when generated, and can be rotated any time from the partner portal. Keep the key server-side — never ship it in an app or a browser.

curl https://zatcatools.com/api/partner/account \
  -H "Authorization: Bearer ztkp_live_..."

A missing or wrong key answers 401 unauthenticated. Using a merchant key (ztk_) here is called out explicitly — the error says it is a merchant key, so nobody debugs the wrong thing. A suspended partnership answers 403 partner_suspended.

Acting as a merchant

There are no per-merchant keys. Your one partner key acts for any of your merchants on the /api/v1 surface by naming the merchant in a header:

curl https://zatcatools.com/api/v1/account \
  -H "Authorization: Bearer ztkp_live_..." \
  -H "X-Merchant-Id: 34"

The Fatoora OTP

The constraint is only on the source of the code. Entering it happens inside your screens: show your merchant "enter the OTP from the Fatoora portal", pass what they type to connect, and poll status. The same rule applies to every branch device later: on the portal the merchant picks Onboard new solution unit/device, chooses how many codes to generate — one OTP per device — and each code is single-use and valid for one hour.

Errors

Errors use conventional HTTP status codes and one envelope. The code is stable and machine-readable; the message explains, and often names the exact fix.

{ "error": { "code": "seat_limit_reached", "message": "..." } }

Idempotency

Invoice and note creation accept an Idempotency-Key header (or an external_id field) — your order id is the natural choice. Retrying the same key returns the original document instead of creating a second one, so network timeouts are always safe to retry. Keys are namespaced per document kind: a refund can reuse its order's id.

Rate limits

/api/partner: 120 requests/minute. /api/v1: 60 requests/minute per key — enough for hundreds of tills in practice. Above that, write [email protected] and we raise it.

The merchant object

A merchant is a complete invoicing establishment with the Authority: its own certificate, its own invoice chain, unlimited issuing. Every merchant occupies one paid seat while active.

{
  "id": 34,
  "name": "مطعم البيك",
  "vat_number": "310122393500003",
  "email": "[email protected]",
  "status": "connected",          // awaiting_onboarding | trial | connected | failed | released
  "zatca_environment": "production",
  "certificate_expires_at": "2029-01-09",
  "invoices_issued": 1240,
  "seat": "active",               // active | released
  "created_at": "2026-09-01T09:24:32+03:00"
}

Your partner account

Your partnership at a glance — primarily the seat counters your billing screen needs.

{
  "partner": {
    "name": "Smart POS Co.",
    "status": "active",
    "seats": { "limit": 50, "used": 37, "remaining": 13 }
  }
}

Create a merchant

Creates the establishment and occupies one seat. The seat cap is enforced atomically — concurrent creates can never oversell your limit.

curl -X POST https://zatcatools.com/api/partner/merchants \
  -H "Authorization: Bearer ztkp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "مطعم البيك",
    "email": "[email protected]",
    "vat_number": "310122393500003",
    "short_address": "RRRD2929"
  }'

201
{
  "merchant": { "id": 34, "status": "awaiting_onboarding", ... },
  "onboarding_url": "https://zatcatools.com/partner/onboarding/34?...",
  "seats": { "limit": 50, "used": 38, "remaining": 12 }
}

List merchants

All your merchants (newest first), or one. Returns { "merchants": [ ... ] } / { "merchant": { ... } } of merchant objects.

Update a merchant

Completes or corrects establishment details before connecting. Send any subset of the create fields (plus subdivision). Sending a short_address re-resolves the full address from it. Identity fields — name, vat_number, cr_number — lock the moment the merchant connects (409 identity_locked): the certificate the Authority issues binds them. Address fields stay editable; shops move.

Connect to ZATCA

Onboards the merchant's establishment to Fatoora — CSR, certificate, the six compliance checks — from inside your screen. The one thing you collect from the merchant is the OTP. Completeness is checked before the single-use code is spent: missing fields answer merchant_incomplete with a missing array, costing nothing.

202
{ "status": "connecting", "message": "CSR → certificate → six compliance checks...", "poll": ".../status" }

already_connected and connect_in_progress (409) protect against double submits — a second OTP would be wasted while the first run may still succeed. The no-build alternative remains the onboarding link.

Connection status

What your checklist polls — typically settled in under two minutes.

{
  "zatca_status": "compliance_passed",  // pending | csr_generated | ccsid_issued | compliance_passed | connected | failed
  "connected": false,
  "connecting": true,
  "stalled": false,
  "compliance_passed": 4,               // of the 6 ZATCA compliance documents
  "error": null,                        // otp_invalid | compliance_failed | api_error | interrupted
  "certificate_expires_at": null
}

Onboarding link

A signed URL (valid 72 hours) that drops the merchant onto our onboarding page at exactly the step they're on — the zero-code alternative to building the connect screen yourself. Returns { "onboarding_url": "...", "expires_in_hours": 72 }.

Release & reinstate

A merchant left your platform? Release frees the seat for someone else — and deletes nothing: ZATCA mandates a six-year archive and an unbroken invoice chain, so the establishment, its documents and its owner's login all remain. Reads survive too: every GET endpoint keeps answering for a released merchant, so exports and audits never break — what the released seat blocks is acting anew (issuing, emailing, wiring devices), with 403 seat_released. Reinstate puts a returning merchant back on a free seat and the chain resumes where it left off.

Account & quota

The merchant's profile, connection state, quota (partner merchants: "unlimited": true) — and their branches with each branch's devices, which is where your POS screens read branch_id / device_id from.

{
  "name": "مطعم البيك", "vat_number": "310122393500003",
  "zatca": { "connected": true, "environment": "production", "certificate_expires_at": "2029-01-09" },
  "branches": [
    { "id": 3, "name": "فرع النخيل مول", "city": "الرياض", "connected": true,
      "devices": [ { "id": 7, "name": "كاشير 1", "status": "connected", "usable": true } ] }
  ],
  "quota": { "used": 0, "limit": null, "remaining": null, "unlimited": true }
}

Branches

All outlets live under the merchant's single VAT number; a branch stamps its own address and CR onto documents sold from it, while the legal name and VAT stay the establishment's. A branch cannot issue until one of its devices is connected.

201
{ "branch": { "id": 3, "name": "فرع النخيل مول", "cr_number": "1010777333", "devices": [] },
  "next": "Onboard the branch's device: POST /v1/branches/3/devices ..." }

Devices

A device is a ZATCA EGS unit: authorized by its own single-use Fatoora OTP, holding its own certificate and its own ICV/PIH invoice chain. One branch runs up to 10 — tills sign in parallel, each on its own chain. The establishment's head office needs none; its unit is the main onboarding itself.

Answers 202 immediately; onboarding completes in the background. Poll the device until connected — failed with otp_invalid means the code was wrong, spent or expired: have the merchant generate a fresh one and POST again.

{
  "device": {
    "id": 7, "branch_id": 3, "name": "كاشير 1",
    "status": "connected",       // pending | csr_generated | ccsid_issued | compliance_passed | connected | failed
    "connected": true, "connecting": false,
    "compliance_passed": 6, "error": null,
    "usable": true,              // can it sign the establishment's documents right now
    "trial": false, "certificate_expires_at": "2029-01-09"
  }
}

Re-onboards an existing unit with a fresh OTP — a failed run, or a trial-era device after the establishment graduated. Same body and 202-then-poll flow as creating one; a run already in flight answers 409 connect_in_progress. On success the unit signs with a fresh certificate and its chain restarts at ICV 1.

Retires a unit. Its issued documents survive untouched; the merchant can revoke the CSID from the Fatoora portal's device list.

Create an invoice

Builds, signs and submits the document to ZATCA synchronously — the response already carries the verdict. Simplified (B2C) invoices are reported; standard (B2B) are cleared.

curl -X POST https://zatcatools.com/api/v1/invoices \
  -H "Authorization: Bearer ztkp_live_..." \
  -H "X-Merchant-Id: 34" \
  -H "Idempotency-Key: order-18821" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "simplified",
    "branch_id": 3,
    "device_id": 7,
    "prices_include_vat": true,
    "lines": [
      { "name": "وجبة مشاوي", "quantity": 2, "unit_price": 57.50 },
      { "name": "دواء", "quantity": 1, "unit_price": 80,
        "tax_category": "Z", "tax_reason_code": "VATEX-SA-35" }
    ]
  }'

201
{
  "uuid": "8ac37285-...", "number": "INV-2026-00184",
  "kind": "invoice", "type": "simplified",
  "status": "accepted",            // accepted | warnings | rejected
  "issue_date": "2026-09-01",
  "totals": { "lines": "180.00", "discount": "0.00", "vat": "15.00", "grand": "195.00", "currency": "SAR" },
  "zatca": { "channel": "reporting", "icv": 42, "submitted_at": "...", "warnings": [] },
  "links": { "view": "...", "xml": "...", "pdf": "...", "qr": "..." }
}

links.view is the one URL safe to put in front of a human — it carries its own per-invoice token. The xml/pdf/qr links need the API key and are for server-to-server use.

List & retrieve invoices

Query parameters: kind (invoice default · credit · debit · all), status, type, since (ISO timestamp — compared against created_at, so pollers never miss a backdated document), per_page (max 100). Feed the newest created_at back as since to poll incrementally.

XML, PDF, QR & email

Credit & debit notes

An issued invoice can never be edited or deleted — refunds and corrections are notes against it. A note automatically follows its origin's branch; name the signing till with an optional device_id, or the branch's most idle device signs.

curl -X POST https://zatcatools.com/api/v1/notes \
  -H "Authorization: Bearer ztkp_live_..." \
  -H "X-Merchant-Id: 34" \
  -d '{ "invoice_uuid": "8ac37285-...", "kind": "credit",
        "reason": "إرجاع", "full": true }'