Quick Start

Introduction

This tutorial runs entirely in the UAE sandbox. You will authenticate, create a sandbox Legal Entity through the simulated EmaraTax onboarding, send an invoice, and verify how an incoming invoice is received.

Sandbox API URL: https://ae-sandbox.api.acubeapi.com

No production credentials or real fiscal documents are used in this tutorial.

You will complete four steps:

Get sandbox access and authenticate.
Onboard a new Legal Entity.
Send an invoice.
Simulate the reception of an incoming invoice.

1. Get sandbox access and authenticate

Create a free sandbox account. To receive an access token, please follow the authentication guide

If the received token does not grant access to the UAE API, contact A-Cube support.

2. Onboard a new legal entity

A legal entity represents the UAE taxpayer that will send or receive documents. It cannot be added with a generic create request: you reserve its TIN, then the taxpayer completes the onboarding.

info

In production, the taxpayer starts the onboarding from EmaraTax, which redirects it to the A-Cube onboarding page. In the sandbox, EmaraTax is simulated, so you start the same onboarding page yourself from the sandbox dashboard. See Onboarding Legal Entity for the production flow.

2.1 Reserve the TIN

The {{tin_legal_entity_a}} should be replaced with a TIN of your choice (10 digits, starting with 1, e.g. 1234567890). This is your first legal entity (Legal Entity A). Use the same value everywhere {{tin_legal_entity_a}} appears in this guide.

In the sandbox dashboard, open Legal entities in the United Arab Emirates section, click New legal entity and enter {{tin_legal_entity_a}}. The legal entity appears in the list with status Reserved.

You can also reserve the TIN with POST /legal-entities. The {{jwt}} should be replaced with the token received from authentication step.

POST /legal-entities
Authorization: Bearer {{jwt}}
Content-Type: application/json
Accept: application/json

{
  "tin": "{{tin_legal_entity_a}}"
}

The reservation expires if the onboarding is not started in time. Reserving the same TIN again refreshes it.

2.2 Simulate the onboarding

On the Legal entities page of the sandbox dashboard, click Simulate onboarding (sandbox) button. The A-Cube onboarding page opens, as it would after the EmaraTax redirect:

Enter {{tin_legal_entity_a}} and any email address, then click Verify. The simulated EmaraTax returns test company data.
Check the company data, tick the confirmation and click Confirm and continue.
Wait until the page has completed the three onboarding steps: initialization, Peppol SMP synchronization and Central Registry synchronization.

The whole onboarding must be completed within five minutes, as in production. If the time runs out, start again from Simulate onboarding (sandbox).

tip

The simulated EmaraTax answers according to the TIN:

a TIN starting with 1404 fails the verification, to test the error case;
a TIN starting with 1204 returns a company without VAT TRN.

2.3 Check the legal entity

When the onboarding is complete, the legal entity has status Active in the dashboard. You can also call GET /legal-entities/{legalEntityId} and check its status. Save the legalEntityId and the tin ({{tin_legal_entity_a}}) of Legal Entity A: it will be the supplier in the next steps.

Get Legal Entity By ID Example

GET /legal-entities/{legalEntityId}
Authorization: Bearer {{jwt}}
Content-Type: application/json
Accept: application/json

