API reference¶
The spec is the authority¶
GET /api/integrations/openapi.json the OpenAPI document
GET /api/integrations/docs a browsable version
Both are public — no key needed to read them — and both are generated from the running code, so they cannot drift from what the API actually does. Point your client generator at the JSON.
This page lists the same surface in prose. Where the two disagree, the spec is right.
What a key can call¶
21 paths, 27 operations. The Role column is the least privilege that works.
Invoices¶
| Method | Path | Role |
|---|---|---|
GET |
/api/invoices/ |
ViewInvoice |
POST |
/api/invoices/ |
CreateInvoice |
POST |
/api/invoices/preview/ |
ViewInvoice |
GET |
/api/invoices/{invoice_id}/ |
ViewInvoice |
PATCH |
/api/invoices/{invoice_id}/clearance-reporting/ |
CreateInvoice |
GET |
/api/invoices/{invoice_id}/pdf-a3/ |
ViewInvoice |
POST |
/api/invoices/{invoice_id}/pdf-a3/ |
ViewInvoice |
PATCH …/clearance-reporting/ resubmits an invoice ZATCA rejected, after you have fixed it.
Credit and debit notes¶
| Method | Path | Role |
|---|---|---|
GET |
/api/invoices/{invoice_id}/notes/ |
ViewInvoice |
POST |
/api/invoices/{invoice_id}/notes/ |
CreateInvoice |
Notes hang off the invoice they correct. There is no standalone note endpoint — a note without an original would be meaningless.
Clients¶
| Method | Path | Role |
|---|---|---|
GET |
/api/buyers/ |
ViewInvoice |
GET |
/api/buyers/{buyer_id}/ |
ViewInvoice |
PATCH |
/api/buyers/{buyer_id}/ |
CreateInvoice |
POST |
/api/onboarding/organizations/clients/ |
CreateInvoice |
Creating a client uses the onboarding path, not POST /api/buyers/.
Items¶
| Method | Path | Role |
|---|---|---|
GET |
/api/items/ |
ViewInvoice |
POST |
/api/items/ |
CreateInvoice |
GET |
/api/items/{item_id}/ |
ViewInvoice |
PATCH |
/api/items/{item_id}/ |
CreateInvoice |
Devices and usage¶
| Method | Path | Role |
|---|---|---|
GET |
/api/devices/ |
ViewInvoice |
GET |
/api/usage/current/ |
any |
Reference data¶
Eight GET endpoints, any authenticated key — see Reference data.
What a key deliberately cannot do¶
No deletes. DELETE on invoices, items and clients exists in the product but is Admin-only and off the key surface. A leaked key cannot destroy records.
No administration. Users, roles, branches, devices, billing and API keys themselves are all Admin-only. A key cannot create another key.
No webhooks. There is no callback registration. Poll — see Quickstart.
Conventions¶
- Base URL — your gateway host including the version segment. It comes with your key.
- Auth —
Authorization: Bearer clix_…on every request. - Ids — UUIDs in paths.
- Async creation —
POST /api/invoices/returns202and alocationto poll. - Errors —
400for validation, never422. Bothmessageanddetailappear; see Errors.
Multiple organisations¶
If a key's identity reaches more than one organisation you get 409 with code: org_context_required. Send the organisation in X-Active-Org. A key is normally bound to one organisation and you will not meet this.