Overview

Wafeq ASP is an e-invoicing service provider (ASP) for the UAE. Your app submits the data of an invoice to Wafeq ASP. Wafeq ASP makes the official UAE e-invoice, delivers it to the buyer and reports it to the FTA. Then Wafeq ASP tells your app the result.

This page uses these terms:

• Your organization: the account of your company in the Wafeq ASP portal. Your company builds the app that uses the Wafeq ASP API. Your API keys, your OAuth client and your webhook endpoints belong to your organization.
• Your app: the software that your company builds, for example an ERP or an invoicing app.
• Business: a company that uses your app and wants to issue e-invoices with it.
• Grant: the permission that a business gives to your organization. A grant lets your app submit e-invoices in which that business is the seller.
• Taxpayer: a business from which your organization has an active grant. The API uses the Taxpayer ID (txpay_…) to identify it.
• Buyer: the business that receives the e-invoice.
• FTA: the UAE Federal Tax Authority. Wafeq ASP reports each e-invoice to the FTA.
• Peppol: the network that UAE businesses use to exchange e-invoices. Each business connects to Peppol through an e-invoicing provider.

For all the terms that these guides use, refer to Key terms.

Two examples

Example 1: a group of companies with its own ERP. A holding company builds an integration between its ERP and Wafeq ASP. The holding company creates one organization in the Wafeq ASP portal. Each company in the group gives a grant to this organization. In the API, each company is a separate taxpayer. The ERP submits the e-invoices of each company, with that company as the seller.

Example 2: a software company with many customers. A software company sells an invoicing app to other businesses. The software company creates one organization in the Wafeq ASP portal. Each customer that wants to issue e-invoices through the app gives a grant to this organization. In the API, each customer is a taxpayer. The app submits the e-invoices of each customer, with that customer as the seller.

What happens to an e-invoice

1. Your app submits the data of an invoice to Wafeq ASP. Your app does not make the e-invoice XML.
2. Wafeq ASP makes the official e-invoice in PINT-AE, the UAE e-invoice format.
3. Wafeq ASP checks the e-invoice against the UAE rules. If the e-invoice breaks a rule, Wafeq ASP refuses it, and nothing goes to the buyer or to the FTA.
4. Wafeq ASP looks for the buyer on Peppol:
   • If the buyer is on Peppol, Wafeq ASP delivers the e-invoice to the e-invoicing provider of the buyer.
   • If the buyer is not on Peppol, Wafeq ASP does not deliver the e-invoice. Wafeq ASP only reports it to the FTA.
5. Wafeq ASP reports the e-invoice to the FTA.
6. Wafeq ASP gives the results of the delivery and of the report to your app, through webhooks and the API.

What your app supplies and what Wafeq ASP supplies

Your app supplies:

• The buyer: name, address, TIN, VAT TRN and legal registration, as necessary.
• Each line: the item, the quantity, the price and the VAT category.
• The special scenario, if the sale is one, for example an export.
• For a credit note: the original invoice and the reason.

Wafeq ASP supplies:

• The seller: the details of the taxpayer, from its registered profile.
• The totals.
• The document type: for example 380 (tax invoice) or 480 (commercial invoice). Refer to Document types.
• The route: delivery to the buyer and a report to the FTA, or a report to the FTA only.

Build your integration in six stages

Do stages 1 to 5 in Sandbox first. Sandbox is free, and nothing in it goes to EmaraTax, the FTA or Peppol. Each stage page tells you what is different in Sandbox. For the full list, refer to Sandbox.

Where to find details

• The rules behind a field or an error: the pages in How UAE E-Invoicing Works. Start with Document types.
• Credentials, webhooks, limits and error codes: the pages in Reference.
• Each endpoint and each field: the API reference.

Base URL

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

All paths in the API reference start from this URL. For example, POST /invoices is POST https://api.wafeq.com/ae/v1/invoices.

Live and Sandbox use the same base URL. The API key selects the mode:

• A Sandbox API key (pk_test_…) goes to Sandbox.
• A Live API key (pk_live_…) goes to Live.

Live and Sandbox have separate data. Use Sandbox credentials with Sandbox taxpayers, and Live credentials with Live taxpayers.

Versioning

v1 in the base URL is the version of the API. A change that is not compatible with v1 will come in a new version. Integrations that use older addresses continue to work. New integrations must use https://api.wafeq.com/ae/v1.