Getting started with the eConnect PSB API: first steps, test environment and your first API call.
In this article you will walk through the first steps to start working with the PSB API: from requesting an account to making your first API call. By the end you will have a working connection to the test environment and understand how the API is structured.
To use the PSB API you need credentials. You request them via the contact form on the PSB product page at econnect.eu. After signing up you will receive three details:
clientIdclientSecretsubscriptionKeyTip: request credentials for both the acceptance and production environments straight away. This way you can test safely without accidentally sending real invoices.
Depending on the chosen OAuth2 flow, you may also receive a username and password for the Resource Owner Password Credentials flow. For server-to-server integrations the Client Credentials flow is recommended and you only need the clientId and clientSecret.
The PSB has two environments. Use the acceptance environment for development and testing, and the production environment for real transactions.
https://accp-psb.econnect.euhttps://psb.econnect.euhttps://accp-identity.econnect.euhttps://identity.econnect.euhttps://accp-vpd.econnect.eu/graphql/v1https://vpd.econnect.eu/graphql/v1@accp.econnect.email@econnect.emailThe acceptance environment works identically to production: token requests, API calls and webhooks behave the same. The difference is that documents are not sent to the real Peppol network.
Note: use separate credentials for acceptance and production. This prevents test credentials from accidentally ending up in a production environment.
Every API request to the PSB requires a Bearer token. You request that token from the Identity Server via a POST request to /connect/token.
POST /connect/token HTTP/1.1
Host: accp-identity.econnect.eu
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
&client_id=your-client-id
&client_secret=your-client-secret
&scope=ap
On success you receive a JSON response containing the access token:
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"expires_in": 3600,
"token_type": "Bearer",
"scope": "ap"
}
The token is valid for 3600 seconds (1 hour). After it expires you simply request a new token. The full authentication process, including the Resource Owner Password Credentials flow and token renewal, is described in the authentication article.
With a valid token you can call the API. A good starting point is the GET /api/v1/me endpoint, which returns information about your account and the organisations (parties) linked to it.
GET /api/v1/me HTTP/1.1
Host: accp-psb.econnect.eu
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
A successful response contains your account details and a list of parties you are authorised for. Each party has a PartyId (for example a Chamber of Commerce number or OIN) and permissions that determine what you can do: send documents, receive documents, delete documents or manage hooks.
You can submit documents in any format the PSB supports: UBL 2.1, NLCIUS, BIS Billing V3, PINT, CII, XRechnung, Factur-X, FatturaPA and more than 20 other standards. The PSB auto-detects the format and transforms it to the format the recipient expects. You do not need to know which format the recipient uses.
The PSB API returns all responses in JSON format. Documents themselves (invoices, orders) are sent and received as XML.
HTTP status codes follow standard REST conventions:
For a 4xx error the response contains an error message indicating what went wrong. For 5xx errors it is advisable to retry the request with exponential backoff.
The PSB has two roles that determine what a user can do.
ApUser is the default role. It allows you to send and receive documents, and manage webhooks for the parties you are linked to.
ApManager additionally has administrative rights: creating and deleting users, registering organisations in the Peppol SMP/SML registry, and using the Enrollment API to set up new parties.
Permissions are configured per party: canSendDocument, canReceiveDocument, canRemoveDocument and canManageHook. Each registered party must be linked to at least one ApUser account.
The full API reference is available as a Swagger UI at psb.econnect.eu. There you can explore endpoints, view request and response formats and test API calls with your own token. The swagger.json is also downloadable, so you can use tools such as OpenAPI Generator to generate client code in the language of your choice.
View the interactive API documentation