Send an invoice

post
https://api.wafeq.com/ae/v1/invoices

Send an invoice to the buyer, and report it to the FTA.

Wafeq checks the invoice against the UAE e-invoicing rules (PINT-AE), picks its
document type (380 tax invoice or 480 commercial invoice) and looks the buyer up
on Peppol. If the buyer is registered there, Wafeq delivers the invoice to the
buyer's e-invoicing provider. If it isn't, the invoice is reported to the FTA
only, addressed to an FTA placeholder address, where the rules allow it. Either
way, Wafeq reports the invoice to the FTA. In Sandbox, delivery is simulated and
nothing is reported.

The seller is always the taxpayer, taken from its registered profile: you never
send it. For a credit note, use POST /credit-notes. To check an invoice
without sending it, send the same body to POST /invoices/validate.

Send an Idempotency-Key so you can retry safely, and branch on status in the
answer. Live mode needs an active subscription for your organization: without
one you get 402 (subscription_required). If Wafeq can't confirm the billing
status just then, you get 503 (billing_status_unavailable): try again shortly.
Sandbox needs no subscription.

Body Params

An invoice. Wafeq files it as a tax invoice (380), or as a commercial invoice (480) when it's
outside the scope of VAT or exempt: the seller has no TRN, or every line, document discount and charge is exempt (E)
or out of scope (O). Zero-rated (Z) supplies never use 480.
The seller is the taxpayer, from its registered profile; you send the buyer in customer.

preceding_invoicesarray of objectslength ≤ 100

Preceding invoices, including each already-invoiced advance settled by this final invoice. Supply their invoice numbers and, when known, issue dates. References do not change amounts or look up stored documents. For already-invoiced advances, supply the remaining net amounts on each final line, with its original VAT treatment; do not deduct the advances again. The 100-reference limit is an API capacity limit.

string | null

Only to correct a document the buyer's e-invoicing provider rejected as invalid (delivery_status rejected, with reason BV or SV): that document's document_id. Wafeq takes care of the rejected document's report to the FTA, withdrawing it where needed. Send the corrected document in full to the same endpoint, with the same number, and a new Idempotency-Key; it must be filed as the same document type. A correction is always queued (202). If Wafeq is still handling the rejected document's report, you get 409 correction_not_ready: send the same request again later, with the same key. A correction is a new document and must satisfy current issuance rules: an older 480/81 with zero-rated (Z) supplies cannot be corrected into another commercial document.

metadataobject

Your own string key-value pairs: up to 100 keys, 100 characters per key, 16 KiB in total. Kept apart from the e-invoice and never sent to Peppol or the FTA.

string | null

Issue date, YYYY-MM-DD. Defaults to today.

stringlength ≤ 64Defaults to pint:billing-1@ae-1

The Peppol profile the document is sent under. Leave the default.

stringDefaults to ALWAYS_SEND

Whether the buyer's e-invoicing provider sends a delivery confirmation for every document (ALWAYS_SEND, the default and recommended) or only when it rejects one (FAILURE_ONLY).

stringlength between 3 and 3Defaults to AED

Currency of the amounts, as an ISO 4217 code. Defaults to AED. Other currencies require currency_exchange_rate.

currency_exchange_rate

AED per one unit of document currency. A finite positive decimal with at most 6 decimal places, required when currency is not AED; ignored for AED documents. For example, 3.6725 means 1 USD = 3.6725 AED on a USD document. Wafeq multiplies the published document-currency VAT and total including VAT by this rate, then rounds each AED amount to 2 decimal places, half up. Send a decimal string to retain the rate's exact precision.

Any of
number≥ 0
stringenumDefaults to TAX_EXCLUSIVE

Whether unit prices and all discount/charge amounts and percentage bases exclude VAT (TAX_EXCLUSIVE, the default) or include it (TAX_INCLUSIVE). With TAX_INCLUSIVE, Wafeq e-invoicing ASP converts these inputs to amounts before VAT, then calculates VAT and totals as usual, and makes the amount due what you charge. Line quotes include any separate discounts and charges and are rounded to 2 decimal places, half up, then document adjustments are applied. Line adjustments use the line's VAT rate; document adjustments use their own rate. Any difference from the total including VAT appears on the e-invoice as a rounding amount. For example, one line of 0.10 including 5% VAT has an amount before VAT of 0.10 and VAT of 0.01, so the total including VAT is 0.11 and the amount due is 0.10. The e-invoice always shows prices and amounts before VAT.

