📄Peppol BIS Billing 3.0 · UAE FTA Compliant · v1

Aigentrix E-Invoice API

Submit, validate, and manage Peppol-compliant UAE e-invoices programmatically. Integrate your ERP, accounting software, or custom application with the Aigentrix external gateway using a single API key — no JWT management required.

Base URLhttps://api.aigentrix.ai

Auth HeaderX-API-KEY: <key>

Endpoints15

🚀 Get API Key Download Postman Collection View Pricing →

Getting Started

Complete these six steps to go from zero to your first API call in under 10 minutes.

Quick-start — your first invoice in one request

bash

curl -X POST "https://api.aigentrix.ai/external/api/v1/eInvoiceEntry/createFull" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: <your-api-key>" \
  -d '{
    "companyId": 1,
    "invoiceRef": "INV-001",
    "documentId": "INV-2024-001",
    "issueDate": "2024-01-15",
    "invoiceTypeCode": "380",
    "invoiceTransactionType": "B2B",
    "documentCurrencyCode": "AED",
    "sellerName": "ABC Trading LLC",
    "sellerVatTrn": "100123456700003",
    "sellerCountryCode": "AE",
    "buyerName": "XYZ Corp",
    "buyerVatTrn": "100987654300003",
    "buyerCountryCode": "AE",
    "lineExtensionTotal": 1000.00,
    "taxAmount": 50.00,
    "totalIncludingTax": 1050.00,
    "payableAmount": 1050.00,
    "lines": [{
      "lineNumber": 1,
      "itemName": "Consulting Services",
      "quantity": 10, "quantityUom": "HUR",
      "unitPrice": 100.00, "lineNetAmount": 1000.00,
      "taxCategory": "S", "taxRatePercent": 5,
      "taxScheme": "VAT", "lineTaxAmount": 50.00,
      "inclVatAmount": 1050.00
    }],
    "allowances": [], "payments": [], "terms": []
  }'

👤

Create Your Aigentrix Account

Visit the Aigentrix platform and sign up for a new account. You will need a valid business email address.

1Navigate to https://app.aigentrix.ai and click Get Started.
2Enter your full name, business email, and a secure password.
3Verify your email address via the confirmation link sent to your inbox.
4Log in with your credentials.

💡

If your organisation already has an account, ask your admin to invite you instead of creating a new organisation.

🏢

Create Your Organisation

An Organisation is the top-level entity that holds your companies, users, and subscription credits.

1After logging in, go to Settings → Organisation.
2Click "Create Organisation" and fill in your legal organisation name.
3Set the default country and currency for the organisation.
4Click "Save". Your organisation is now active.

💡

Your organisation ID and credit balance are displayed on the Organisation dashboard. Credits are consumed each time the AI extraction engine processes a document.

🏭

Add a Company

A Company represents the legal entity that issues or receives e-invoices (e.g. your UAE-registered company).

1Navigate to Settings → Companies → Add Company.
2Enter the company's registered name (EN and AR if required), VAT TRN, and address details.
3Select the country (AE for UAE) and the default currency (AED).
4Click "Save". Note the Company ID — you will use it in API calls as companyId.

💡

You can add multiple companies under one organisation. Each company has its own VAT TRN and Peppol participant IDs.

📄

Enable E-Invoicing for the Company

Activate the e-invoice module for the company so it can submit, validate, and track Peppol-compliant invoices.

1Open the company record and go to the E-Invoice tab.
2Toggle "Enable E-Invoice" to ON.
3Enter the seller's Peppol Participant ID (e.g. 0088:1234567890123) if you are submitting outbound invoices via Peppol.
4Click "Save Configuration".
5Optionally configure the FTA submission credentials under the Compliance section.

💡

The E-Invoice module supports both OUTBOUND (seller) and INBOUND (buyer) document flows. You do not need Peppol IDs for validation-only usage.

🔑

Generate an API Key

API Keys allow external systems (your ERP, custom scripts, or third-party tools) to call Aigentrix without requiring user login tokens.

1Navigate to Settings → API Keys → Generate New Key.
2Give the key a descriptive label (e.g. ERP Integration – Production).
3Select the scopes (read, write, or full access).
4Click "Generate". Copy the key immediately — it is shown only once.
5Store the key securely (e.g. in your environment variables as AIGENTRIX_API_KEY).

💡

Pass the key in every API request as the X-API-KEY HTTP header. Keys can be revoked at any time from the API Keys settings page.

🚀

Start Using the API

