Quick Start
Introduction
This tutorial runs entirely in the UAE sandbox. You will authenticate, create a sandbox Legal Entity through the mocked EmaraTax flow, 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 must be created through the onboarding flow and cannot be added using a generic create request.
In production, onboarding starts in EmaraTax. In the sandbox, EmaraTax is mocked, so start directly with POST /legal-entities/onboarding/verify using the provided test data and the LINK action.
Important: In production, onboarding starts from EmaraTax service, where the customer selects A-Cube as its Accredited Service Provider. EmaraTax then redirects the user to A-Cube with a temporary authCode. After verification, A-Cube issues an Integration Passport, valid for five minutes, to complete the onboarding flow. In the sandbox, the EmaraTax handoff is simulated, but the timeframe is exactly the same to simulate production behavior.
Note that each step returns a new passport. Pass the returned value to the next request in the X-Onboarding-Passport header. Always use the latest passport returned by the previous step.
The onboarding flow consists of four sequential steps:
2.1. Verifies the mocked EmaraTax request.
Use POST /legal-entities/onboarding/verify to simulate the request verification call from EmaraTax service.
The {{jwt}} should be replaced with the token received from authentication step.
POST /legal-entities/onboarding/verify
Authorization: Bearer {{jwt}}
Content-Type: application/json
Accept: application/json
{
"token": "qwertyuiopasdfghjklzxcvbnm",
"tin": "1069086623",
"email": "admin@mail.com",
"action": "LINK"
}
{
"action": "LINK",
"step": "INITIALIZATION",
"isCompleted": false,
"legalEntity": {
"tin": "1069086623",
"legalType": "L3",
"nameEn": "ACube Global Technologies LLC",
"nameAr": "إيه كيوب للتقنيات العالمية ش.ذ.م.م",
"effectiveDate": "2024-04-01",
"email": "admin@mail.com",
"legalEntityId": null,
"vatTrn": "100654190600003",
"mobile": null
},
"passport": "<verification_passport>"
}
2.2. Create a new legal entity in A-Cube.
Use POST /legal-entities/onboarding/init to create a legal entity in A-Cube.
The {{verification_passport}} should be replaced with the passport value received in the above step.
POST /legal-entities/onboarding/init
Authorization: Bearer {{jwt}}
X-Onboarding-Passport: {{verification_passport}}
Content-Type: application/json
Accept: application/json
{
"action": "LINK",
"step": "SMP_SYNC",
"isCompleted": false,
"legalEntity": {
"tin": "1069086623",
"legalType": "L3",
"nameEn": "ACube Global Technologies LLC",
"nameAr": "إيه كيوب للتقنيات العالمية ش.ذ.م.م",
"effectiveDate": "2024-04-01",
"email": "admin@mail.com",
"legalEntityId": "64f50adc-1cd6-43e5-a627-437091a8a1d6",
"vatTrn": "100654190600003",
"mobile": null
},
"passport": "<initialization_passport>"
}
2.3. Register legal entity receiving capabilities with the Peppol SMP.
Use POST /legal-entities/onboarding/sync-smp to register receiving capabilities with the Peppol SMP for a newly created legal entity.
The {{initialization_passport}} should be replaced with the passport value received in the above step.
POST /legal-entities/onboarding/sync-smp
Authorization: Bearer {{jwt}}
X-Onboarding-Passport: {{initialization_passport}}
Content-Type: application/json
Accept: application/json
{
"action": "LINK",
"step": "CENTRAL_REGISTRY_SYNC",
"isCompleted": false,
"legalEntity": {
"tin": "1069086623",
"legalType": "L3",
"nameEn": "ACube Global Technologies LLC",
"nameAr": "إيه كيوب للتقنيات العالمية ش.ذ.م.م",
"effectiveDate": "2024-04-01",
"email": "admin@mail.com",
"legalEntityId": "64f50adc-1cd6-43e5-a627-437091a8a1d6",
"vatTrn": "100654190600003",
"mobile": null
},
"passport": "<smp_sync_passport>"
}
Save the legalEntity.legalEntityId and legalEntity.tin for later usage (as either supplier or receiver in the next steps).
2.4. Complete the Central Registry synchronization.
Use POST /legal-entities/onboarding/sync-central-registry to complete synchronization of legal entity in the Central Registry.
The {{smp_sync_passport}} should be replaced with the passport value received in the above step.
POST /legal-entities/onboarding/sync-central-registry
Authorization: Bearer {{jwt}}
X-Onboarding-Passport: {{smp_sync_passport}}
Content-Type: application/json
Accept: application/json
204 No Content
Optionally, when the flow is complete, call GET /legal-entities/{legalEntityId} and confirm that the entity status is Active.
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": "1069086623",
"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. Simulate an incoming 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.
Please repeat the steps of onboarding a new legal entity using different TIN number to create a second legal entity. Save the newly generated legal entity TIN as a {{recipient_tin}}.
4. Send an invoice
4.1 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 {{supplier_tin}} & {{recipient_tin}} accordingly with the Legal Entity TINs 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">{{supplier_tin}}</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">{{recipient_tin}}</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": "1095338362",
"legalEntityUuid": "86b13328-d9e7-4f03-9632-d1dda0822260",
"documentTypeCode": 480,
"direction": "outgoing",
"status": "processed",
"senderName": "Supplier Legal Name",
"senderIdentifier": "0235:1095338362",
"recipientName": "Buyer Legal Name",
"recipientIdentifier": "0235:1069086623",
"invoiceNumber": "AE-CI-001Test",
"invoiceDate": "2025-02-07T06:04:37+00:00",
"totalAmount": "150000",
"totalAmountNet": "150000",
"currencyCode": "AED",
"dueDate": "2025-02-07T06:04:37+00:00",
"externalReferenceId": null
}
3.2 Retrieve the received invoice
Reception is asynchronous. Retrieve the filtered invoice list using:
GET /invoices?owningLegalEntity.legalEntityId={newLegalEntityId}&direction=incoming
GET /invoices?owningLegalEntity.legalEntityId={newLegalEntityId}&direction=incoming
Authorization: Bearer {{jwt}}
[
{
"invoiceId": "019ffb8c-9c03-7f86-80c6-e6020af6162e",
"ownerFiscalId": "1095338362",
"legalEntityUuid": "86b13328-d9e7-4f03-9632-d1dda0822260",
"documentTypeCode": 389,
"direction": "incoming",
"status": "received",
"senderName": "Buyer Legal Name",
"senderIdentifier": "0235:1095338362",
"recipientName": "Supplier Legal Name",
"recipientIdentifier": "0235:1069086623",
"invoiceNumber": "AE-01-SB-TEST",
"invoiceDate": "2025-02-06T00:00:00+00:00",
"totalAmount": "11175.45",
"totalAmountNet": "10643.29",
"currencyCode": "AED",
"dueDate": "2025-02-13T00:00:00+00:00",
"externalReferenceId": "PO-AE-220"
},
{
"invoiceId": "019ffee0-3ffe-7bb7-982f-1a200a260c9b",
"ownerFiscalId": "1095338362",
"legalEntityUuid": "86b13328-d9e7-4f03-9632-d1dda0822260",
"documentTypeCode": 389,
"direction": "incoming",
"status": "received",
"senderName": "Buyer Legal Name",
"senderIdentifier": "0235:1095338362",
"recipientName": "Supplier Legal Name",
"recipientIdentifier": "0235:1069086623",
"invoiceNumber": "AE-01-SB-TEST",
"invoiceDate": "2025-02-06T00:00:00+00:00",
"totalAmount": "11175.45",
"totalAmountNet": "10643.29",
"currencyCode": "AED",
"dueDate": "2025-02-13T00:00:00+00:00",
"externalReferenceId": "PO-AE-220"
}
]
Then, retrieve the document details and original XML using its UUID.
You can now authenticate, onboard a sandbox entity, and exchange test documents.