Try in playground

Go live in the United Arab Emirates

Work through this checklist before you send UAE e-invoices in production. You need UAE documents that already pass in sandbox and the company's authorization for its accredited service provider in production.

Open in Claude Open in ChatGPT

Onboard the company in production

A company onboarded in sandbox is not registered in production.

  1. In the Invoice Portal, select United Arab Emirates and Production.
  2. Follow Onboard a UAE company, choosing Verify with EmaraTax with the company’s TIN.
  3. Add the branch and the source that will send its invoices.

Open Onboard and check the company’s registration status. A Pending registration is not ready to send invoices.

Move your integration to production

  • Create a key under Production API keys with Write access. See Create an API key.
  • With Production selected, link the source you added during onboarding to your mapping and the company’s branch. See Manage sources and their links.
  • Send "environment": "production" and the production source’s name:version in every Unify request. If you use an SDK, change its environment setting; each SDK guide shows where.
  • Check the production credit balance in Credits, and create a separate production webhook if you receive webhooks. See Credits and Set up a webhook.

Check the required test cases

If your workspace uses the Default GETS Mapping, the test cases for the United Arab Emirates must show Passed in Test your mapping. Until they do, Unify refuses invoices with 412 and failed_precondition, in sandbox and in production.

Send the first production invoice

Send one real invoice and follow it with its documentId until isTerminal is true. See Submit and retrieve. final_valid means both the buyer’s ASP and the FTA accepted it; in the Invoice Portal it shows as Compliant. final_invalid means one of them rejected it, and rejected means it failed validation before delivery. Read errors for the reason. See the five corners.

UAE checks

  • Replace every sample identity from your tests with real ones: the seller’s and buyer’s TRNs, and their Peppol IDs, the 10-digit TIN with scheme 0235.
  • Check each document type against the UAE field reference, the allowed code lists and the validation rules. Credit notes and self-billed documents have their own rules.

If something goes wrong

ASP_LINKAGE_NOT_FOUND during onboarding: the company’s ASP authorization is missing for production. Ask its authorized administrator to check it, then try again.

The company stays Pending: use Refresh status if it is offered, and check again later.

403 with permission_denied: the key is a sandbox key. Use a production key with "environment": "production".

404: the source is not in production. Check its name and version in Source management with Production selected.

412 with failed_precondition: the required test cases for the United Arab Emirates have not all passed. Run them, then send the document again. Unify errors lists each reason.

422: the document failed validation. Correct the fields named in errors; see UAE validation rules.