BOOK A CALL
+971 58 560 3037
+971 58 560 3037
BOOK A CALL
LEARN MORE

Dubai-based founder scaling HoReCa technology across 15+ countries

LEONID DOVBENKO

Article by

UAE E-INCOICING · DEVELOPER GUIDE

API-First E-Invoicing in the UAE

A developer-oriented guide to integrating UAE e-invoicing over an API. Covers authentication, the endpoints a compliant integration needs, request and response structures, webhook design, idempotency, error handling, sandbox testing, and what to look for in provider documentation before you commit.
reading time: 14 min
SOURCES: MOF, FTA OFFICIAL PUBLICATIONS
august 2026

aiverix research

UAE e-invoicing is fundamentally a systems integration problem. The regulation defines a structured document format, a transmission network, and a real-time reporting obligation to the tax authority — none of which a business handles directly. All of it is mediated through an accredited provider, and for teams building or maintaining their own billing systems, that mediation happens over an API. How well that API is designed determines how much of your engineering time this consumes, both during implementation and for years afterwards.
“
OFFICIAL SOURCES:

UAE Electronic Invoicing Guidelines V1.0 — Ministry of Finance, 23 February 2026
UAE Electronic Invoice Mandatory Fields V1.0 — Ministry of Finance, 23 February 2026
UAE Peppol 5-Corner E-Invoice Business and IT Impact Scope V1.0
Ministerial Decision No. 243 of 2025 · Ministerial Decision No. 244 of 2025

mof.gov.ae/eInvoicing
51
Mandatory fields the payload must satisfy
5
Corners in the UAE model — the API abstracts corners 2 to 5
3
Predefined fallback endpoints the API must route to automatically
8
Special transaction scenarios the payload must express

What API-First Means in This Context

An API-first e-invoicing provider treats the programmatic interface as the primary product surface rather than an afterthought bolted onto a web application. In practice this shows up in a handful of concrete ways: the API supports every operation available in the user interface, the documentation is complete enough to build against without a support call, a sandbox environment exists and behaves like production, and webhooks deliver state changes rather than requiring you to poll.

The distinction matters because e-invoicing is not a one-time integration. Regulations change, new transaction scenarios appear, invoice volumes grow, and your own billing logic evolves. An API you can reason about and extend is a modest ongoing cost. One you cannot is a recurring engineering tax.
WHAT THE API IS ACTUALLY ABSTRACTING

Behind a single invoice submission call, the provider performs field validation against all 51 mandatory requirements, transformation into PINT AE XML, application of a digital signature, a participant lookup to find the buyer’s network address, routing to the correct fallback endpoint if the buyer is not registered, transmission across the Peppol network, real-time reporting of tax data to the FTA, and compliant archival of the signed document. Your integration should not need to know about any of that — which is the point.

Six Principles of a Well-Designed Integration

  • PRINCIPLE 1

    Your document ID is the correlation key

    Every request should carry your own source document identifier, and every response and webhook should return it. Without this, correlating provider records back to your billing records becomes manual reconciliation.

  • PRINCIPLE 2

    Submission is not delivery

    A successful API response means the invoice was accepted for processing. Delivery to the buyer and confirmation from the FTA are later, asynchronous events. Model these as distinct states, not one boolean.

  • PRINCIPLE 3

    Assume retries will happen

    Network timeouts, deployment restarts and queue replays all cause duplicate submissions. Idempotency handling is not an edge case — design for it from the start rather than discovering duplicates in production.

  • PRINCIPLE 4

    Validation errors are data problems

    Most failures are not integration bugs. They are missing tax numbers, unmapped tax codes, absent network addresses. Route these to the people who own the data, not to your engineering backlog.

  • PRINCIPLE 5

    Prefer webhooks over polling

    At meaningful volume, polling for status across thousands of invoices is wasteful and slow. Webhooks deliver state changes as they happen and scale without additional request load.

  • PRINCIPLE 6

    Reconcile daily regardless

    Webhooks can be missed and requests can fail silently. A daily reconciliation confirming that every posted invoice has a terminal status catches the failures neither system reports on its own.

