ISV UAE quickstart

This guide takes a new ISV workspace from setup to its first validated UAE sandbox invoice. You do not need to create a mapping or upload a sample payload first.

What Complyance prepares automatically

When a workspace is created under an ISV account, Complyance creates:

a protected UAE Default GETS Mapping;
a complete UAE GETS payload in Payload Manager;
a validated default mapping release; and
automatic assignment for newly onboarded sandbox Sources, enabled by default.

The Source created by onboarding is assigned to the designated default mapping. Other mappings in the workspace do not disable this behavior.

1. Generate a sandbox API key

In the ISV portal, open API Keys, create a sandbox key with read and write access, and copy it when it is displayed. The secret is shown only once.

Store the key in a server-side secret manager. The examples below use environment variables so the secret is not written into shell history or source code.

export COMPLYANCE_API_KEY='YOUR_SANDBOX_API_KEY'
export COMPLYANCE_SOURCE='accounting-platform:2.1'

Connect endpoints use X-API-Key. Unify endpoints use the same key as Authorization: Bearer.

2. Onboard a UAE company

The TIN must have a ready ASP linkage in the same environment. Use a unique sourceName and sourceVersion; together they become the Source identity used for invoice submission.

curl --request POST 'https://prod.gets.complyance.io/v3/connect/companies' \
  --header "X-API-Key: ${COMPLYANCE_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "sourceName": "accounting-platform",
    "sourceVersion": "2.1",
    "countryCode": "AE",
    "tin": "1234567890",
    "contactPersonEmail": "onboarding@example.com",
    "contactPersonName": "Amina Hassan",
    "branchName": "Main",
    "platformEnvironment": "sandbox"
  }'

A ready Source returns:

{
  "success": true,
  "data": {
    "sourceName": "accounting-platform",
    "sourceVersion": "2.1",
    "readyForInvoicing": true,
    "mappingReadiness": {
      "status": "READY",
      "templateId": "default-gets-WORKSPACE_ID"
    }
  }
}

Do not submit an invoice when readyForInvoicing is false. Use mappingReadiness.code to resolve the mapping problem first.

3. Download the complete payload

In the ISV portal, open Payload Manager and select Default UAE GETS Payload. The same schema-complete example is available here:

Download the complete UAE GETS payload

The payload exposes every registered UAE tax-invoice field. Populated values form a valid standard invoice example; unused optional fields are null or empty arrays so you can discover them without inventing property names.

Change at least these values for each invoice:

Area	Fields to review
Invoice identity	`header.documentId`, `header.issueDate`, `header.dueDate`, `header.currency`
Seller	`parties.seller`, including VAT, registration, address, and Peppol values
Buyer	`parties.buyer`, especially `peppolId`, address, and tax identifiers
Lines	`lineItems[]`, including quantity, price, taxable value, tax rate, and tax amount
Totals	`taxTotals[]` and `totals`

For a UAE Peppol participant such as 0235:1234567890, send the identifier and scheme separately:

{
  "parties": {
    "buyer": {
      "peppolId": "1234567890"
    }
  },
  "extensions": {
    "peppol_buyer_peppolIdScheme": "0235"
  }
}

See Complete UAE GETS payload for field-count, null-value, and document-type guidance.

4. Build the Unify V2 request

Save your populated payload as uae-invoice-payload.json, then wrap it with the Source returned by onboarding:

jq --arg source "${COMPLYANCE_SOURCE}" '{
  country: "AE",
  environment: "sandbox",
  purpose: "invoicing",
  source: $source,
  documentType: {
    base: "tax_invoice",
    modifiers: []
  },
  payload: .
}' uae-invoice-payload.json > uae-invoice-request.json

The Source must exactly match sourceName:sourceVersion from onboarding.

5. Submit the invoice

curl --request POST 'https://prod.gets.complyance.io/api/v3/unify' \
  --header "Authorization: Bearer ${COMPLYANCE_API_KEY}" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'new-api: true' \
  --data @uae-invoice-request.json

Store the returned documentId. An HTTP success proves that this request was processed successfully; it is not by itself proof of final government or Peppol acceptance.

6. Verify the final result

curl --request GET \
  "https://prod.gets.complyance.io/api/v3/documents/DOCUMENT_ID/status" \
  --header "Authorization: Bearer ${COMPLYANCE_API_KEY}" \
  --header 'Accept: application/json'

Continue only while data.isTerminal is false.

Result	Meaning
`final_valid`	Terminal successful outcome for the selected environment
`final_invalid` or `rejected`	Terminal failure; inspect `errors[]`
`submitted`, `processing`, or `delivery_success`	Not terminal yet
`delivery_failed`	Delivery failed; inspect the response and retain the request identifiers

Sandbox success proves sandbox processing and validation. Only a terminal production result can represent a live authority or network outcome.