Aan de slag met de eConnect PSB API: eerste stappen, testomgeving en je eerste API-aanroep.
In dit artikel doorloop je de eerste stappen om met de PSB API te werken: van het aanvragen van een account tot het doen van je eerste API-aanroep. Aan het einde heb je een werkende verbinding met de testomgeving en weet je hoe de API is opgebouwd.
Om de PSB API te gebruiken heb je credentials nodig. Die vraag je aan via het contactformulier op de PSB-productpagina op econnect.eu. Na aanmelding ontvang je drie gegevens:
clientIdclientSecretsubscriptionKeyTip: vraag direct credentials aan voor zowel de acceptatie- als de productieomgeving. Zo kun je veilig testen zonder dat je per ongeluk echte facturen verstuurt.
Afhankelijk van de gekozen OAuth2-flow ontvang je mogelijk ook een username en password voor de Resource Owner Password Credentials-flow. Voor server-naar-server integraties is de Client Credentials-flow aanbevolen en heb je alleen clientId en clientSecret nodig.
De PSB heeft twee omgevingen. Gebruik de acceptatieomgeving voor ontwikkeling en testen, en de productieomgeving voor echte transacties.
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.emailDe acceptatieomgeving werkt identiek aan productie: token-aanvragen, API-calls en webhooks gedragen zich hetzelfde. Het verschil is dat documenten niet naar het echte Peppol-netwerk worden gestuurd.
Let op: gebruik aparte credentials voor acceptatie en productie. Zo voorkom je dat testcredentials per ongeluk in een productieomgeving terechtkomen.
Elk API-verzoek aan de PSB vereist een Bearer token. Dat token vraag je aan bij de Identity Server via een POST-verzoek naar /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=jouw-client-id
&client_secret=jouw-client-secret
&scope=ap
Bij succes ontvang je een JSON-response met daarin het access token:
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"expires_in": 3600,
"token_type": "Bearer",
"scope": "ap"
}
Het token is 3600 seconden (1 uur) geldig. Na het verlopen vraag je gewoon een nieuw token aan. Het volledige authenticatieproces, inclusief de Resource Owner Password Credentials-flow en tokenvernieuwing, staat beschreven in het authenticatie-artikel.
Met een geldig token kun je de API aanroepen. Een goed startpunt is het GET /api/v1/me endpoint, dat informatie teruggeeft over je account en de organisaties (party's) die eraan gekoppeld zijn.
GET /api/v1/me HTTP/1.1
Host: accp-psb.econnect.eu
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Een succesvolle response bevat je accountgegevens en een lijst van party's waarvoor je gemachtigd bent. Elke party heeft een PartyId (bijvoorbeeld een KvK-nummer of OIN) en permissies die bepalen wat je mag doen: documenten verzenden, ontvangen, verwijderen of hooks beheren.
Je kunt documenten aanleveren in elk formaat dat de PSB ondersteunt: UBL 2.1, NLCIUS, BIS Billing V3, PINT, CII, XRechnung, Factur-X, FatturaPA en meer dan 20 andere standaarden. De PSB detecteert het formaat automatisch en transformeert het naar het formaat dat de ontvanger verwacht. Je hoeft dus niet te weten welk formaat de ontvanger gebruikt.
De PSB API retourneert alle responses in JSON-formaat. Documenten zelf (facturen, orders) worden als XML verzonden en ontvangen.
HTTP-statuscodes volgen de standaard REST-conventies:
Bij een 4xx-fout bevat de response een foutmelding die aangeeft wat er mis is. Bij 5xx-fouten is het verstandig om het verzoek opnieuw te proberen met exponential backoff.
De PSB kent twee rollen die bepalen wat een gebruiker mag doen.
ApUser is de standaardrol. Hiermee kun je documenten verzenden en ontvangen, en webhooks beheren voor de party's waaraan je gekoppeld bent.
ApManager heeft daarnaast beheerrechten: gebruikers aanmaken en verwijderen, organisaties registreren in het Peppol SMP/SML-register, en de Enrollment API gebruiken om nieuwe party's in te richten.
Per party worden permissies apart ingesteld: canSendDocument, canReceiveDocument, canRemoveDocument en canManageHook. Elke geregistreerde party moet aan minimaal een ApUser-account gekoppeld zijn.
De volledige API-referentie is beschikbaar als Swagger UI op psb.econnect.eu. Daar kun je endpoints verkennen, request- en responseformaten bekijken en API-calls testen met je eigen token. De swagger.json is ook downloadbaar, zodat je met tools als OpenAPI Generator client code kunt genereren in de taal van je keuze.
Neem contact op met de salesafdeling van eConnect voor een testaccount. Na goedkeuring ontvang je OAuth2-credentials (client_id en client_secret) waarmee je toegang krijgt tot de acceptatieomgeving op accp-psb.econnect.eu.
ApUser is de standaardrol waarmee je documenten kunt verzenden en ontvangen en webhooks kunt beheren. ApManager heeft daarnaast beheerrechten: gebruikers aanmaken, organisaties registreren in het Peppol-register en de Enrollment API gebruiken.
Ja, de interactieve Swagger UI op psb.econnect.eu laat je endpoints verkennen, request- en responseformaten bekijken en API-calls testen met je eigen Bearer token, direct vanuit de browser.
Bekijk de interactieve API-documentatie