With your API key and Company ID in hand you can now interact with all E-Invoice endpoints through the external gateway.

1Set your base URL to https://api.aigentrix.ai.
2Add X-API-KEY: <your-key> to every request header.
3Use the companyId returned from step 3 in request bodies that require it.
4Start with the Validate endpoint to test your invoice data before creating real records.
5Use Create E-Invoice (endpoint 1) to persist and submit invoices.

💡

All dates must be in yyyy-MM-dd format. Currency codes follow ISO 4217 (e.g. AED, USD). Country codes follow ISO 3166-1 alpha-2 (e.g. AE, US).

Authentication

All external API calls are authenticated via the X-API-KEY HTTP header. No JWT tokens are needed — the gateway handles internal auth automatically.

Missing key401

{ "errorKey": "API key missing" }

Invalid key401

{ "errorKey": "Invalid API key" }

Invalid endpoint404

{ "errorKey": "Invalid endpoint" }

Server error500

{ "errorKey": "Forwarding failed", "details": "..." }

javascript

// Example using fetch (Node.js / browser)
const response = await fetch(
  "https://api.aigentrix.ai/external/api/v1/eInvoiceEntry/createFull",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-KEY": process.env.AIGENTRIX_API_KEY,
    },
    body: JSON.stringify(invoicePayload),
  }
);
const data = await response.json();

Invoice Lifecycle

Every outbound e-invoice moves through a defined set of statuses. Understanding this flow helps you build robust error handling and retries in your integration.

DRAFT

Created, not yet validated

→

VALID

Passed schematron validation

→

SUBMITTED

Sent to Peppol / FTA

→

CLEARED

Cleared by authority

VALIDATION_FAILEDSchematron validation errors — fix and resubmit

REJECTEDRejected by authority — correction required

CANCELLEDManually cancelled

NOT_INITIATEDTax submission not started (taxStatus)

API Reference

Try it in Postman

Download the ready-to-import Postman collection with all 15 endpoints, sample payloads, and environment variables pre-configured.

Download Collection

All 15 endpoints live under the external gateway and require the X-API-KEY header. Path parameters shown as {entryId} must be replaced with real values.

GETPOSTPUTDELETE

1POSThttps://api.aigentrix.ai/external/api/v1/eInvoiceEntry/createFull

Create E-Invoice Entry (Full JSON)

Creates a complete e-invoice in a single JSON request — header, line items, allowances/charges, payments, and payment terms all in one call. Returns the new entry ID on success.

Notes

•invoiceTypeCode: 380 = Invoice, 381 = Credit Note, 386 = Prepayment.

•invoiceTransactionType: B2B, B2C, or B2G.

•For taxCategory = 'E' (exempt), vatExemptReasonCode is mandatory [ibr-167-ae].

•All monetary amounts must be in the currency specified by documentCurrencyCode.

•Date fields accept: yyyy-MM-dd, dd-MMM-yyyy, dd/MM/yyyy, MM/dd/yyyy, dd-MM-yyyy.

json

