United Arab Emirates only. This module implements the UAE EIS model — a decentralized Peppol 5-corner network (no central pre-clearance authority), where a Mandatory accredited service provider (ASP) transmits each document. It is distinct from Saudi ZATCA (a central clearance/reporting model — see ZATCA). ColorsX74 never holds your ASP credentials in clear text; each company onboards its own ASP account.
How it fits together
A draft is not a tax document. An e-invoice is created when you issue an invoice — never when you save a draft. A draft carries a provisional DRFT- reference, posts nothing, and produces no e-invoice, no invoice counter and no hash-chain entry. Issue it and exactly one e-invoice is created, carrying the invoice's final number. Abandon or delete the draft and nothing was ever consumed — so your reported sequence stays gapless.
UAE e-invoicing is a gated add-on. When enabled for a company it lives under E-Invoicing (UAE) in the sidebar (/einvoicing-uae); its API is served at /api/v1/einvoicing-uae. It records each sales invoice, builds it into the mandatory PINT AE format (UBL 2.1 — CustomizationID urn:peppol:pint:billing-1@ae-1, document types 380 invoice / 381 credit note, TRN as the Peppol EndpointID under scheme 0235, AED), checks it against the PINT AE business rules, and submits it through your ASP over Peppol.
Jump to: The 5-corner model · Enabling the module · Wire formats · Onboarding your ASP · Document lifecycle & MLS · Testing with the built-in Mock · A missing e-invoice (the catch-up) · Operator notes.
The decentralized 5-corner model
Unlike a central-clearance country, the UAE routes invoices over Peppol: you (corner 1) → your ASP (corner 2) → the network (corner 3) → the buyer's ASP (corner 4) → the buyer (corner 5), with the Federal Tax Authority informed via the network. You cannot connect to Peppol directly — an accredited service provider (ASP) is mandatory. ColorsX74 builds and validates the document; your contracted ASP signs/seals and transmits it, and reports a Message Level Status (MLS) back.
Enabling the module
Switch into the company, open E-Invoicing (UAE) → Settings, and toggle Enable UAE e-invoicing. From then on, every sales invoice you issue is recorded as a UAE e-invoice document (type 380; credit notes type 381). You can optionally override the seller legal name and TRN here when they differ from the company record.
Your history is never back-filed. The moment you enable is recorded, and invoices issued before it never get an e-invoice automatically. Record an older one deliberately if you need it (POST /api/v1/einvoicing-uae/documents/record/{invoiceId}). Switching it off and on again loses nothing: an invoice issued while it was on still gets its e-invoice, and one issued while it was off never does.
Wire formats — raw UBL or JSON DTO
Different ASPs accept different payloads, so the module produces both from one projection and you pick which to send under Settings → Wire format:
- Raw PINT AE UBL — the standards XML. Every generated UBL passes an offline conformance check (the high-value mandatory PINT AE rules: CustomizationID, EndpointID scheme 0235 + TRN, the party tax/legal blocks, AED, the per-line VAT category, and the monetary-total reconciliation) before it can be submitted — a document that fails is held with the exact rule, never shipped.
- Provider JSON DTO — a canonical JSON shape carrying the same PINT AE data, for ASPs whose API consumes JSON rather than UBL.
Onboarding your ASP
Open E-Invoicing (UAE) → Service provider (ASP) and record the provider you've contracted, its API endpoint, the wire format it consumes, and your API key + secret. The credentials are encrypted at rest and never displayed, logged, or returned by the API again — the screen only shows whether credentials are stored. Leave the key/secret blank when editing other settings to keep the stored values untouched.
Before the first live transmission a SuperAdmin must Arm production for the company — a deliberate safety step on top of the platform's live-transmission switch and the stored credentials. Until a real ASP is armed and enabled, you can exercise the entire flow with the built-in Mock (below).
Document lifecycle & the Message Level Status
Each document moves through: Recorded (captured from the invoice) → Generated (PINT AE produced + conformance-checked) → SubmittedToAsp → AspAccepted or AspRejected → MlsReceived (the asynchronous Peppol delivery status settled). A blocked or transient failure is marked SubmissionFailed and is safe to retry; a generation/conformance problem is marked Failed with the offending rule. Use the per-row Generate, Submit, Refresh status, and View UBL actions on the documents table; the Provider and MLS columns show where each document is.
Testing with the built-in Mock
A built-in offline Mock provider runs the complete forward + MLS flow with no credentials and no network — ideal for trying the cycle before you contract an ASP. Leave the provider unset (or choose mock), enable the module, create an invoice, then Generate → Submit → Refresh status: you'll see it move to AspAccepted and then MlsReceived. Reference adapters for real providers (Complyance, Pagero/ClearTax, Cygnet.One) ship behind the live-transmission switch and are wired to each ASP's sandbox during onboarding.
A missing e-invoice: the automatic catch-up
A UAE e-invoice is recorded the instant an invoice is issued. If that step is interrupted — the server restarts at the wrong moment, or recording hits an error — the invoice is issued but has no e-invoice. A background catch-up runs every few minutes and records the missing ones:
- Only issued invoices — never drafts or voided invoices — and only those issued while UAE e-invoicing was on.
- It waits 10 minutes after an invoice last changed, so the normal path always goes first. Either way an invoice gets exactly one e-invoice.
- More than 20 at once is held for a person. Nothing is recorded for the company; the platform
operator is notified once a day with the count and the oldest invoice number and can release one run of up to
200, oldest first (
POST /api/v1/einvoicing-uae/admin/companies/{companyId}/catch-up, SuperAdmin only; an unused release expires after 24 hours, and every release is written to the company's audit log). - A bad invoice never blocks the others: it is recorded as Failed with the error, and the catch-up moves on. Generating it again (the documents table's Generate) rebuilds it once the cause is fixed.
Your administrators are notified when the catch-up recorded missing e-invoices — at most once a day, and always after a run the platform operator released. Review E-Invoicing (UAE) → Documents and submit them.
Operator notes
- One company, one ASP account. Each company onboards separately. Switch into the company first, then onboard.
- Secrets stay encrypted. The ASP API key and secret are encrypted at rest and never displayed, logged, or returned — only a "credentials stored" indicator is shown.
- TRN is required on both parties. A UAE e-invoice needs the seller's and the buyer's TRN; the conformance check will hold a document that is missing either.
- Credit notes (negative totals) are typed and generated automatically as the 381 credit-note document.
- Build-ahead. The pipeline is ready ahead of the UAE mandate so a company can be live the moment it has an accredited provider and its credentials.
- If generating an e-invoice is declined, the message says why. There are four different reasons — the invoice is still a draft, the invoice has been voided, UAE e-invoicing is not enabled for the company, or the invoice no longer exists. These were previously reported with one message naming only the last two, so an operator whose invoice was simply not issued yet was sent to the settings screen for a problem that did not exist. Each reason is now named exactly, matching the ZATCA behaviour.