Skip to main content

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 version1.0
Document date7 August 2026
Machine-readable contractopenapi.yaml (OpenAPI 3.0.3, ships alongside this guide)
AudienceERP and system integrators building server-to-server connections to Unibox

Contents​

  1. Overview and concepts
  2. Getting started
  3. Authentication
  4. Error handling
  5. Idempotent submission
  6. Choosing the delivery route
  7. Pre-flight validation
  8. Submitting documents
  9. The document lifecycle
  10. Tracking and synchronization
  11. Downloading document renditions
  12. Limits, paging, and retention

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​

ConceptMeaning
Business documentOne 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).
ParticipantAn 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.
StatusEach 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.
TenantYour 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​

EndpointPurpose
GET /api/business-document/meVerify the key; identify the tenant
GET /api/business-document/participants/{id}/capabilitiesIs the receiver on Peppol, and what can it receive? (public — no API key)
POST /api/business-document/validateDry-run PINT-AE validation, nothing stored
POST /api/business-document/uploadSubmit UBL XML for Peppol delivery
POST /api/business-document/upload-non-peppolSubmit UBL XML for email delivery
POST /api/business-document/upload-excelSubmit an Excel workbook (Unibox template)
GET /api/business-document/templates/excelDownload the current Excel templates (zip)
GET /api/business-document/status-changesDelta-sync feed of every status transition
GET /api/business-document/idsBackfill / reconciliation listing by creation date
GET /api/business-document/{id}Full document detail
GET /api/business-document/{id}/xmlDownload the document XML
GET /api/business-document/{id}/tdd/xmlDownload the tax data document XML
GET /api/business-document/{id}/pdfDownload 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​

  1. GET /me returns your expected tenant.
  2. Validate a sample invoice with POST /validate until it is valid: true.
  3. Look up your test receiver with the capabilities endpoint.
  4. Submit with POST /upload (or /upload-non-peppol), storing the returned document id and your idempotency key.
  5. Implement the status-change polling loop (section 10.3) and confirm you observe the document reaching Exchanged and TaxReported.
  6. Handle the failure statuses (ValidationError, SendingError, ReceiverValidationError, TaxReportError) — read the structured error list from GET /{id}.
  7. 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 401 with 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). The detail texts are for humans and may be reworded.

4.1 Status codes​

StatusMeaningRecommended handling
400The 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).
401Missing/invalid API key.Check key configuration; alert an operator.
404Resource does not exist (or belongs to another tenant); for capabilities: participant not on Peppol.Business-level handling (e.g. fall back to email delivery).
409The 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.
500Unexpected 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, a 500, …) the same key can be submitted again once the problem is fixed.

5.1 What a repeated key receives​

You send the same key…ResponseMeaning
while the first request is still processing409, empty bodyWait briefly, then retry with the same key.
after the first attempt failedprocessed normallyThe key was not consumed; this new response is authoritative.
within 24 h after the first attempt succeeded400, 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 201409, problem details, code BusinessDocument.IdempotencyKeyAlreadyUsedThe 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; documentTypes lists what its access point accepts. Route to /upload.
  • 404 (ParticipantNotRegistered) — not on the Peppol network. Route to /upload-non-peppol.
  • businessCard is 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:

  • valid is true when there are no ERROR-severity findings. WARNINGs do not block submission but are worth reviewing.
  • XSD-stage findings carry the Xerces cvc-* rule id and a line/column location; 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) and document-type-unknown (cbc:CustomizationID missing or unrecognised). These are still HTTP 200 with valid: 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 fieldRequiredDescription
UblFileyesUBL XML file (.xml); root element Invoice or CreditNote
CountryCodenoISO 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:

StatusWhat happenedYour next step
ValidationErrorThe document failed PINT-AE validation.GET /{id} → errors[] lists the violations. Fix and submit as a new document (new idempotency key).
ReceiverValidationErrorThe receiving side rejected the document.Inspect errors[]; correct and resubmit as a new document.
SendingErrorDelivery to the receiver failed.Inspect errors[]. Depending on cause, resubmit or contact support.
TaxReportErrorDelivery 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:

ToolUse for
GET /status-changesStaying in sync — the delta feed of every transition; poll it on a schedule.
GET /idsBackfill 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/to are UTC date-times, both inclusive; the window may span at most 30 days and defaults to the last 30.
  • status filters on the transition's new status (case-insensitive; values in Appendix A).
  • The feed serves the last 90 days. A from older than that returns 400 RetentionExceeded — 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 seen set 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 = lastPollUtc exactly (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, dateTo inclusive, at most 31 days, defaults to the last 31.
  • Rows include both directions; each row's status and lastChangedUtc reflect the current state, so a full reconciliation pass is: page through the window, compare statuses with your system, drill into differences with GET /{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=Download GET /api/business-document/{id}/tdd/xml?downloadFileMode=Download GET /api/business-document/{id}/pdf?downloadFileMode=Download

  • All three accept downloadFileMode: Download (default) adds a Content-Disposition attachment header with the file name; Inline streams the body without one.
  • /xml returns the document's UBL XML (application/xml) — for outgoing documents the submitted payload, for incoming documents the received one.
  • /tdd/xml returns the Tax Data Document reported to the tax authority; it responds 404 until the TDD has been generated.
  • /pdf returns 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.
  • 404 also covers ids that don't exist or belong to another tenant.

12. Limits, paging, and retention​

SubjectValue
Page size (both listings)1–1000, default 500
Status-change feed window≤ 30 days per request (UTC date-times, inclusive)
Status-change feed horizonLast 90 days; older ⇒ 400 RetentionExceeded, reconcile via /ids
Ids listing window≤ 31 days per request (whole UTC days, dateTo inclusive)
Idempotency-key reuse rejection400 within 24 h of the successful submission, 409 naming the document id afterwards (chapter 5) — the original response is never replayed
Recommended feed polling interval1–5 minutes (with the 60-second overlap)
Rate limitingNone 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​

StatusMeaningTerminal?
NewAccepted and processing (validation / dispatch pending).no
ValidationErrorFailed PINT-AE validation in Unibox.yes (resubmit corrected document)
ReceiverValidationErrorRejected by the receiving side.yes (resubmit corrected document)
ExchangedDelivered to the receiver.no (tax reporting follows)
TaxReportedReported to the tax authority.yes — success
SendingErrorDelivery to the receiver failed.yes (investigate via errors[])
TaxReportErrorTax reporting failed after delivery.monitor / escalate

Appendix B — Document types​

ValueMeaning
InvoiceCommercial invoice (UNTDID 1001 code 380)
CreditNoteCredit note (381)
SelfBillingInvoiceSelf-billed invoice (389)
SelfBillingCreditNoteSelf-billed credit note (261)
InvoiceOutOfScopeOfVatInvoice out of scope of VAT (480)
CreditNoteGoodsAndServicesCredit 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)​

CodeMeaning
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)​

CodeMeaning
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)​

CodeMeaning
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)​

CodeMeaning
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)​

CodeMeaning
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)​

CodeMeaning
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 (or java, 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 pointWhat happens
AcceptedThe 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 failThe 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 SendingError with 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 as SendingError within 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.