انتقل إلى المحتوى

لم تُترجم هذه الصفحة بعد

تعرض هذه الصفحة النص الإنجليزي حتى تصدر ترجمتها.

Changelog

Changes that affect integrators. The current API version is 1.3.0, reported in the info.version field of the spec.

How to watch for changes

The machine-readable spec at /api/integrations/openapi.json is generated from the running code, so diffing it between deploys is the most reliable signal. This page records the changes worth a human explanation.

2026.09

Each entry names the backend release that carried it.

issue_date and issue_time are in Riyadh time. Release 0.108.9, 2026-09-29. The server stamps both on every invoice, credit note and debit note, in Asia/Riyadh. Before this release it used UTC, so a document issued between 00:00 and 03:00 Riyadh carried the previous day's date in its XML and QR code. This applies to preview, draft and create alike.

issue_date and issue_time are optional again. Release 0.108.8, 2026-09-28. The server sets both from its own clock and ignores any value you send. Releases 0.108.6 and 0.108.7 demanded them anyway: a create, preview or draft without them was refused with 400 and Missing required fields: issue_date, issue_time. If you added the fields to get past that error, you may leave them in; they are ignored.

The spec's error and metering text is corrected. Release 0.108.7, 2026-09-28. The description at /api/integrations/docs listed 422 as the validation status and said calls count against a monthly limit. Neither was true. It now says validation failures are 400 and that individual calls are not metered.

The spec's required lists match what the server refuses. Release 0.108.6, 2026-09-27. On POST /api/invoices/ and POST /api/invoices/preview/, type_code, transaction_code, exchange_rate and document_level_allowances are now published as required. The server already refused a body without them, but the spec showed defaults (388 and 0100000) for the first two. exchange_rate and document_level_allowances no longer accept null. On client creation, industry is now published as required.

Typeaheads accept q. Releases 0.108.1 and 0.108.3, 2026-09-24. The …/autocomplete/ endpoints take q as the search parameter. The old name, query, is still accepted. None of these endpoints is in the integration spec; list endpoints such as GET /api/buyers/ still take search_text.

GET /api/invoices/ filters on several statuses at once. Release 0.105.2, 2026-09-20. invoice_status takes a comma-separated list, for example invoice_status=CLEARED,REPORTED. An unknown status is refused with 400 naming it.

API calls are no longer metered against a monthly quota. Release 0.99.0, 2026-09-13. api_calls_used and api_calls_limit in GET /api/usage/current/ are now permanently 0, kept so existing clients keep parsing. If you displayed "API calls remaining" from those fields, it now reads zero of zero; read invoices_used / invoices_limit instead. Write operations are instead governed by a fair-use guard that returns 403 with code: fair_use_limit. See Usage and quotas.

GET /api/devices/ joins the spec, and 429 carries Retry-After. Release 0.98.0, 2026-09-10. One read of /api/devices/ gives both the device and the seller an invoice needs. A rate-limited call now answers 429 with Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.

A curated integration spec. Release 0.96.0, 2026-09-09. /api/integrations/openapi.json and /api/integrations/docs publish only the surface an API key can actually call: 21 paths since 0.98.0. The older /api/openapi.json shows the whole internal API including endpoints no key may use; it is not the integrator reference.

Standing behaviours worth knowing

These are not new, but they surprise people often enough to state:

  • Validation errors are 400, not 422. The body is {"message": [ … ]} with an array.
  • Invoice creation is asynchronous. POST /api/invoices/ returns 202 and a location to poll. The task_id is informational; there is no task endpoint.
  • Identical invoice payloads are refused for five minutes with a 400. Poll before retrying a timed-out create.
  • There are no outbound webhooks. Polling is the supported pattern.
  • Reference data returns objects keyed by enum name, not arrays.
  • Revocation is immediate. No cache sits in front of key resolution.

Deprecations

What Status Do this
query on typeahead endpoints Still accepted as of 0.108.11; to be removed Use q
api_calls_used / api_calls_limit Frozen at 0, retained for compatibility Use the invoice counters