Getting started

Hubix exchanges business documents, such as e-invoices, on the networks your customers and partners use: Peppol, consumers' e-faktura and Kivra inboxes, and partner operator networks. The Hubix APIs let your system send and receive documents on them, and register the companies that do. This page covers what every API has in common; each area's own getting started page takes it from there.

How this portal is organized

• Areas. APIs lists the areas Hubix covers, such as Peppol or B2C. An area opens on its own guides, with its APIs listed beside them.
• APIs. Each API has a Documentation tab with its guides and an API reference tab with every operation, its parameters, responses and code samples. An API with more than one version also has a Changes tab, listing what changed from the version before.
• Search. The search box at the top searches these general docs. To search an area's guides and its APIs' docs, use the search below the area's title.

Before you start

• An access token. Every call carries a bearer token issued to your organization's API client: Authorization: Bearer <token>. A call without a valid token is answered 401, and a token that does not give access to an operation 403.
• An API version. Send the version you are written against with ?api-version= or the x-api-version header. Without either, a call is answered as version 1.0, so an API whose current version is 2 needs it on every call. Each API's page shows its versions.

Your first request

A request carries the token and the version, and a JSON body is sent as application/json:

POST /peppol/participants?api-version=2
Authorization: Bearer <token>
Content-Type: application/json
IdempotencyKey: 3f2b8c1e-6d4a-4f7e-9b0c-2a5d8e1f4c67

{ ... }

The API reference has the body each operation takes, and a code sample for it in several languages.

Writes you can safely retry

A write that can be retried takes an IdempotencyKey header, and the API reference marks the operations that do. Generate a new key, a V4 UUID, for each operation you mean to perform, and send the same key again when you retry it:

• A new key: the operation is carried out, and its result stored with the key.
• The same key and the same body: the operation is not carried out again; you get the stored result.
• The same key with a different body: the request is rejected, since a key belongs to one request.
• No key, or one that is not valid: the request is rejected where the operation requires one.

Idempotency-Key is accepted as the same header.

Operations that take time

Some operations, such as registering a participant, carry on after the request is answered. They answer with a Location header, often with 202 Accepted while the work is still under way: read that resource with GET until its status shows the operation is done. The operation's guide says which status that is.

When something goes wrong

Every API answers errors the same way, as problem details. Errors describes the format and the status codes any operation can answer. Retry a 429, 502, 503 or 504 after a delay, backing off between attempts, and after a 429 wait the number of seconds in Retry-After first. When you contact support about an error, quote the traceId it carries.

Next steps

• Browse the APIs, and open the area you are integrating with. Its getting started page walks through the first calls.
• Read Errors before you write your error handling.