{
  "legalEntityId": "64f50adc-1cd6-43e5-a627-437091a8a1d6",
  "tin": "{{tin_legal_entity_a}}",
  "status": "Active",
  "legalType": "L3",
  "nameEn": "ACube Global Technologies LLC",
  "nameAr": "إيه كيوب للتقنيات العالمية ش.ذ.م.م",
  "effectiveDate": "2024-04-01T00:00:00+00:00",
  "vatTrn": "100654190600003",
  "contact": {
    "email": "admin@mail.com",
    "mobile": null
  },
  "isEnabled": true,
  "enabledCapabilities": [
    {
      "key": "billing.invoice",
      "domain": "billing",
      "type": "invoice",
      "docScheme": "peppol-doctype-wildcard",
      "docValue": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:peppol:pint:billing-1@ae-1*::2.1",
      "processScheme": "cenbii-procid-ubl",
      "processValue": "urn:peppol:bis:billing"
    },
    {
      "key": "billing.strict_invoice",
      "domain": "billing",
      "type": "strict_invoice",
      "docScheme": "peppol-doctype-wildcard",
      "docValue": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:peppol:pint:billing-1@ae-1::2.1",
      "processScheme": "cenbii-procid-ubl",
      "processValue": "urn:peppol:bis:billing"
    },
    {
      "key": "billing.credit_note",
      "domain": "billing",
      "type": "credit_note",
      "docScheme": "peppol-doctype-wildcard",
      "docValue": "urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:peppol:pint:billing-1@ae-1*::2.1",
      "processScheme": "cenbii-procid-ubl",
      "processValue": "urn:peppol:bis:billing"
    },
    {
      "key": "billing.strict_credit_note",
      "domain": "billing",
      "type": "strict_credit_note",
      "docScheme": "peppol-doctype-wildcard",
      "docValue": "urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:peppol:pint:billing-1@ae-1::2.1",
      "processScheme": "cenbii-procid-ubl",
      "processValue": "urn:peppol:bis:billing"
    },
    {
      "key": "self_billing.invoice",
      "domain": "self_billing",
      "type": "invoice",
      "docScheme": "peppol-doctype-wildcard",
      "docValue": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:peppol:pint:selfbilling-1@ae-1*::2.1",
      "processScheme": "cenbii-procid-ubl",
      "processValue": "urn:peppol:bis:selfbilling"
    },
    {
      "key": "self_billing.strict_invoice",
      "domain": "self_billing",
      "type": "strict_invoice",
      "docScheme": "peppol-doctype-wildcard",
      "docValue": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:peppol:pint:selfbilling-1@ae-1::2.1",
      "processScheme": "cenbii-procid-ubl",
      "processValue": "urn:peppol:bis:selfbilling"
    },
    {
      "key": "self_billing.credit_note",
      "domain": "self_billing",
      "type": "credit_note",
      "docScheme": "peppol-doctype-wildcard",
      "docValue": "urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:peppol:pint:selfbilling-1@ae-1*::2.1",
      "processScheme": "cenbii-procid-ubl",
      "processValue": "urn:peppol:bis:selfbilling"
    },
    {
      "key": "self_billing.strict_credit_note",
      "domain": "self_billing",
      "type": "strict_credit_note",
      "docScheme": "peppol-doctype-wildcard",
      "docValue": "urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:peppol:pint:selfbilling-1@ae-1::2.1",
      "processScheme": "cenbii-procid-ubl",
      "processValue": "urn:peppol:bis:selfbilling"
    },
    {
      "key": "mls.application_response",
      "domain": "mls",
      "type": "application_response",
      "docScheme": "busdox-docid-qns",
      "docValue": "urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:peppol:edec:mls:1.0::2.1",
      "processScheme": "cenbii-procid-ubl",
      "processValue": "urn:peppol:edec:mls"
    }
  ],
  "createdAt": "2026-08-13T10:52:47+00:00",
  "updatedAt": "2026-08-13T10:52:55+00:00",
  "smpSyncAt": "2026-08-13T10:52:52+00:00",
  "registrySyncAt": "2026-08-13T10:52:55+00:00"
}

3. Send an invoice

3.1 Create a Second Legal Entity

There is no public endpoint for directly injecting an incoming invoice. To test invoice reception, send an invoice from one sandbox legal entity to another.

Repeat the steps of onboarding a new legal entity to create a second legal entity (Legal Entity B): reserve {{tin_legal_entity_b}} and simulate its onboarding. {{tin_legal_entity_b}} is another TIN of your choice (10 digits, starting with 1), which must be different from {{tin_legal_entity_a}}. Use the same {{tin_legal_entity_b}} value everywhere it appears in the next steps.

3.2 Send a PINT AE Invoice

Prepare a valid PINT AE UBL XML invoice and send it as a request body to POST /invoices/outgoing

Before sending the request, remember to replace {{tin_legal_entity_a}} (supplier) and {{tin_legal_entity_b}} (recipient) with the TINs of the two legal entities you created in the previous steps.

POST /invoices/outgoing
Authorization: Bearer {{jwt}}

