Flow & integration patterns

This page explains how authentication, API keys, EGS units, and invoices work together, and the two main ways to integrate: one key with explicit EGS unit or key linked to a default EGS unit. Both are supported so you can choose what fits your app.

High-level request flow

Every invoice (and EGS) request is authenticated with an API key. The key determines sandbox or production. The EGS unit used for the invoice must belong to the same environment as the key.

If the diagram does not load, paste the code into mermaid.live.

Two ways to specify the EGS unit

Pattern A: One API key, send `egs_unit_id` in every request

Best if you have one key (e.g. one integration) and multiple EGS units (branches, POS devices). You always send egs_unit_id in the invoice body. No need to set a default on the key. Simple and explicit.

Create one API key (sandbox or production).
Create one or more EGS units in the dashboard (same environment as the key).
In every POST /v1/invoices/simplified (and standard/credit/debit), include egs_unit_id in the JSON body.

Pattern B: API key with a default EGS unit (omit `egs_unit_id`)

Best if each key represents one context (e.g. one POS or one branch). Set a default EGS unit on the key in the dashboard; then you can omit egs_unit_id in invoice requests and the default unit is used automatically.

Create an API key and, in the dashboard, set its "Default EGS unit" to the unit that key should use.
When calling invoice APIs, do not send egs_unit_id in the body.
You can still override by sending egs_unit_id when needed; the unit must match the key environment (sandbox key → sandbox unit, production key → production unit).

Mixing patterns

You can use both: some keys with a default unit (simpler requests), some without (always send egs_unit_id). If you omit egs_unit_id and the key has no default, the API returns EGS_UNIT_REQUIRED with a message to set a default or send the field.

Sandbox vs production (end-to-end)

Sandbox and production are strictly separated. EGS units and invoice submissions always use the correct ZATCA gateway based on the unit's environment (which is set when the unit is created, from your account type).

Sandbox key → only sandbox EGS units; production key → only production EGS units. You cannot use a sandbox unit with a production key or vice versa.

Typical integration sequence

Sign up (dashboard or POST /v1/onboard) and get your first API key.
Create one or more EGS units (POST /v1/egs) with an OTP for ZATCA onboarding; poll status until onboarding_status: active.
Optionally create more API keys and set a default EGS unit per key in the dashboard.
Submit invoices: POST /v1/invoices/simplified or /standard with Authorization: Bearer YOUR_API_KEY. Include egs_unit_id or rely on the key's default.
Use the returned pdf_url and signed_xml_url to fetch documents with the same API key.