{
  "companyId": 1,
  "invoiceRef": "INV-001",
  "documentId": "INV-2024-001",
  "issueDate": "2024-01-15",
  "invoiceTypeCode": "380",
  "invoiceTransactionType": "B2B",
  "documentCurrencyCode": "AED",
  "noteEN": "Standard invoice",
  "taxPointDate": "2024-01-15",
  "invoiceSupplyDate": "2024-01-14",
  "paymentDueDate": "2024-02-15",
  "orderReference": "PO-2024-001",
  "contractDocumentReference": "CTR-001",
  "buyerReference": "BR-001",
  "invoicePeriodStartDate": "2024-01-01",
  "invoicePeriodEndDate": "2024-01-31",

  "sellerName": "ABC Trading LLC",
  "sellerVatTrn": "100123456700003",
  "sellerVatScheme": "VAT",
  "sellerRegisteredName": "ABC Trading LLC",
  "sellerAddressLine1": "Office 101, Business Bay",
  "sellerCity": "Dubai",
  "sellerPostalZone": "00000",
  "sellerCountrySubdivision": "DU",
  "sellerCountryCode": "AE",
  "sellerTelephone": "+971501234567",
  "sellerEmail": "info@abctrading.ae",

  "buyerName": "XYZ Corp",
  "buyerVatTrn": "100987654300003",
  "buyerVatScheme": "VAT",
  "buyerRegisteredName": "XYZ Corporation",
  "buyerAddressLine1": "Floor 5, DIFC Gate Building",
  "buyerCity": "Dubai",
  "buyerPostalZone": "00000",
  "buyerCountrySubdivision": "DU",
  "buyerCountryCode": "AE",
  "buyerTelephone": "+971507654321",
  "buyerEmail": "ap@xyzcorp.ae",

  "lineExtensionTotal": 1000.00,
  "docLevelDiscount": 50.00,
  "docLevelCharges": 0.00,
  "taxAmount": 47.50,
  "totalIncludingTax": 997.50,
  "payableAmount": 997.50,
  "roundingAmount": 0.00,

  "deliveryLocation": "Warehouse A",
  "deliveryAddressLine1": "Jebel Ali Free Zone",
  "deliveryCity": "Dubai",
  "deliveryPostalZone": "15000",
  "deliveryCountrySubdivision": "DU",
  "deliveryCountryCode": "AE",
  "deliveryPartyName": "XYZ Corp Warehouse",
  "deliveryIncoterms": "DDP",

  "lines": [
    {
      "lineNumber": 1,
      "itemName": "Consulting Services",
      "itemDescription": "Monthly IT consulting - Jan 2024",
      "sellerItemId": "SVC-001",
      "itemTypeGoodsServices": "S",
      "itemCountryOrigin": "AE",
      "quantity": 10,
      "quantityUom": "HUR",
      "unitPrice": 95.00,
      "priceBaseQty": 1,
      "priceBaseQtyUom": "HUR",
      "lineDiscountAmount": 50.00,
      "lineDiscountPercent": 5.26,
      "lineNetAmount": 900.00,
      "taxCategory": "S",
      "taxRatePercent": 5,
      "taxScheme": "VAT",
      "lineTaxAmount": 45.00,
      "inclVatAmount": 945.00,
      "orderLineRef": "PO-2024-001-L1",
      "periodStart": "2024-01-01",
      "periodEnd": "2024-01-31"
    }
  ],

  "allowances": [
    {
      "level": "Header",
      "isCharge": false,
      "reasonCode": "95",
      "reason": "Promotional discount",
      "amount": 50.00,
      "baseAmount": 1000.00,
      "percent": 5,
      "taxCategory": "S",
      "taxPercent": 5,
      "taxScheme": "VAT"
    }
  ],

  "payments": [
    {
      "paymentMeansCode": "30",
      "paymentId": "PAY-001",
      "creditAccountIban": "AE070331234567890123456",
      "creditAccountScheme": "IBAN",
      "creditAccountName": "ABC Trading LLC",
      "bankBicSwift": "CBAUAEADXXX",
      "bankAddressLine1": "Commercial Bank of Dubai, Main Branch",
      "bankCity": "Dubai",
      "bankCountry": "AE"
    }
  ],

  "terms": [
    {
      "termId": "TERM-001",
      "termNote": "Net 30 days",
      "termAmount": 997.50,
      "termCurrency": "AED",
      "termInstallDate": "2024-02-15"
    }
  ]
}

2GEThttps://api.aigentrix.ai/external/api/v1/eInvoiceEntry/{entryId}

Get E-Invoice Entry by ID

Retrieves the full header details of a single e-invoice entry by its ID.

json

{
  "id": 1042,
  "documentIdEN": "INV-2024-001",
  "invoiceTypeCode": "380",
  "documentCurrencyCode": "AED",
  "issueDateEN": "2024-01-15T00:00:00",
  "paymentDueDate": "2024-02-15T00:00:00",
  "status": "DRAFT",
  "taxStatus": "NOT_INITIATED",
  "supplyPartyNameEN": "ABC Trading LLC",
  "supplyVatIdEN": "100123456700003",
  "customerPartyNameEN": "XYZ Corp",
  "customerVatIdEN": "100987654300003",
  "legalTaxInclusiveAmountEN": 997.50,
  "legalFinalPayableEN": 997.50,
  "taxTotalTaxAmount": 47.50,
  "createdAt": "2024-01-15T10:30:00"
}

3GEThttps://api.aigentrix.ai/external/api/v1/eInvoiceEntry

List E-Invoice Entries

Returns a paginated list of e-invoice entries filtered by company and date range.

Query Parameters

companyIdreq

Filter by company ID.

startDatereq

Start of issue date range (yyyy-MM-dd).

endDatereq

End of issue date range (yyyy-MM-dd).

pageopt

Zero-based page number (default: 0).

perPageopt

Page size (default: 10).

sortByopt

Field to sort by (default: createdAt).

orderByopt

