Guide
Integration API — Integrator Guide
Unibox · Peppol e-invoicing platform
Submitting, validating, and tracking e-invoicing documents on the Peppol network (PINT-AE, UAE jurisdiction).
| API version | 1.0 |
| Document date | 7 August 2026 |
| Machine-readable contract | openapi.yaml (OpenAPI 3.0.3, ships alongside this guide) |
| Audience | ERP and system integrators building server-to-server connections to Unibox |
Contents
- Overview and concepts
- Getting started
- Authentication
- Error handling
- Idempotent submission
- Choosing the delivery route
- Pre-flight validation
- Submitting documents
- The document lifecycle
- Tracking and synchronization
- Downloading document renditions
- Limits, paging, and retention
- Appendix A — Document statuses
- Appendix B — Document types
- Appendix C — Error code catalog
- Appendix D — Using the OpenAPI specification
- Appendix E — Delivery retries and time bounds
1. Overview and concepts
Unibox is an e-invoicing platform for the UAE Peppol network. Through the Integration API your system can submit UBL invoices and credit notes, have them validated against the PINT-AE rules, delivered to the receiver (over Peppol or by email), reported to the tax authority, and track every step of that journey — including documents received for your organization over the network.
1.1 Key concepts
| Concept | Meaning |
|---|---|
| Business document | One invoice or credit note in Unibox, identified by a UUID that every endpoint shares. Has a direction: Out (submitted by you) or In (received for you over the network). |
| Participant | An organization on the Peppol network, addressed by a participant identifier of the form icd:identifier (e.g. 0235:100000000000003). Your own participant id is returned by GET /me. |
| Status | Each document carries one business status (Appendix A) that advances asynchronously as the document is validated, delivered, and tax-reported. |
| Tax Data Document (TDD) | The reporting artifact Unibox generates and submits to the tax authority for a document. Its XML can be downloaded once it exists. |
| Tenant | Your organization's isolated space in Unibox. An API key belongs to exactly one tenant, and every listing and lookup is automatically scoped to it. |
1.2 The asynchronous model
Submission is an acknowledgement, not a delivery receipt. A 201 Created means Unibox
accepted the document and will validate, dispatch, and tax-report it asynchronously. Everything
after the 201 is observed through the tracking endpoints — most efficiently through the
status-change feed (chapter 10).
1.3 Endpoint map
| Endpoint | Purpose |
|---|---|
GET /api/business-document/me | Verify the key; identify the tenant |
GET /api/business-document/participants/{id}/capabilities | Is the receiver on Peppol, and what can it receive? (public — no API key) |
POST /api/business-document/validate | Dry-run PINT-AE validation, nothing stored |
POST /api/business-document/upload | Submit UBL XML for Peppol delivery |
POST /api/business-document/upload-non-peppol | Submit UBL XML for email delivery |
POST /api/business-document/upload-excel | Submit an Excel workbook (Unibox template) |
GET /api/business-document/templates/excel | Download the current Excel templates (zip) |
GET /api/business-document/status-changes | Delta-sync feed of every status transition |
GET /api/business-document/ids | Backfill / reconciliation listing by creation date |
GET /api/business-document/{id} | Full document detail |
GET /api/business-document/{id}/xml | Download the document XML |
GET /api/business-document/{id}/tdd/xml | Download the tax data document XML |
GET /api/business-document/{id}/pdf | Download a PDF rendition of the document |
2. Getting started
The base URL for your environment and your API key are provided at onboarding. All examples in
this guide use https://api.unibox.ae as a placeholder.
2.1 Your first call
curl -H "X-Api-Key: <your key>" https://api.unibox.ae/api/business-document/me
{
"tenantId": "0b9f7c1e-8f4b-4a49-9d3e-2f6a01d1a111",
"tenantName": "Acme Trading LLC",
"tenantPeppolId": "0235:100000000000003"
}
A 200 proves the key works and shows which tenant — and which Peppol participant — it acts as. If you manage multiple tenants, call this per key and store the mapping.
2.2 Integration checklist
GET /mereturns your expected tenant.- Validate a sample invoice with
POST /validateuntil it isvalid: true. - Look up your test receiver with the capabilities endpoint.
- Submit with
POST /upload(or/upload-non-peppol), storing the returned document id and your idempotency key. - Implement the status-change polling loop (section 10.3) and confirm you observe the document reaching
ExchangedandTaxReported. - Handle the failure statuses (
ValidationError,SendingError,ReceiverValidationError,TaxReportError) — read the structured error list fromGET /{id}. - If you receive documents: list incoming ones via
/ids(direction: In) and fetch their XML.
3. Authentication
Every request carries the API key in the X-Api-Key header:
X-Api-Key: <your key>
- Keys are issued and rotated in the Unibox portal. Treat them as secrets: server-side storage only, never in client-side code or logs.
- The key scopes every request to your tenant. There is no way to read or write another tenant's data; requests for foreign document ids return
404. - A missing or invalid key returns
401with a deliberately simple body — one of the few errors that is not an RFC 7807 problem details object (the idempotency rejections in chapter 5 are the others):
{ "error": "unauthorized", "message": "Invalid API key." }
One exception: the participant capabilities lookup (chapter 6) is public — Peppol registrations are public data, so that endpoint works without a key.
4. Error handling
Except for the 401 above and the two idempotency rejections described in chapter 5, every
error response is an RFC 7807 problem-details body carrying a machine-readable
errors[] array:
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "Bad Request",
"status": 400,
"detail": "Time window cannot exceed 30 days.",
"errors": [
{
"code": "TimeRangeExceeded",
"propertyName": null,
"translationKey": null,
"detail": "Time window cannot exceed 30 days."
}
]
}
TIP — Rule of thumb Branch on
errors[].code— the codes are stable contract (Appendix C). Thedetailtexts are for humans and may be reworded.
4.1 Status codes
| Status | Meaning | Recommended handling |
|---|---|---|
400 | The request is invalid (bad parameter, malformed file, unknown status filter…). Special case on submissions: a reused Idempotency-Key returns a plain-string 400 — see chapter 5. | Fix the request; do not retry unchanged. For the idempotency case: the document already exists — recover its id (chapter 5). |
401 | Missing/invalid API key. | Check key configuration; alert an operator. |
404 | Resource does not exist (or belongs to another tenant); for capabilities: participant not on Peppol. | Business-level handling (e.g. fall back to email delivery). |
409 | The same Idempotency-Key was seen before: empty body — that request is still in flight; problem details with BusinessDocument.IdempotencyKeyAlreadyUsed — the key already created a document (chapter 5). | In flight: wait briefly, retry with the same key. Already used: the message names the existing document id. |
500 | Unexpected server error. | Retry with backoff; submissions with the same Idempotency-Key are safe to retry. |
5. Idempotent submission
The three submission endpoints require an Idempotency-Key header. Its purpose is to make
retries safe: network timeouts happen, and without the key a retry could create a duplicate
invoice on the Peppol network.
Idempotency-Key: 0d4f2e5a-7c1b-4f6e-9a3d-8b2c01d1a333
The guarantee is duplicate prevention, not response replay. A key is permanently
bound to the one document it successfully creates; once a submission with the key has succeeded,
every later request carrying the same key is rejected — the original 201 is
never replayed, even when the resent file is byte-identical.
- Generate one key per business document — a UUID stored next to the document in your system is the recommended pattern. Never reuse a key for a different document, and never switch to a fresh key when retrying a submission you are unsure about — a fresh key is exactly what creates duplicates.
- A failed submission does not consume the key. After a synchronous error response (a validation
400, a500, …) the same key can be submitted again once the problem is fixed.
5.1 What a repeated key receives
| You send the same key… | Response | Meaning |
|---|---|---|
| while the first request is still processing | 409, empty body | Wait briefly, then retry with the same key. |
| after the first attempt failed | processed normally | The key was not consumed; this new response is authoritative. |
| within 24 h after the first attempt succeeded | 400, plain-string body "The Idempotency header key value '…' was used in a different request." | The document already exists. Returned even for a byte-identical resend. Recover the id as described below. |
more than 24 h after the 201 | 409, problem details, code BusinessDocument.IdempotencyKeyAlreadyUsed | The message names the document id the key created. |
The two rejection bodies (the plain-string 400 and the empty in-flight 409) are, together
with the 401, the only error responses that are not problem-details objects.
5.2 Recovering after a timeout
On a timeout you cannot know whether the attempt landed — so retry with the same key and
branch on the table above: a normal response means it did not land; the plain-string
400 means it did. What a same-key retry can never do is create a duplicate.
If you receive the reuse rejection but never saw the original 201 (so you have no
document id), find the document with GET /ids over the submission date window and match
on businessDocumentNumber (section 10.4); it also appears in the status-change feed
as it progresses. After 24 h the rejection itself names the id.
6. Choosing the delivery route
Unibox delivers documents two ways: over the Peppol network (/upload) or by email for
receivers not on the network (/upload-non-peppol). The capabilities endpoint tells you
which applies, per receiver:
GET
/api/business-document/participants/{participantId}/capabilities?businessCard=true
This endpoint is public — Peppol registrations are public data, so no API key is required (sending one is harmless):
curl "https://api.unibox.ae/api/business-document/participants/9915:test/capabilities?businessCard=true"
{
"participantId": "9915:test",
"documentTypes": [
{ "niceName": "Peppol BIS Billing UBL Invoice V3", "isDeprecated": false },
{ "niceName": "Peppol BIS Billing UBL Credit Note V3", "isDeprecated": false }
],
"businessCard": {
"participant": { "scheme": "iso6523-actorid-upis", "value": "9915:test" },
"entity": [
{
"name": [ { "name": "Austrian Government" } ],
"countrycode": "AT",
"geoinfo": "Vienna, Austria",
"website": [ "https://test.example.gov" ],
"additionalinfo": "Test endpoint",
"regdate": "2012-01-01"
}
]
}
}
- 200 — the participant is registered;
documentTypeslists what its access point accepts. Route to/upload. - 404 (
ParticipantNotRegistered) — not on the Peppol network. Route to/upload-non-peppol. businessCardis the receiver's self-published directory entry — useful for displaying or verifying the receiver's identity. Field names mirror the Peppol directory's own JSON (lowercase).
TIP — Performance The lookup queries the live Peppol network (typically a few hundred milliseconds). If you call it per invoice, cache results per participant for a few minutes on your side.
7. Pre-flight validation
POST /api/business-document/validate runs the exact validation pipeline of a real
submission — UBL 2.1 XSD, then the PINT-AE schematrons — and returns every finding at once.
Nothing is stored, nothing is sent, and no Idempotency-Key is needed. Use it while building
your mapping, and optionally as a gate before each production submission.
curl -H "X-Api-Key: <key>" \
-F "UblFile=@invoice.xml" \
https://api.unibox.ae/api/business-document/validate
{
"valid": false,
"errorCount": 1,
"warningCount": 0,
"messages": [
{
"severity": "ERROR",
"ruleId": "ibr-119-ae",
"location": "/ubl:Invoice[1]/cac:TaxTotal[1]/cac:TaxSubtotal[2]",
"text": "Each VAT breakdown (IBG-23) shall have a VAT category rate (IBT-119), ..."
}
],
"documentType": "BILLING",
"customizationId": "urn:peppol:pint:billing-1@ae-1",
"validatedAt": "2026-08-07T10:00:00Z"
}
Reading the result:
validis true when there are noERROR-severity findings.WARNINGs do not block submission but are worth reviewing.- XSD-stage findings carry the Xerces
cvc-*rule id and aline/columnlocation; schematron findings carry the PINT rule id and an XPath location. - Two synthetic findings describe documents the pipeline cannot classify:
xml-not-well-formed(the bytes are not parseable XML) anddocument-type-unknown(cbc:CustomizationIDmissing or unrecognised). These are still HTTP 200 withvalid: false— every document defect arrives through the report, never as a transport error.
8. Submitting documents
All three endpoints accept multipart/form-data, require the Idempotency-Key header
(chapter 5), and return 201 Created with the document UUID as the body and a
Location header pointing at the document resource.
8.1 Peppol delivery
POST
/api/business-document/upload
| Form field | Required | Description |
|---|---|---|
UblFile | yes | UBL XML file (.xml); root element Invoice or CreditNote |
CountryCode | no | ISO 3166-1 alpha-2; defaults to AE |
curl -H "X-Api-Key: <key>" \
-H "Idempotency-Key: 0d4f2e5a-7c1b-4f6e-9a3d-8b2c01d1a333" \
-F "UblFile=@invoice.xml" \
https://api.unibox.ae/api/business-document/upload
HTTP/1.1 201 Created
Location: https://api.unibox.ae/api/business-document/7b0c31da-5be1-45c9-9d2e-6f2a01d1a222
"7b0c31da-5be1-45c9-9d2e-6f2a01d1a222"
8.2 Email delivery (non-Peppol receivers)
POST
/api/business-document/upload-non-peppol
Same contract as 8.1 plus a required Email form field — the recipient address the
document is delivered to. The document is still validated against PINT-AE before dispatch and is
tax-reported like any other document.
8.3 Excel workbook
POST
/api/business-document/upload-excel
Accepts an Excel workbook following the Unibox template in the UblFile field; Unibox
parses it into a PINT-AE XML document and submits it over Peppol. Intended for integrations that
cannot yet produce UBL directly.
The current templates are always available from the API itself:
GET
/api/business-document/templates/excel
Returns a zip archive (application/zip) with one workbook per document type —
invoice, credit note, and their self-billing variants. Templates evolve with the PINT-AE rules:
build Excel submissions on the current download, not on a stored copy, and re-fetch periodically.
8.4 What to store
TIP — Persist these three things The returned document id (the handle for all tracking calls), your idempotency key (to retry safely), and your own document number. Together they make every later question — "did it land?", "what happened to it?" — answerable.
9. The document lifecycle
After the 201, a document advances through the statuses in Appendix A. The typical successful outgoing flow is:
New ──> Exchanged ──> TaxReported (terminal success)
Failure statuses and their meaning:
| Status | What happened | Your next step |
|---|---|---|
ValidationError | The document failed PINT-AE validation. | GET /{id} → errors[] lists the violations. Fix and submit as a new document (new idempotency key). |
ReceiverValidationError | The receiving side rejected the document. | Inspect errors[]; correct and resubmit as a new document. |
SendingError | Delivery to the receiver failed. | Inspect errors[]. Depending on cause, resubmit or contact support. |
TaxReportError | Delivery succeeded but tax reporting failed. | Usually resolved platform-side; monitor the status, escalate if it persists. |
Failure statuses are not the first resort: transient problems are absorbed by automatic retries before any of them appears — Appendix E describes that machinery and its time bounds.
Incoming documents (direction: In) appear in the listings as they are received; fetch
their XML with GET /{id}/xml and ingest them into your system.
10. Tracking and synchronization
Three complementary tools:
| Tool | Use for |
|---|---|
GET /status-changes | Staying in sync — the delta feed of every transition; poll it on a schedule. |
GET /ids | Backfill and reconciliation — "which documents exist / entered the system in window X". |
GET /{id} | Drilling in — full detail and the structured error list for one document. |
10.1 The status-change feed
GET
/api/business-document/status-changes?from=&to=&status=&pageSize=&continuationToken=
{
"statusChanges": [
{
"eventId": 184223,
"documentId": "7b0c31da-5be1-45c9-9d2e-6f2a01d1a222",
"direction": "Out",
"businessDocumentType": "Invoice",
"businessDocumentNumber": "INV-2026-0042",
"oldStatus": "Exchanged",
"newStatus": "TaxReported",
"changedAtUtc": "2026-08-05T09:14:03Z"
}
],
"continuationToken": null
}
- Rows are ordered by change time ascending, are self-sufficient (direction, type, and number are included so you can decide relevance without a follow-up fetch), and each carries a unique
eventId. from/toare UTC date-times, both inclusive; the window may span at most 30 days and defaults to the last 30.statusfilters on the transition's new status (case-insensitive; values in Appendix A).- The feed serves the last 90 days. A
fromolder than that returns 400RetentionExceeded— reconcile older history via/ids+GET /{id}.
10.2 Why polling needs an overlap
Event ids and timestamps are assigned when a transition is written, but other requests only see it when its transaction commits — typically milliseconds later, occasionally more. A poll can therefore run in the gap: an event with a lower id/timestamp becomes visible after you already read past that point. Polling "everything after my highest eventId" (or after your exact last timestamp) silently skips such events, forever — and because the race is rare, that bug passes every test and surfaces months later as a missed rejection.
10.3 The correct polling loop
# state: lastPollUtc (persisted), seen: set of (eventId, changedAtUtc) from the overlap window
every 1–5 minutes:
windowStart = lastPollUtc - 60 seconds # the overlap
pollStarted = now (UTC)
token = null
repeat:
page = GET /status-changes?from={windowStart}&continuationToken={token}
for event in page.statusChanges:
if event.eventId not in seen:
process(event) # your handler
seen.add(event.eventId, event.changedAtUtc)
token = page.continuationToken
until token == null
seen.removeWhere(changedAtUtc < pollStarted - 60 seconds) # bounded memory
lastPollUtc = pollStarted # persist
TIP — Shortcut for idempotent processors If handling an event twice is harmless in your system (e.g. "set invoice 42's status to TaxReported" — the common ERP case), you can drop the
seenset entirely and just keep the 60-second overlap. The overlap is the part that guarantees you never miss an event; the dedup only suppresses harmless repeats.
⚠ WARNING — Do not Poll with
from = lastPollUtcexactly (no overlap), or track "highest eventId processed" as your cursor. Both look correct and both lose events under concurrency — see 10.2.
10.4 Backfill and reconciliation — the ids listing
GET
/api/business-document/ids?dateFrom=&dateTo=&pageSize=&continuationToken=
{
"documents": [
{
"id": "7b0c31da-5be1-45c9-9d2e-6f2a01d1a222",
"direction": "Out",
"businessDocumentType": "Invoice",
"businessDocumentNumber": "INV-2026-0042",
"status": "TaxReported",
"createdUtc": "2026-08-01T07:42:11Z",
"lastChangedUtc": "2026-08-05T09:14:03Z"
}
],
"continuationToken": null
}
- The window is over the document's creation date in Unibox (system time, not invoice date) — exactly what reconciliation needs: "what entered the system when". Whole UTC days,
dateToinclusive, at most 31 days, defaults to the last 31. - Rows include both directions; each row's
statusandlastChangedUtcreflect the current state, so a full reconciliation pass is: page through the window, compare statuses with your system, drill into differences withGET /{id}. - Use it after downtime longer than the feed's 90-day horizon, for periodic audits, and to discover incoming documents if you don't process them from the feed.
10.5 Paging (both listings)
When a response carries a non-null continuationToken, more rows exist: repeat the request
with the token attached, keeping the window and filters identical. Treat the token as opaque —
its format may change without notice. A stale or malformed token returns 400
InvalidContinuationToken; restart from the first page.
10.6 Push notifications (webhooks)
In addition to the feed, Unibox can push webhook notifications for delivered
(Exchanged) and tax-reported documents — configured per tenant in the Unibox portal.
Webhooks are a latency optimization, not a substitute for the feed: run the polling loop as the
reconciliation net underneath them. A webhook delivery that keeps failing is retried for roughly
42 minutes and then dropped for that event (Appendix E.5) — the feed remains the source
of truth.
11. Downloading document renditions
GET
/api/business-document/{id}/xml?downloadFileMode=DownloadGET/api/business-document/{id}/tdd/xml?downloadFileMode=DownloadGET/api/business-document/{id}/pdf?downloadFileMode=Download
- All three accept
downloadFileMode:Download(default) adds aContent-Dispositionattachment header with the file name;Inlinestreams the body without one. /xmlreturns the document's UBL XML (application/xml) — for outgoing documents the submitted payload, for incoming documents the received one./tdd/xmlreturns the Tax Data Document reported to the tax authority; it responds404until the TDD has been generated./pdfreturns a human-readable PDF rendition (application/pdf) generated on demand from the document's data — suitable for ERP archiving and approval workflows. Generation takes a moment; cache the result if you fetch it repeatedly.404also covers ids that don't exist or belong to another tenant.
12. Limits, paging, and retention
| Subject | Value |
|---|---|
| Page size (both listings) | 1–1000, default 500 |
| Status-change feed window | ≤ 30 days per request (UTC date-times, inclusive) |
| Status-change feed horizon | Last 90 days; older ⇒ 400 RetentionExceeded, reconcile via /ids |
| Ids listing window | ≤ 31 days per request (whole UTC days, dateTo inclusive) |
| Idempotency-key reuse rejection | 400 within 24 h of the successful submission, 409 naming the document id afterwards (chapter 5) — the original response is never replayed |
| Recommended feed polling interval | 1–5 minutes (with the 60-second overlap) |
| Rate limiting | None enforced today; fair-use limits may be introduced with notice before general availability. Design for the polling pattern above rather than tight loops. |
⚠ WARNING — Loud failures by design Where other APIs silently clamp (an over-long window, an out-of-range page size), this API returns 400. A silently clamped 60-day request would look complete while missing a month — an error you can handle beats data you didn't know was missing.
Appendix A — Document statuses
| Status | Meaning | Terminal? |
|---|---|---|
New | Accepted and processing (validation / dispatch pending). | no |
ValidationError | Failed PINT-AE validation in Unibox. | yes (resubmit corrected document) |
ReceiverValidationError | Rejected by the receiving side. | yes (resubmit corrected document) |
Exchanged | Delivered to the receiver. | no (tax reporting follows) |
TaxReported | Reported to the tax authority. | yes — success |
SendingError | Delivery to the receiver failed. | yes (investigate via errors[]) |
TaxReportError | Tax reporting failed after delivery. | monitor / escalate |
Appendix B — Document types
| Value | Meaning |
|---|---|
Invoice | Commercial invoice (UNTDID 1001 code 380) |
CreditNote | Credit note (381) |
SelfBillingInvoice | Self-billed invoice (389) |
SelfBillingCreditNote | Self-billed credit note (261) |
InvoiceOutOfScopeOfVat | Invoice out of scope of VAT (480) |
CreditNoteGoodsAndServices | Credit note related to goods or services (81) |
Appendix C — Error code catalog
Codes appear in errors[].code of problem-details responses. HTTP status in parentheses.
Submission (/upload, /upload-non-peppol, /upload-excel)
| Code | Meaning |
|---|---|
UBLFileNotUploaded (400) | No file, or an empty file, in the UblFile field. |
ExtensionInvalid (400) | The file does not have the expected extension. |
UBLUnsupportedDocumentType (400) | The XML root element is not Invoice or CreditNote. |
XmlInvalid (400) | The file is not well-formed XML. |
ExternalEmailInvalid (400) | Email missing or malformed (/upload-non-peppol). |
ExternalPeppolIdInvalid (400) | The receiver id in the document is not valid for non-Peppol sending. |
DocumentValidationError (400) | The document failed PINT-AE validation at submission; details in the error text. Use /validate to get the full structured report. |
ValidatorUnavailable (500) | The validation service is temporarily unavailable; retry with the same idempotency key. |
UnknownError (500) | Unexpected failure while processing the upload. |
BusinessDocument.IdempotencyKeyAlreadyUsed (409) | The Idempotency-Key already created a document more than 24 h ago; the message names its id. Within 24 h the same reuse returns the plain-string 400 of chapter 5 instead. |
Pre-flight validation (/validate)
| Code | Meaning |
|---|---|
UBLFileNotUploaded (400) | No file, or an empty file. |
ExtensionInvalid (400) | Not an .xml file. |
XmlInvalid (400) | The first element could not be parsed as XML. |
UBLUnsupportedDocumentType (400) | Root element is not Invoice or CreditNote. |
Ids listing (/ids)
| Code | Meaning |
|---|---|
InvalidDateRange (400) | dateFrom is after dateTo. |
DateRangeExceeded (400) | Window longer than 31 days. |
DateOutOfRange (400) | A date outside the supported range. |
InvalidPageSize (400) | pageSize outside 1–1000. |
InvalidContinuationToken (400) | Malformed/stale token; restart from the first page. |
Status-change feed (/status-changes)
| Code | Meaning |
|---|---|
InvalidTimeRange (400) | from is after to. |
TimeRangeExceeded (400) | Window longer than 30 days. |
TimeOutOfRange (400) | A timestamp outside the supported range. |
RetentionExceeded (400) | from is older than the 90-day horizon; reconcile via /ids. |
InvalidStatus (400) | status is not one of the Appendix A values. |
InvalidPageSize (400) | pageSize outside 1–1000. |
InvalidContinuationToken (400) | Malformed/stale token; restart from the first page. |
Documents and downloads (/{id}, /{id}/xml, /{id}/tdd/xml, /{id}/pdf)
| Code | Meaning |
|---|---|
DocumentNotFound (404) | No such document for your tenant (for the TDD download: the TDD does not exist yet). |
| PDF rendition (404 / 400) | The PDF endpoint relays the generation service's problem details: 404 when the document does not exist, 400 when generation fails — branch on the HTTP status for this endpoint. |
Participant capabilities (/participants/{id}/capabilities)
| Code | Meaning |
|---|---|
ParticipantIdRequired (400) | The participant id is missing/blank. |
ParticipantNotRegistered (404) | The participant is not registered on the Peppol network — use email delivery. |
SmpQueryFailed (500) | The network lookup failed; retry later. |
Appendix D — Using the OpenAPI specification
The machine-readable contract ships alongside this guide as openapi.yaml
(OpenAPI 3.0.3). It contains every endpoint, schema, enum, and error shape described here, and
the operation ids (IntegrationUploadDocument, IntegrationListStatusChanges, …) are
stable — generated client method names will not change between releases without notice.
- Explore: import into Postman/Insomnia (both accept OpenAPI YAML directly) or view in any Swagger UI/Redoc instance.
- Generate a client: e.g.
openapi-generator-cli generate -i openapi.yaml -g csharp(orjava,typescript-fetch,python, …). - Stay current: the specification is versioned with the platform; breaking changes are announced ahead of time once the API is generally available.
Appendix E — Delivery retries and time bounds
Everything after the 201 is asynchronous, and every step retries automatically.
You never need to resubmit a document because it seems slow — resubmitting creates a
new document, and failures always surface as a document status in the feed. This
appendix describes the retry machinery and how long each stage can take. The timings are current
platform defaults — treat them as indicative operational behavior, not contract.
E.1 Durable acceptance
The 201 commits the document and its dispatch job in a single transaction (a
transactional outbox). An accepted document can therefore never be lost between acceptance and
dispatch: if a worker crashes mid-job, the job is reclaimed within a few minutes and re-run.
Processing is at-least-once and duplicate-safe toward the network.
E.2 Dispatch to the access point — the outbox retry mechanism
A background processor picks up queued dispatch jobs within seconds. Outcomes:
| Outcome at the access point | What happens |
|---|---|
| Accepted | The delivery leg advances; Unibox now waits for the network's message-level acknowledgment (E.3). |
| Rejected (4xx — the document is the problem) | Permanent, no retry: the document moves to ValidationError. Fix and submit as a new document. |
| Transient failure (5xx, network, timeout) | The attempt is rolled back and retried with exponential backoff — roughly 20 s, 40 s, 80 s, 160 s between attempts, five attempts in total (≈5 minutes). Short access-point outages are absorbed invisibly. |
| All five attempts fail | The job is parked for operator intervention; the document currently remains in New. (Automatic surfacing of this rare case as SendingError is planned.) |
E.3 Awaiting the network acknowledgment — the SLA watchdog
A successful dispatch is acknowledged by the Peppol network with a message-level status. A watchdog sweeps every 60 seconds for documents whose acknowledgment is overdue:
- Invoice delivery: no acknowledgment within 10 minutes of dispatch → the document is automatically re-transmitted (a fresh transmission, duplicate-safe). Up to 3 re-transmissions, each with a fresh 10-minute window. If the network is still silent after that, the document moves to
SendingErrorwith a status-change event — and if a tax report had already been acknowledged for it, Unibox automatically files the corresponding withdrawal with the tax authority. Net effect: a silently failing access point surfaces asSendingErrorwithin roughly 45 minutes; an actively rejecting one surfaces as soon as its rejection arrives. - Tax reporting: no acknowledgment from the tax authority within 15 minutes → the report is re-transmitted from the stored XML, and this repeats indefinitely (with internal alerting as attempts accumulate). The regulation requires retrying until acknowledged, so there is no time-based give-up on the tax leg.
E.4 Tax report sending failures
The tax report itself is sent through the same outbox (same five-attempt backoff). If sending
permanently fails, the document moves to TaxReportError with a status-change event.
Combined with E.3, TaxReportError signals a definitive failure rather than a
timeout — which is why §9 advises monitoring rather than action: it is usually resolved
platform-side.
E.5 Webhooks
Webhook deliveries (§10.6) retry on the same exponential schedule with an extended budget — eight attempts over roughly 42 minutes — and are then dropped for that event. This is the reason webhooks are a latency optimization only: the polling feed is the reconciliation net that never loses an event inside its retention window.
Unibox Integration API — Integrator Guide, v1.0, 7 August 2026. Questions and onboarding support: your Unibox integration contact.