Allowed:
string | null

The buyer's reference for the purchase, e.g. its purchase order number.

string | null

Your own ID for this document, e.g. the invoice's ID in your system. Wafeq stores it and sends it back in every document.* webhook, so you can match events to your records.

string | null

A free-text note on the document.

stringDefaults to 00000000

Special scenarios that apply to the sale, as 8 flags. Each position is one scenario, left to right: free zone, deemed supply (goods or services given away or used privately, which VAT treats as a sale), margin scheme (second-hand goods taxed only on the seller's margin), summary invoice (one invoice for several supplies over a period), continuous supply, disclosed agent billing, e-commerce, export. 1 means the scenario applies, 0 that it doesn't; several can apply at once. The default 00000000 means none; 00000001 is an export. A summary invoice needs invoice_period; an export or an e-commerce sale needs delivery_address. Free zone requires beneficiary, disclosed agent billing requires principal, and margin scheme requires category N at tax_percent: 5 on every line, with no VAT added.

invoice_periodobject

The period the document covers. Required on a summary invoice (the 4th flag of transaction_type_code).

beneficiaryobject

The beneficiary of the supply. Required only when the free-zone transaction flag (position 1) is set; refused without that flag. The beneficiary may be the buyer.

principalobject

The principal the seller acts for. Required only when the disclosed-agent-billing transaction flag (position 6) is set; refused without that flag. Its TRN must differ from the seller's TRN.

line_itemsarray of objectsrequiredlength between 1 and 1000

The document's lines: 1 to 1000. The maximum is an API capacity limit, not a UAE regulatory limit.

discountsarray of objectslength ≤ 100

Discounts on the whole document, after line discounts. Amounts and bases follow tax_amount_type. Give each entry its VAT category and rate.

chargesarray of objectslength ≤ 100

Charges on the whole document, after line charges. Amounts and bases follow tax_amount_type. Give each entry its VAT category and rate.

customerobjectrequired

The buyer.

delivery_addressobject

Where the goods or services are actually delivered. Required for an export (services included), where it must be outside the UAE, and for an e-commerce sale. Wafeq never copies it from the buyer's address.

stringrequiredlength ≤ 64

Your invoice number. Unique among the taxpayer's documents: a number already sent is refused (duplicate_number).

stringrequiredlength ≤ 10

Payment due date, YYYY-MM-DD.

payment_meansobject
string | nullenum

The type the invoice must be filed as: 380 tax invoice or 480 commercial invoice (outside the scope of VAT). Optional: leave it out and Wafeq e-invoicing ASP picks the type. A supplied type is never switched. A type incompatible with the seller or supplies is refused with 422 (document_type_mismatch), e.g. a 380 from a seller without a TRN. 480 requires every line, document discount and charge to be exempt (E) or out of scope (O); zero-rated (Z) supplies cannot use it. Without this field, such an invoice is filed as 480. A 380 whose lines are all E or O fails official validation (SCH:ibr-151-ae).

Allowed:
Headers
string | null

Makes the send safe to repeat: send the same body with the same key again and you get the first answer back, and nothing is sent twice. Use one key per version of the document; a changed body needs a new key. Required for a document reported to the FTA only, for queued delivery (Prefer: respond-async) and with corrects_document_id, so send one every time. Keys are scoped to the taxpayer and your organization, and never expire.

string | nullenum

respond-async asks for queued delivery: Wafeq accepts the document and answers 202 straight away, then delivers it in the background. Needs Idempotency-Key. Without it, the call waits until the delivery to the buyer's provider has finished.

Allowed:
string | null
stringrequired

Taxpayer ID (txpay_…). Required with an organization API key (pk_…) for this taxpayer-specific operation, even for one taxpayer. Not a TIN. Optional with a taxpayer access token, which already names its taxpayer.

string | null

Grant ID (tgr_…) to act through, with an organization API key. The request then has exactly that grant's scopes and fails once the grant is revoked. Without it, the key acts through all of the organization's active grants on the taxpayer.

Response