Concepts

Conventions

Names, amounts, dates and identifiers, the same on every route.

JSON

• Bodies are JSON, fields in camelCase, and enums by their names ("emirate": "DUBAI").
• A field you leave out of an update keeps what it holds.

Amounts and VAT

• Every amount is a JSON number in AED. KWN records nothing in another currency.
• Unit prices are VAT-exclusive. A VAT rate is a percentage: 5 (standard) or 0 (zero-rated).
• Totals are rounded to two decimal places, line by line, as the tax invoice prints them. Send expectedTotal to have an e-invoice refused rather than cleared if it does not add up to yours.

Dates

• A calendar day is YYYY-MM-DD, read as a day in the UAE.
• Instants such as createdAt and updatedSince are UTC, in ISO 8601.

Your own ids: externalId

Records you create may carry your system’s id as externalId: 1 to 100 visible ASCII characters, unique per company and kind of record, and kept for good. Find a record by it with ?externalId=. A second record with the same one is refused 409 EXTERNAL_ID_TAKEN. On POST /einvoices it is required: it is how a repeat is recognised.

Actions are safe to repeat

An action on an existing document — confirm, approve, issue, post, cancel — answers { "alreadyDone": …, "document": … }. Sent again, it does nothing twice and answers alreadyDone: true.