asc or desc (default: desc).

statusopt

Filter by status: DRAFT | VALID | SUBMITTED | REJECTED.

typeopt

OUTBOUND or INBOUND.

searchStringopt

Free-text search.

json

{
  "content": [
    {
      "id": 1042,
      "documentIdEN": "INV-2024-001",
      "status": "DRAFT",
      "issueDateEN": "2024-01-15T00:00:00",
      "supplyPartyNameEN": "ABC Trading LLC",
      "customerPartyNameEN": "XYZ Corp",
      "legalFinalPayableEN": 997.50
    }
  ],
  "totalElements": 1,
  "totalPages": 1,
  "pageNumber": 0,
  "pageSize": 10
}

4GEThttps://api.aigentrix.ai/external/api/v1/eInvoiceEntry/{entryId}/statusTimeline

Status Timeline

Returns the full chronological status transition history for an entry (e.g. DRAFT → VALID → SUBMITTED → CLEARED).

Query Parameters

typereq

OUTBOUND or INBOUND.

json

{
  "statusTimeline": {
    "entryId": 1042,
    "documentId": "INV-2024-001",
    "type": "OUTBOUND",
    "timeline": [
      { "status": "DRAFT",     "timestamp": "2024-01-15T10:30:00", "updatedBy": "user@example.com" },
      { "status": "VALID",     "timestamp": "2024-01-15T10:35:00", "updatedBy": "system" },
      { "status": "SUBMITTED", "timestamp": "2024-01-15T10:36:00", "updatedBy": "system" }
    ]
  }
}

5GEThttps://api.aigentrix.ai/external/api/v1/print/xml/{entryId}

PDF Download (Peppol)

Generates and streams a Peppol e-invoice PDF via Jasper Reports. Save the binary response as a .pdf file.

Query Parameters

fileNamereq

text

// Binary PDF stream — save response body as .pdf
// Response headers:
Content-Type: application/pdf
Content-Disposition: attachment; filename="outbound_sent_1042.pdf"

6GEThttps://api.aigentrix.ai/external/api/v1/print/orgxml/{entryId}

Download Raw XML

Downloads the stored UBL 2.1 Peppol XML file for the given entry. Save the response body as a .xml file.

Query Parameters

fileNamereq

Notes

•The XML is Peppol BIS Billing 3.0 / UBL 2.1 format.

•Use this endpoint to forward the signed XML to your buyer or authority.

text

// Raw XML stream — save as .xml
// Response headers:
Content-Type: application/xml; charset=UTF-8
Content-Disposition: attachment; filename="outbound_sent_1042.xml"

7PUThttps://api.aigentrix.ai/external/api/v1/eInvoiceEntry/{entryId}

Update E-Invoice Entry

Updates header fields of an existing entry. Only entries in DRAFT or VALIDATION_FAILED status can be updated.

json

{
  "documentIdEN": "INV-2024-001-REV",
  "noteEN": "Revised note - updated billing address",
  "customerAddressLine1EN": "Floor 7, DIFC Gate Building"
}

8DELETEhttps://api.aigentrix.ai/external/api/v1/eInvoiceEntry

Delete E-Invoice Entries

Permanently deletes one or more entries by ID. Pass a JSON array of entry IDs in the request body.

json

[1042, 1043]

9POSThttps://api.aigentrix.ai/external/api/v1/eInvoiceEntry/upload

Bulk Upload (Excel)

Creates multiple invoices from a 4-sheet Excel workbook. Existing DRAFT / VALIDATION_FAILED / REJECTED entries matching companyId + documentId are overwritten.

Notes

•Content-Type must be multipart/form-data.

•Sheet 0: Invoice Header | Sheet 1: Invoice Lines | Sheet 2: Allowances & Charges | Sheet 3: Payment.

•Download the template first using endpoint 10.

text

// multipart/form-data
companyId: 1
file: <your-excel-file.xlsx>

10GEThttps://api.aigentrix.ai/external/api/v1/eInvoiceEntry/upload/template

Download Upload Template

Downloads sample_einvoice_entry.xlsx — the 4-sheet bulk upload template. Save the binary response as a .xlsx file.

text

// Binary XLSX stream
Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Content-Disposition: attachment; filename="sample_einvoice_entry.xlsx"

11POSThttps://api.aigentrix.ai/external/api/v1/eInvoiceEntry/upload/errorLog

Download Error Log (CSV)

Pass the "results" array from a previous bulk upload response to download a CSV audit log of all rows (SUCCESS, FAILED, SKIPPED, OVERWRITTEN).