<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
	xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
	xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2 http://docs.oasis-open.org/ubl/os-UBL-2.1/xsd/maindoc/UBL-Invoice-2.1.xsd">
	<cbc:CustomizationID>urn:peppol:pint:billing-1@ae-1</cbc:CustomizationID>
	<cbc:ProfileID>urn:peppol:bis:billing</cbc:ProfileID>
	<cbc:ProfileExecutionID>00000000</cbc:ProfileExecutionID>
	<cbc:ID>AE-CI-001Test</cbc:ID>
	<cbc:UUID>19e2c9a3-b000-4fb0-9bd5-a9c4ebda2358</cbc:UUID>
	<cbc:IssueDate>2025-02-07</cbc:IssueDate>
	<cbc:IssueTime>17:38:00</cbc:IssueTime>
	<cbc:DueDate>2025-02-07</cbc:DueDate>
	<cbc:InvoiceTypeCode>480</cbc:InvoiceTypeCode>
	<cbc:DocumentCurrencyCode>AED</cbc:DocumentCurrencyCode>
	<cac:AccountingSupplierParty>
		<cac:Party>
			<cbc:EndpointID schemeID="0235">{{tin_legal_entity_a}}</cbc:EndpointID>
			<cac:PartyName>
				<cbc:Name>Seller Trade Name</cbc:Name>
			</cac:PartyName>
			<cac:PostalAddress>
				<cbc:StreetName>Street Name</cbc:StreetName>
				<cbc:CityName>Sharjah</cbc:CityName>
				<cbc:CountrySubentity>SHJ</cbc:CountrySubentity>
				<cac:Country>
					<cbc:IdentificationCode>AE</cbc:IdentificationCode>
				</cac:Country>
			</cac:PostalAddress>
			<cac:PartyTaxScheme>
				<cbc:CompanyID>198765432112303</cbc:CompanyID>
				<cac:TaxScheme>
					<cbc:ID>VAT</cbc:ID>
				</cac:TaxScheme>
			</cac:PartyTaxScheme>
			<cac:PartyLegalEntity>
				<cbc:RegistrationName>Supplier Legal Name</cbc:RegistrationName>
				<cbc:CompanyID schemeAgencyID="TL" schemeAgencyName="Trade License issuing Authority">112345678900003</cbc:CompanyID>
				<cbc:CompanyLegalForm>Merchant</cbc:CompanyLegalForm>
			</cac:PartyLegalEntity>
			<cac:Contact>
				<cbc:Name>Contact Name</cbc:Name>
				<cbc:Telephone>Contact Number</cbc:Telephone>
				<cbc:ElectronicMail>Email address</cbc:ElectronicMail>
			</cac:Contact>
		</cac:Party>
	</cac:AccountingSupplierParty>
	<cac:AccountingCustomerParty>
		<cac:Party>
			<cbc:EndpointID schemeID="0235">{{tin_legal_entity_b}}</cbc:EndpointID>
			<cac:PostalAddress>
				<cbc:StreetName>Street Name</cbc:StreetName>
				<cbc:CityName>Abu Dhabi</cbc:CityName>
				<cbc:CountrySubentity>AUH</cbc:CountrySubentity>
				<cac:Country>
					<cbc:IdentificationCode>AE</cbc:IdentificationCode>
				</cac:Country>
			</cac:PostalAddress>
			<cac:PartyTaxScheme>
				<cbc:CompanyID>134567890123003</cbc:CompanyID>
				<cac:TaxScheme>
					<cbc:ID>VAT</cbc:ID>
				</cac:TaxScheme>
			</cac:PartyTaxScheme>
			<cac:PartyLegalEntity>
				<cbc:RegistrationName>Buyer Legal Name</cbc:RegistrationName>
				<cbc:CompanyID schemeAgencyID="TL" schemeAgencyName="Trade License issuing Authority">112345679000001</cbc:CompanyID>
			</cac:PartyLegalEntity>
			<cac:Contact>
				<cbc:Name>Contact Name</cbc:Name>
				<cbc:Telephone>Contact Number</cbc:Telephone>
				<cbc:ElectronicMail>Email Address</cbc:ElectronicMail>
			</cac:Contact>
		</cac:Party>
	</cac:AccountingCustomerParty>
	<cac:PayeeParty>
		<cac:PartyName>
			<cbc:Name>Payee Ltd.</cbc:Name>
		</cac:PartyName>
		<cac:PartyLegalEntity>
			<cbc:CompanyID>CN12389045678121</cbc:CompanyID>
		</cac:PartyLegalEntity>
	</cac:PayeeParty>
	<cac:PaymentMeans>
		<cbc:PaymentMeansCode name="In cash">10</cbc:PaymentMeansCode>
	</cac:PaymentMeans>
	<cac:PaymentTerms>
		<cbc:Note>Cash payment</cbc:Note>
	</cac:PaymentTerms>
	<cac:TaxTotal>
		<cbc:TaxAmount currencyID="AED">0</cbc:TaxAmount>
		<cbc:TaxIncludedIndicator>false</cbc:TaxIncludedIndicator>
		<cac:TaxSubtotal>
			<cbc:TaxableAmount currencyID="AED">150000</cbc:TaxableAmount>
			<cbc:TaxAmount currencyID="AED">0</cbc:TaxAmount>
			<cac:TaxCategory>
				<cbc:ID>O</cbc:ID>
				<cac:TaxScheme>
					<cbc:ID>VAT</cbc:ID>
				</cac:TaxScheme>
			</cac:TaxCategory>
		</cac:TaxSubtotal>
	</cac:TaxTotal>
	<cac:LegalMonetaryTotal>
		<cbc:LineExtensionAmount currencyID="AED">150000</cbc:LineExtensionAmount>
		<cbc:TaxExclusiveAmount currencyID="AED">150000</cbc:TaxExclusiveAmount>
		<cbc:TaxInclusiveAmount currencyID="AED">150000</cbc:TaxInclusiveAmount>
		<cbc:PayableAmount currencyID="AED">150000</cbc:PayableAmount>
	</cac:LegalMonetaryTotal>
	<cac:InvoiceLine>
		<cbc:ID>1</cbc:ID>
		<cbc:InvoicedQuantity unitCode="H87">1000</cbc:InvoicedQuantity>
		<cbc:LineExtensionAmount currencyID="AED">150000</cbc:LineExtensionAmount>
		<cac:Item>
			<cbc:Description>Item Description</cbc:Description>
			<cbc:Name>Item Name</cbc:Name>
			<cac:ClassifiedTaxCategory>
				<cbc:ID>O</cbc:ID>
				<cac:TaxScheme>
					<cbc:ID>VAT</cbc:ID>
				</cac:TaxScheme>
			</cac:ClassifiedTaxCategory>
		</cac:Item>
		<cac:Price>
			<cbc:PriceAmount currencyID="AED">150</cbc:PriceAmount>
			<cbc:BaseQuantity unitCode="H87">1</cbc:BaseQuantity>
			<cac:AllowanceCharge>
				<cbc:ChargeIndicator>false</cbc:ChargeIndicator>
				<cbc:Amount currencyID="AED">1</cbc:Amount>
				<cbc:BaseAmount currencyID="AED">151</cbc:BaseAmount>
			</cac:AllowanceCharge>
		</cac:Price>
		<cac:ItemPriceExtension>
			<cbc:Amount currencyID="AED">150000</cbc:Amount>
			<cac:TaxTotal>
				<cbc:TaxAmount currencyID="AED">0</cbc:TaxAmount>
			</cac:TaxTotal>
		</cac:ItemPriceExtension>
	</cac:InvoiceLine>
