Outgoing invoices

The invoice object

POST /invoices takes { invoices: [...] } with up to 100 inputs. Each input describes one document:

Totals are computed server-side with the same rounding as the editor: line net = quantity × unit price rounded to 2 decimals; VAT per category on (lines − allowances + charges); document total = taxable + VAT.

Validation

Every invoice is validated against PINT AE before it is stored. Blocking errors (severity error) reject the element with E_VALIDATION, unless draftOnly is set; warnings are stored with the invoice.

{
  "code": "E_VALIDATION", "statusCode": 400,
  "message": "The invoice does not pass PINT AE validation",
  "extra": {
    "errors": [{ "field": "seller_trn", "rule": "BT-31", "message": "Seller TRN is required (set in Organization Settings)", "severity": "error" }],
    "warnings": [{ "field": "due_date", "rule": "BT-9", "message": "Due date is recommended", "severity": "warning" }]
  }
}

Seller data (BT-27 to BT-43, the trade licence and its licensing authority) comes from the organization profile, not from the payload. IBANs are checked for length, structure and check digits (rule IBAN); a plain account number that is not an IBAN is accepted. The PINT AE field reference lists every business term, its UBL path and the API field that carries it.

GET /invoices/{id}/validation re-runs the checks; POST /invoices/{id}/validate also moves a draft to validated.

Document kind and transaction type rules

The web editor greys these out before you can pick them; the API accepts the input, runs the same validation and stores the invoice as a draft with the finding, so a client sees the rule number in validation.errors rather than a 4xx.

Other currencies

A document in another currency than AED needs an exchange rate (validation rule IBR-159-AE; at most 6 decimals, IBR-002-AE; a USD rate more than 1 % away from the 3.6725 peg gives a warning). Send exchangeRate to use your own, or leave it out and Alya Books fills in the UAE Central Bank rate "for VAT related obligations" for the date of supply: taxPointDate, else deliveryDate, else issueDate. The Central Bank publishes on working days around 18:00 UAE time; on weekends, holidays and before publication the last earlier rate is used. The response says which: exchangeRateSource is cbuae (with exchangeRateDate, the publication date) or manual. When the Central Bank has no rate for the currency the invoice fails IBR-159-AE, or stays a draft with draftOnly. All amounts in the payload and the response stay in the document currency. Alya Books adds the AED figures the UAE specification asks for:

AED amounts are the document amounts × rate, rounded to 2 decimals. GET /invoices/{id} returns them as aedTotals: { currency, rate, taxTotal, total } (null for AED documents). The rate is stored on the invoice, so issued invoices never change when later rates are published.

Batches and partial failure

Elements succeed or fail independently. When all succeed the response is 202 with an array. When any element fails, the status mirrors the first failure (usually 400) and extra.results holds one entry per element:

{
  "code": "E_VALIDATION", "statusCode": 400, "message": "…",
  "extra": { "results": [
    { "index": 0, "success": true, "invoiceId": "…", "invoiceNumber": "INV-0042" },
    { "index": 1, "success": false, "code": "E_VALIDATION", "statusCode": 400, "message": "…", "field": "invoiceNumber" }
  ] }
}

Submission and delivery

• submit: true on creation, or POST /invoices/{id}/submit, hands a validated invoice to the ASP. The response carries the ASP request id and the first status; the invoice becomes submitted and is locked.
• send: { to, cc, bcc, subject, message } on creation, or POST /invoices/{id}/send, emails the PDF and (for tax documents) the XML. state is sent, skipped (no email provider configured on the environment) or failed.
• reviewMode: true creates the invoice with reviewStatus: pending; an approver must approve it in the app before it can be submitted.

The ASP and FTA lifecycle page explains the stages and the authority[] entries in GET /invoices/{id}/status.

After issue

Issued invoices (submitted and later) are immutable. What you can still do:

Drafts and validated invoices can be replaced entirely with PUT /invoices/{id} or deleted with DELETE /invoices/{id}.

Listing and search

GET /invoices supports keyword (number, buyer, TRN, order reference), invoiceNumber, status, paymentStatus (comma-separated: unpaid, partially_paid, paid, overpaid, nothing_due; the last is a deemed supply, which has no payment), documentKind, buyerId, startIssueDate / endIssueDate, startDate / endDate (creation), includeArchived, isTest, externalId, sort (issueDate, createdAt, invoiceNumber, dueDate, total) and order. Test keys only see test documents unless isTest=false is passed explicitly.