Send Invoice

post

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

Send an invoice through the Peppol network.

Converts the JSON invoice to UBL XML, wraps it in an SBDH, validates it,
performs SMP lookup, and sends it via AS4. The supplier defaults to your
registered profile when omitted (LL-1468). For credit notes use
POST /credit-notes.

Live mode requires an active subscription for the taxpayer’s organization.
Returns HTTP 402 with detail.code=subscription_required when absent or
inactive, or HTTP 503 with detail.code=billing_status_unavailable when
billing status is stale. Sandbox does not require a subscription.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Request body for POST /invoices — a commercial invoice (UBL 380).

You are the supplier (from your registered profile); provide the customer.

corrects_document_id

string | null

AP document_id of a C3-rejected document this submission corrects. Keep its business number/type and supply corrected content. Requires a new Idempotency-Key and uses queued delivery. The AP handles FTA recovery internally; retry the same request/key if recovery is pending.

metadata

object

Customer-defined string key-value pairs (up to 100 keys, 100 characters per key, 16 KiB total). Stored separately from the fiscal document; never sent to Peppol or the FTA.

issue_date

string | null

Issue date YYYY-MM-DD (defaults to today)

profile

string

length ≤ 64

^pint:(billing|selfbilling)-1(@ae-1)?\*?$

Defaults to pint:billing-1@ae-1

PINT profile used for the Peppol DocTypeID + SMP lookup. Default is the UAE profile (real counterparties). Override for conformance, e.g. 'pint:billing-1*' to reach a testbed receiver.

mls_type

string

^(ALWAYS_SEND|FAILURE_ONLY)$

Defaults to ALWAYS_SEND

eDEC Message Level Status preference: ALWAYS_SEND (MLS for every message — recommended for tax-invoice confirmation/audit) or FAILURE_ONLY (MLS only on rejection).

currency

string

length between 3 and 3

Defaults to AED

ISO 4217 currency code

buyer_reference

string | null

Buyer's purchase order reference

source_id

string | null

The caller's own id for this document (e.g. your invoice id). Stored on the AP record and echoed back in every document.* webhook so you can correlate callbacks to your own document.

notes

string | null

Free-text note

transaction_type_code

string

^[01]{8}$

Defaults to 00000000

§10.4 invoice transaction-type code (BTAE-02): 8 flags, one per scenario, left→right — Free zone, Deemed supply, Margin scheme, Summary invoice, Continuous supply, Disclosed agent billing, E-commerce, Exports. '1' = applies (multiple allowed). '00000000' = no special scenario.

invoice_period

object

Invoicing period (IBG-14) covered by the document. Required when the summary-invoice transaction flag is set.

line_items

array of objects

required

length between 1 and 1000

Line Items*

customer

object

required

The buyer (counterparty)

delivery_address

object

Actual delivery location; required for exports, including services. Never inferred from buyer address.

invoice_number

string

required

length ≤ 64

Your invoice number

due_date

string

required

length ≤ 10

Due date YYYY-MM-DD

payment_means

object

Headers

Idempotency-Key

string | null

^[\x21-\x7e]+$

Optional taxpayer-scoped submission key. Repeat the same key and payload to replay the saved response without resending. Required with corrects_document_id or queued delivery. Changed payloads and unfinished attempts return 409. Keys have no automatic expiry.

Prefer

string | null

enum

Set respond-async with Idempotency-Key to request durable queued delivery. Requires server enablement.

Allowed:

authorization

string | null

x-ae-taxpayer-id

string

required

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.

x-ae-grant-id

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.

Responses

409

Idempotency conflict, correction recovery pending, or the earlier submission is in progress/unconfirmed. Retry the same payload/key.

503

Billing/authentication is temporarily unavailable, or the idempotency reservation/response could not be persisted. Retry with the same Idempotency-Key and, for portal service authentication, a fresh token.

200Successful Response

202Durably queued. Location identifies the current delivery status; success means accepted, not delivered.

402Live document processing requires an active subscription. Sandbox is exempt.

422Validation Error