Esnad
DashboardGet API key

Quickstart

Create the company and API key in the dashboard, onboard an EGS unit with the API, then submit invoices. Sandbox and production stay separated by key prefix and EGS environment.

What the API does vs the dashboard

  • Dashboard only — create companies (legal entities), create/revoke API keys, billing, team, webhooks UI.
  • API (API key) — EGS onboarding, invoice submit/list/download, reference data, GET /v1/auth/context.

Path to first invoice

  1. In the dashboard, complete the company profile and create a zatca_test_ API key (shown once — store it).
  2. Create an EGS unit: POST /v1/egs with sandbox OTP 123345. Poll until onboarding_status: active.
  3. Submit a simplified invoice: POST /v1/invoices/simplified with egs_unit_id and Authorization: Bearer ….

Prefer a ready-made walkthrough? Import the API collection.

Request flow

Every EGS and invoice call uses an API key. The key selects sandbox or production; the egs_unit_id in the body must match that environment.

Company, API key, and EGS

A company (legal entity) is one VAT / CR. An API key authenticates that company. An EGS unit is a branch or POS with its own ZATCA certificate and invoice chain. The key does not pick the branch — each invoice must send egs_unit_id.

  • One API key per app or environment (sandbox vs live).
  • One EGS unit per branch or POS (same environment as the key).
  • Missing egs_unit_id → EGS_UNIT_REQUIRED.

Multiple companies (different VATs)

Business, Studio, and Platform plans can hold several legal entities under one organization. Each entity has its own keys, EGS units, and PIH chain. Billing quotas are pooled at the organization.

  1. In the dashboard, open Companies and add the legal entity (VAT, CR, address).
  2. Switch to that company, then create its API key under API Keys.
  3. Use that key for POST /v1/egs and invoices for that VAT only.

Details: Multiple companies.

Sandbox vs production

Never mix environments: sandbox key only with sandbox EGS; live key only with production EGS. Production EGS and live keys also require a complete company profile (VAT, CR, Saudi address).

After your first submit

  • HTTP 200 — Fatoora finished inline. Still read zatca_warnings.
  • HTTP 202 — queued; poll GET /v1/invoices/:id or use webhooks.
  • B2B: do not send the invoice to the buyer until status is cleared.

See Responses and Errors.