Authentication and Environments

Most e-invoicing APIs use OAuth 2.0 client credentials or long-lived API keys scoped to an environment. Because invoice data is commercially sensitive and the operations are legally consequential, expect and require credentials to be environment-specific, revocable, and scoped by permission.

Illustrative – Obtaining an Access Token

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=<client_id>
&client_secret=<client_secret>
&scope=invoices:write invoices:read
{
"access_token": "eyJhbGciOi...",
"token_type": "Bearer",
"expires_in": 3600
}
VERIFY SANDBOX FIDELITY EARLY

The most costly surprise in an API integration is discovering at go-live that sandbox validation was more permissive than production. Before building extensively against a sandbox, submit a deliberately invalid payload — a missing buyer tax number, an unmapped tax category — and confirm it is rejected with the same error you would receive in production. If the sandbox accepts it, treat sandbox results as indicative only and plan for a longer pre-production phase.

The Endpoints a Compliant Integration Needs

Endpoint naming varies by provider, but the functional surface required for a complete UAE integration is consistent. If a provider’s API is missing several of these, expect to compensate with manual processes.
THE TWO MOST COMMONLY MISSING ENDPOINTS

Dry-run validation and participant lookup are frequently absent, and both are disproportionately useful. Dry-run validation lets you run your entire historical customer base through the validator during data cleanup, producing a precise list of what needs fixing before go-live rather than discovering it invoice by invoice. Participant lookup lets you check programmatically which of your buyers are already registered, rather than emailing all of them. Ask about both specifically during evaluation.

Submitting an Invoice

The payload below is illustrative. It shows the structural elements a UAE-compliant submission must express — field names and nesting differ by provider.

Illustrative – Invoice Submission

POST /v1/invoices
Authorization: Bearer <token>
Idempotency-Key: 0090001234-v1
Content-Type: application/json

{
"sourceDocumentId": "INV-2026-004411",
"entityCode": "AE-MAINLAND-01",
"documentType": "INVOICE",
"issueDate": "2026-07-27",
"dueDate": "2026-08-26",
"currency": "AED",
"transactionTypeCode": "00000000",

"supplier": {
"name": "Your Company LLC",
"taxRegistrationNumber": "1000000001",
"registrationIdType": "TL",
"registrationId": "CN-1234567"
},

"buyer": {
"name": "Example Trading LLC",
"taxRegistrationNumber": "1000000002",
"participantId": "0235:1000000002",

"address": {
"street": "Sheikh Zayed Road",
"city": "Dubai",
"countryCode": "AE"
}
},

"lines": [
{
"lineNumber": 1,
"description": "Professional services — July 2026",
"quantity": 1,
"unitCode": "EA",
"unitPrice": 25000.00,
"lineNetAmount": 25000.00,
"taxCategory": "S",
"taxRate": 5.0,
"lineTaxAmount": 1250.00
}
],

"totals": {
"netAmount": 25000.00,
"taxAmount": 1250.00,
"grossAmount": 26250.00
}
}

Successful Response – Accepted for Processing

HTTP/1.1 202 Accepted

{
"invoiceId": "inv_01J8XQZ4KM",
"sourceDocumentId": "INV-2026-004411",
"status": "ACCEPTED",
"validation": { "passed": true, "warnings": [] },
"createdAt": "2026-07-27T08:41:03Z"
}
Note the 202 Accepted rather than 200 OK. The invoice has passed synchronous validation and entered processing. Transmission to the buyer and confirmation from the FTA follow asynchronously, which is why the status model needs more than two states.

Status Lifecycle

Idempotency and Duplicate Protection

Duplicate invoice submission is a compliance problem, not just a data hygiene issue — a duplicate transmitted document is reported to the FTA and delivered to the buyer. Because timeouts and retries are inevitable, idempotency needs to be handled deliberately.

The standard mechanism is an Idempotency-Key header carrying a value your system derives deterministically from the document. If the same key is received again, the provider returns the original result rather than creating a second invoice.

