Required fields when creating invoices through the API
The minimum payload for POST /invoices, what Alya Books fills in for you, and what PINT AE still needs.
POST /invoices accepts one invoice or a batch under invoices. Alya Books validates the payload, then runs the full PINT AE check before the invoice leaves draft. The list below separates what the request must contain from what must be set up once in the app.
Required in the request
| Field | Rule |
|---|---|
buyer.name or buyer.id | A buyer name, or the id of an existing contact |
items | At least one line, at most 500 |
items[].description | Text, up to 1000 characters |
items[].quantity | Number |
items[].unitPrice | Net price |
Everything else has a default: issueDate is today, currency is AED, invoiceTypeCode is 380 (tax invoice), taxCategory is standard with 5 %, language is en. dueDate is derived from payment.termsDays when given. If buyer.trn is sent it must be 15 digits.
Required by PINT AE
These come from your organization settings and are checked on every invoice:
- Seller name, TRN (15 digits), street, city and country under Settings → Profile and Tax & currency (BT-27, BT-31, BT-35, BT-37, BT-40).
- For credit and debit notes:
precedingInvoice.number(BT-25). - A due date whenever an amount is due (IBR-127-AE):
dueDate, orpayment.termsDaysto calculate it. Credit notes and fully prepaid invoices (prepaidAmountequal to the total) may leave it out. - Custom fields marked required in the active template for the document kind, sent as
metadata: { key: value }.
Missing seller data returns 400 E_VALIDATION with the business terms in extra.errors, and nothing is created. Add draftOnly: true to create a draft anyway and finish it in the app.
Recommended
Buyer TRN and email, payment means and IBAN (payment.accountId), and an order or buyer reference. They only raise warnings, but the FTA and your buyers expect them.
Example
{ "invoices": [{
"buyer": { "name": "Buyer LLC", "trn": "100000000000011" },
"issueDate": "2026-09-23",
"payment": { "termsDays": 30 },
"items": [{ "description": "Consulting, September", "quantity": 10, "unitPrice": 500 }],
"submit": true
}] }
Good to know
draftOnlycannot be combined withsubmitorsend.invoiceNumberis optional; the next number of the series is allocated. A number already in use fails withfield: invoiceNumber.- In a batch, elements with
success: truewere created even when the response status is400; retry only the failed ones. - Contacts are matched by id, then TRN, then name; unknown buyers are created.