Integrate your ERP with the UAE Peppol network

Authentication

All requests use a per-tenant API token as a Bearer header. Create and rotate tokens in the portal under API Tokens. Your token identifies the sender — the seller on every document is your own Peppol identity, so tokens cannot impersonate another business.

# every request carries your token
Authorization: Bearer pp_your_token_here
Content-Type: application/json

Send an invoice

Post the invoice as JSON. We build the PINT-AE UBL, validate it, derive the receiver, send over Peppol and report to the FTA. You never send the seller — it is taken from your tenant profile.

# complete invoice — all required fields
curl -X POST https://ozeinvoice.ae/api/v1/invoices \
  -H "Authorization: Bearer pp_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "doc_type": "Invoice",
    "invoice_number": "INV-1001",
    "issue_date": "2026-09-14",
    "due_date": "2026-10-14",
    "currency": "AED",
    "payment_means_code": "30",
    "transaction_type": "Standard",
    "buyer": {
      "name": "Acme Trading LLC",
      "trn": "100000000000003",
      "address": "Sheikh Zayed Road",
      "city": "Dubai",
      "state": "Dubai",
      "country": "AE"
    },
    "lines": [
      { "description": "Consulting", "qty": 1, "unit": "HUR",
        "price": 500.00, "vat_rate": 5, "tax_classification": "S" }
    ]
  }'

Request fields

Send raw values — mapping of your own units, tax labels and payment methods to the code lists below is your side; validation and compliance are ours.

Legend. required send it on every document. Where a default is noted we apply it automatically if you omit the field — but a production integration should set it deliberately, not rely on the default. optional is a matching aid only.

Field-name aliases (PINT-AE names)

If you prefer the official PINT-AE / MoF field names, you can send those instead of the short names above — both are accepted (the short name wins if you send both):

Credit notes

A credit note takes all the same fields as an invoice above (buyer, lines, currency, payment means, transaction type — everything except a due date, which a credit note doesn't carry). You simply set doc_type to CreditNote and add the fields below on top:

# complete credit note — same fields as an invoice, plus the credit-note ones
curl -X POST https://ozeinvoice.ae/api/v1/invoices \
  -H "Authorization: Bearer pp_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "doc_type": "CreditNote",
    "invoice_number": "CN-2001",
    "issue_date": "2026-09-20",
    "currency": "AED",
    "transaction_type": "Standard",
    "credit_reason_code": "DL8.61.1.D",
    "credit_reason_text": "Goods returned by customer",
    "preceding_invoice_number": "INV-1001",
    "preceding_invoice_date": "2026-09-14",
    "buyer": {
      "name": "Acme Trading LLC", "trn": "100000000000003",
      "address": "Sheikh Zayed Road", "city": "Dubai", "state": "Dubai", "country": "AE"
    },
    "lines": [
      { "description": "Consulting", "qty": 1, "unit": "HUR",
        "price": 500.00, "vat_rate": 5, "tax_classification": "S" }
    ]
  }'

Testing — dry run

Add ?dry_run=1 (or "dry_run": true) to validate a payload without sending anything. Nothing is sent over Peppol, nothing is reported to the FTA, and it does not count toward your monthly usage. Use it while you build.

curl -X POST "https://ozeinvoice.ae/api/v1/invoices?dry_run=1" \
  -H "Authorization: Bearer pp_your_token" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Responses & errors

Success

{ "ok": true, "data": { "document_id": 123, "status": "SENT" } }

Dry run

{ "ok": true, "data": {
  "dry_run": true, "valid": true,
  "errors": [], "error_details": [],
  "schematron_version": "PINT AE 1.0.4"
} }

Validation failure — per-field

{ "ok": true, "data": {
  "valid": false,
  "error_details": [
    { "code": "ibr-144-ae", "field": "buyer.address",
      "message": "The buyer address is incomplete — provide street, city and emirate." }
  ]
} }

Other statuses: 400 missing/invalid field, 401 bad token, 409 duplicate invoice number.

Idempotency

Retries are safe. An invoice number is unique per account, and you can also send an Idempotency-Key header — a repeat with the same key returns the original result instead of sending twice.

Idempotency-Key: INV-1001

Ping — check your connection

Returns your tenant identity and capabilities. No side effects — a safe way to confirm your token and base URL are correct.

Receiving invoices

List inbound documents received on Peppol, or fetch one — as raw UBL and as a parsed JSON summary (supplier, buyer, lines, tax, totals). You can also subscribe to invoice.received webhooks in the portal instead of polling.

Payment means (UNCL 4461)

Send the code in payment_means_code. Any valid UNCL 4461 code is accepted; the common ones:

Transaction types (BTAE-02)

Send the label (or the 8-flag code) in transaction_type.

Tax classification

Per line, in tax_classification. A label like "Zero-rated" is accepted too; if null we infer it from the VAT rate.

Credit-note reasons

Send the code in credit_reason_code (a label is accepted).

Units of measure (UN/ECE Rec 20)

Per line, in unit. Blank defaults to C62.