</Invoice>

{
    "invoiceId": "019ffedf-0461-7dd2-b20c-a0df95b2bfff",
    "ownerFiscalId": "{{tin_legal_entity_a}}",
    "legalEntityUuid": "64f50adc-1cd6-43e5-a627-437091a8a1d6",
    "documentType": "invoice",
    "documentTypeCode": 480,
    "direction": "outgoing",
    "status": "processed",
    "senderName": "Supplier Legal Name",
    "senderIdentifier": "0235:{{tin_legal_entity_a}}",
    "recipientName": "Buyer Legal Name",
    "recipientIdentifier": "0235:{{tin_legal_entity_b}}",
    "invoiceNumber": "AE-CI-001Test",
    "invoiceDate": "2025-02-07T00:00:00+00:00",
    "totalAmount": "150000.00",
    "totalAmountNet": "150000.00",
    "currencyCode": "AED",
    "dueDate": "2025-02-07T00:00:00+00:00",
    "externalReferenceId": null
}

4. Simulate the reception of an incoming invoice

4.1 Retrieve the received invoice

Reception is asynchronous. Retrieve the incoming invoices of Legal Entity B by filtering on its TIN ({{tin_legal_entity_b}}) and on the incoming direction, using:

GET /invoices?tin={{tin_legal_entity_b}}&direction=incoming

GET /invoices?tin={{tin_legal_entity_b}}&direction=incoming
Authorization: Bearer {{jwt}}

[
  {
    "invoiceId": "019ffee0-3ffe-7bb7-982f-1a200a260c9b",
    "ownerFiscalId": "{{tin_legal_entity_b}}",
    "legalEntityUuid": "86b13328-d9e7-4f03-9632-d1dda0822260",
    "documentType": "invoice",
    "documentTypeCode": 480,
    "direction": "incoming",
    "status": "received",
    "senderName": "Supplier Legal Name",
    "senderIdentifier": "0235:{{tin_legal_entity_a}}",
    "recipientName": "Buyer Legal Name",
    "recipientIdentifier": "0235:{{tin_legal_entity_b}}",
    "invoiceNumber": "AE-CI-001Test",
    "invoiceDate": "2025-02-07T00:00:00+00:00",
    "totalAmount": "150000.00",
    "totalAmountNet": "150000.00",
    "currencyCode": "AED",
    "dueDate": "2025-02-07T06:04:37+00:00",
    "externalReferenceId": null
  }
]

Then, retrieve the document details and original XML using its UUID.

tip

You can now authenticate, onboard a sandbox entity, and exchange test documents.

Introduction​

1. Get sandbox access and authenticate​

2. Onboard a new legal entity​

2.1 Reserve the TIN​

2.2 Simulate the onboarding​

2.3 Check the legal entity​

3. Send an invoice​

3.1 Create a Second Legal Entity​

3.2 Send a PINT AE Invoice​

4. Simulate the reception of an incoming invoice​

4.1 Retrieve the received invoice​