Deze gids is je startpunt als developer: van sandbox-aanvraag tot een werkende end-to-end flow met token, eerste API-call, factuurverzending en webhooks. Werk altijd eerst in de acceptatieomgeving (accp- endpoints); productie-credentials zijn strikt gescheiden. Waarom de sandbox bestaat en wat je er commercieel mee kunt, lees je op Alles in één API.

Voordat je code schrijft, leg je vast welk documentformaat je verstuurt en hoe je het valideert. Deze sectie bevat daarvoor drie voorbereidende pagina's:

1. Documentformaten — welke formaten eConnect ondersteunt en welk formaat je kiest voor je integratie.
2. Voorbeeldfacturen — complete XML-voorbeelden (NLCIUS en BIS Billing 3.0) als structuur-template en testpayload.
3. Je eerste bestand valideren — controleer je XML met de gratis validator voordat je iets verstuurt.

Heb je een valide testbestand, doorloop dan de stappen hieronder om de PSB API aan te sluiten.

Om de PSB API te gebruiken heb je OAuth2-credentials nodig (clientId en clientSecret). Die vraag je aan via het contactformulier. Na afstemming over het type integratie (eigen koppeling, softwarekoppeling, white-label) maakt eConnect je credentials en testparty aan in het Peppol-testnetwerk.

Na goedkeuring ontvang je:

Voor server-naar-server integraties is de Client Credentials-flow standaard. Afhankelijk van je scenario ontvang je mogelijk ook een username en password voor de Resource Owner Password Credentials-flow.

Tip: vraag direct credentials aan voor zowel acceptatie als productie, zodat je na testen alleen endpoints hoeft te wisselen.

Houd in je configuratie twee gescheiden sets: één voor acceptatie, één voor productie.

De acceptatieomgeving gedraagt zich identiek aan productie: token-aanvragen, REST-calls en webhooks werken hetzelfde. Documenten verstuurd vanuit een testaccount blijven op het Peppol-testnetwerk en bereiken geen echte ontvangers.

Elk API-verzoek vereist een Bearer-token. Vraag dat aan bij de Identity Server:

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 access_token met een geldigheid van 3600 seconden. Het volledige authenticatiepad, inclusief tokenvernieuwing en multi-tenant scenario's, staat in Authenticatie.

Controleer je verbinding met GET /api/v1/me:

GET /api/v1/me HTTP/1.1
Host: accp-psb.econnect.eu
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Een succesvolle response bevat je accountgegevens en de party's waarvoor je gemachtigd bent, inclusief permissies (canSendDocument, canReceiveDocument, canManageHook). De interactieve API Reference laat je endpoints verkennen en testcalls doen met je token.

Verstuur een testfactuur naar je eigen testparty of een testreceiver in de sandbox:

POST /api/v1/{partyId}/salesInvoice/send

Vervang {partyId} door de Peppol-identifier van de verzendende organisatie. De body is het XML-document (Content-Type: application/xml). De PSB valideert, transformeert en routeert het document; je ontvangt een document-ID in de response. Een kant-en-klare testpayload vind je bij de voorbeeldfacturen.

Aanbevolen voor je eerste test:

1. Controleer de ontvanger via queryRecipientParty (zie Factuur verzenden)
2. Stuur een UBL- of NLCIUS-factuur naar je eigen testparty
3. Gebruik X-EConnect-DocumentId met een UUID om dubbele verwerking te voorkomen (zie Idempotency)

Let op: het EndpointID in je XML bepaalt de ontvanger. Een ontbrekend of onjuist ID levert InvoiceSentError op.

Registreer een webhook voor statusupdates na verzending. De PSB stuurt bij relevante gebeurtenissen een HTTP POST naar jouw endpoint met een JSON-payload.

Minimaal voor je eerste end-to-end test:

1. Registreer een hook met topic InvoiceSent (of InvoiceReceived bij ontvangst) via de hooks-API
2. Zorg dat je endpoint binnen 100 seconden een 2xx-response teruggeeft
3. Verifieer de HMAC SHA256-handtekening op inkomende requests

Het volledige configuratiepad, topics en beveiliging staan in Webhooks instellen. Na een geslaagde factuurverzending ontvang je doorgaans een webhook met de afleveringsstatus.

• SDK's en CLI — officiële PHP- en .NET-SDK's, OpenAPI-codegen en de ClientConnector CLI voor productie-integraties.
• Validate API — valideer documenten in je pipeline zonder ze op te slaan of te routeren.
• Foutafhandeling — retries en monitoring voor een productie-stabiele integratie.
• API Reference — interactieve OpenAPI/Swagger-referentie met alle endpoints en modellen.