json

[
  { "invoiceRef": "INV-001", "status": "SUCCESS",  "entryId": 1042, "linesCreated": 2 },
  { "invoiceRef": "INV-003", "status": "SKIPPED",  "error": "Entry already exists with status SUBMITTED" },
  { "invoiceRef": "INV-004", "status": "FAILED",   "error": "[ibr-167-ae] vatExemptReasonCode mandatory" }
]

12POSThttps://api.aigentrix.ai/external/api/v1/eInvoiceEntry/validate

Validate Invoices – JSON (no DB write)

Validates one or more invoices against Peppol schematron rules WITHOUT saving anything to the database. Use this before creating real records to catch errors early.

Query Parameters

includeXmlopt

true to include the generated UBL XML per result (default: false).

Notes

•Request body is a JSON array (wrap a single invoice in [ ]).

•Same field structure as endpoint 1 (createFull).

•No credits are consumed — purely a validation call.

json

[
  {
    "companyId": 1,
    "invoiceRef": "INV-001",
    "documentId": "INV-2024-001",
    "issueDate": "2024-01-15",
    "invoiceTypeCode": "380",
    "invoiceTransactionType": "B2B",
    "documentCurrencyCode": "AED",
    "sellerName": "ABC Trading LLC",
    "sellerVatTrn": "100123456700003",
    "sellerCountryCode": "AE",
    "buyerName": "XYZ Corp",
    "buyerVatTrn": "100987654300003",
    "buyerCountryCode": "AE",
    "lineExtensionTotal": 1000.00,
    "taxAmount": 50.00,
    "totalIncludingTax": 1050.00,
    "payableAmount": 1050.00,
    "lines": [
      {
        "lineNumber": 1,
        "itemName": "Consulting Services",
        "quantity": 10,
        "quantityUom": "HUR",
        "unitPrice": 100.00,
        "lineNetAmount": 1000.00,
        "taxCategory": "S",
        "taxRatePercent": 5,
        "taxScheme": "VAT",
        "lineTaxAmount": 50.00,
        "inclVatAmount": 1050.00
      }
    ],
    "allowances": [],
    "payments": [],
    "terms": []
  }
]

13POSThttps://api.aigentrix.ai/external/api/v1/eInvoiceEntry/upload/validate

Validate Upload – Excel 4-sheet (no DB write)

Parses a 4-sheet bulk-upload Excel workbook and validates all invoices against Peppol schematron rules without persisting anything.

Query Parameters

includeXmlopt

true to receive the generated UBL XML per result.

text

// multipart/form-data
file: <sample_einvoice_entry.xlsx>

14POSThttps://api.aigentrix.ai/external/api/v1/eInvoiceEntry/upload/simple/validate

Validate Simple Upload – Excel 1-sheet (no DB write)

Parses a simplified single-sheet Excel workbook and validates all invoices without DB writes.

Query Parameters

includeXmlopt

true to receive the generated UBL XML per result.

text

// multipart/form-data
file: <sample_einvoice_simple.xlsx>

15GEThttps://api.aigentrix.ai/external/api/v1/eInvoiceEntry/{entryId}/validationErrors

Get Validation Errors for Entry

Returns the stored Peppol schematron validation errors for a specific entry. Useful for entries in VALIDATION_FAILED status.

json

{
  "entryId": 1042,
  "documentId": "INV-2024-001",
  "status": "VALIDATION_FAILED",
  "errors": [
    "[ibr-167-ae] Line 1: vatExemptReasonCode is mandatory when taxCategory is 'E'.",
    "[BR-CO-15] Amount due for payment (BT-115) must equal Invoice total with VAT minus paid amount plus rounding."
  ],
  "warnings": []
}

Quick Reference

Invoice Type Codes

Code	Type
380	Commercial Invoice
381	Credit Note
386	Prepayment Invoice
388	Tax Invoice

VAT Tax Categories

Code	Description
S	Standard rate (5% UAE)
Z	Zero-rated
E	Exempt (vatExemptReasonCode required)
O	Outside scope

Payment Means Codes

Code	Description
10	Cash
30	Credit Transfer (Bank)
48	Bank Card
49	Direct Debit
57	Standing Order
97	Clearing between partners

Common Unit of Measure (UoM)

Code	Description
HUR	Hour
DAY	Day
ANN	Year (Annual)
MTH	Month
EA	Each (Unit)
KGM	Kilogram
MTR	Metre