Illustrative – Repeated Request with the Same Key

POST /v1/invoices
Idempotency-Key: 0090001234-v1
// identical payload as before

HTTP/1.1 200 OK
Idempotent-Replay: true

{
"invoiceId": "inv_01J8XQZ4KM", // same ID, not a new invoice
"status": "DELIVERED"
}

  • Derive the key deterministically

    Use your document number plus a revision suffix. A random UUID generated per attempt defeats the purpose entirely, because a retry generates a new key.

  • Include a version component

    If a rejected invoice is corrected and resubmitted, the key should change — otherwise the provider returns the original rejection instead of processing the corrected document.

  • Confirm the retention window

    Idempotency keys are typically retained for a limited period, often 24 hours. A replay after that window may create a duplicate. Confirm the window and align your retry policy to it.

  • Test the failure path explicitly

    Deliberately submit the same document twice in sandbox and confirm the second call returns the original result rather than creating a second invoice. This is a five-minute test that prevents a serious production incident.

Webhooks and Asynchronous Status

Because delivery and FTA confirmation happen after the initial response, your system needs a way to learn about state changes. Webhooks are the appropriate mechanism at any meaningful volume.

Illustrative – Webhook Delivery

POST https://your-system.example/hooks/einvoice
Content-Type: application/json
X-Signature: sha256=a3f1b2...
X-Event-Id: evt_01J8XR2P

{
"event": "invoice.completed",
"invoiceId": "inv_01J8XQZ4KM",
"sourceDocumentId": "INV-2026-004411",
"status": "COMPLETED",
"peppolStatus": "DELIVERED",
"ftaReportingStatus": "REPORTED",
"occurredAt": "2026-07-27T08:41:19Z"
}

Webhook implementation requirements

  • Verify the signature on every request

    Your endpoint is publicly reachable. Validate the HMAC signature against your shared secret before processing anything, and reject unsigned or mismatched requests outright.

  • Respond quickly, process asynchronously

    Acknowledge with a 2xx immediately and queue the work. Providers commonly treat a slow response as a failure and retry, producing duplicate processing.

  • Handle events idempotently

    Webhooks are delivered at least once, not exactly once. Deduplicate on the event identifier so a redelivery does not double-apply a state change.

  • Tolerate out-of-order arrival

    A completed event can arrive before delivered. Do not regress a status because an older event arrived late — compare timestamps and apply only forward transitions.

  • Keep a polling fallback

    Webhooks can be missed during an outage on your side. A scheduled job that queries for invoices without a terminal status closes the gap without requiring you to poll everything continuously.

Error Taxonomy and Handling

Not all failures deserve the same response. Distinguishing between them is what keeps an integration operable at volume.

Illustrative – Structured Validation Error Response

HTTP/1.1 422 Unprocessable Entity

{
"sourceDocumentId": "INV-2026-004412",
"status": "REJECTED",
"errors": [
{
"field": "buyer.taxRegistrationNumber",
"code": "INVALID_FORMAT",
"message": "Tax registration number must be 10 digits",
"category": "DATA"
},
{
"field": "lines[0].taxCategory",
"code": "UNMAPPED_VALUE",
"message": "Value 'Z9' is not a recognised tax category",
"category": "DATA"
}
]
}
ASK FOR A MACHINE-READABLE ERROR CATEGORY

A category field distinguishing DATA errors from STRUCTURE errors is one of the most practically useful things an API can provide. It allows automatic routing — data errors to the finance queue, structural errors to engineering — without parsing message strings. If a provider’s errors are unstructured prose, expect to build and maintain that classification yourself.

Credit Notes and Corrections

A transmitted invoice cannot be edited or deleted. Corrections are made by issuing a credit note that references the original document, and the credit note is itself a fully validated, transmitted and reported document.

Illustrative – Credit Note Submission

POST /v1/credit-notes
Idempotency-Key: CN-2026-000317-v1

{
"sourceDocumentId": "CN-2026-000317",
"originalInvoiceId": "inv_01J8XQZ4KM", // mandatory reference
"originalDocumentId": "INV-2026-004411",
"reasonCode": "PRICE_CORRECTION",
"issueDate": "2026-07-29",
"currency": "AED",
"lines": [
{
"lineNumber": 1,
"description": "Price correction — professional services July 2026",
"quantity": 1,
"unitPrice": 2000.00,
"taxCategory": "S",
"taxRate": 5.0
}
]
}
Two design points matter here. The reference to the original document is mandatory — without it the FTA cannot reconcile the correction against the original transaction. And a credit note issued in a different VAT period from the original has reporting consequences, so cross-period corrections should be flagged for review rather than processed silently.

Sandbox Testing and Go-Live Checklist

Test with your own data rather than the provider’s examples. Sample payloads pass tests that real data fails, because real data contains the inconsistencies that cause rejections.

SDKs and Client Libraries

An official SDK reduces integration effort, but it is worth understanding what it does and does not remove. A good client library handles authentication and token refresh, request signing, retry logic with backoff, typed request and response models, and webhook signature verification. It does not remove the need to understand the status lifecycle, and it does not solve data quality.

How to Evaluate a Provider’s API

Before committing, read the documentation as though you were building against it tomorrow. Several things become clear quickly.

  • Is the documentation public?

    Documentation available only after signing is a meaningful signal. You cannot scope the work, and you cannot compare providers on the dimension that will consume most of your engineering time.

  • Is every error code documented?

    An error reference listing every code, its meaning, and whether it is retryable is the difference between an integration you can operate and one that generates support tickets.

  • Is there a sandbox you can access before contracting?

    The ability to build a working prototype during evaluation removes most of the risk from the decision.

  • How is versioning handled?

    Ask about the versioning scheme, the deprecation policy, and the notice period for breaking changes. UAE requirements will evolve; you need to know how that reaches your integration.

  • What are the rate limits?

    Limits should be documented explicitly and should accommodate your peak-day volume, not your average. Ask what happens when a limit is reached — queueing behaves very differently from rejection.

  • Can you export everything?

    Confirm there is an API path to retrieve your complete invoice history including signed documents. Data portability written into the contract and available through the API is what makes switching providers possible.

Aiverix API Capabilities

AIVERIX — FTA-ACCREDITED ASP / CERTIFIED PEPPOL ACCESS POINT / ISO 27 001

Built for Systems, Not Just for Users

Aiverix exposes the full compliance flow programmatically, so teams building their own billing systems can integrate without adapting their architecture to a user interface.

  • REST API

    Submission, status, retrieval, validation and document download over a documented HTTP interface.

  • Multiple input channels

    REST API, SFTP, file upload and manual entry — usable in combination across different source systems.

  • Format flexible

    JSON, XML, CSV, XLSX and flat file input. Transformation to PINT AE is handled by the platform.

  • Sandbox environment

    Test end to end before production, including validation behaviour and fallback endpoint routing.

  • Status feedback

    Validation, transmission, delivery and FTA reporting status returned against your own source document identifier.

  • Automatic fallback routing

    Buyers without a registered network address routed to the correct predefined FTA endpoint with no manual handling.

  • Low-code transformation layer

    Mapping, validation and computation rules configured rather than coded, which shortens both first integration and later changes.

  • Proven at volume

    Underlying platform used by 2,500+ enterprises worldwide, including 500+ implementations on the same Peppol framework under Saudi Arabia’s ZATCA programme.
Request API documentation and sandbox access at aiverix.ae · info@aiverix.ae · +971 58 560 3037

Frequently Asked Questions

Most FTA-accredited providers offer some form of API, but the depth varies considerably. When evaluating, look for a documented REST interface covering submission, status retrieval, document download, credit notes and webhook management; a sandbox environment you can access before contracting; a published error reference; and a stated versioning and deprecation policy. Ask whether the documentation is publicly available — providers who publish openly are generally the ones who have invested in the interface as a product. Aiverix supports REST API integration alongside SFTP, file upload and manual entry, with a sandbox environment available during evaluation.

All Guides Now Published