Organisaties registreren op Peppol via de Enrollment API: services, rechten en hooks in één call.
De Enrollment API is een one-stop-shop voor het registreren van een nieuwe party op het Peppol-netwerk. In één API-call configureer je de Peppol-service, koppel je gebruikers met de juiste rechten en stel je optioneel hooks in. Dit artikel beschrijft het endpoint, de drie onderdelen van de enrollment en het verwijderen van een registratie.
De Enrollment API vereist de ApManager-rol. Een ApUser kan geen enrollment uitvoeren. Controleer of je API-credentials de juiste rol hebben voordat je begint.
De integrerende partij is verantwoordelijk voor de end-user verification van elke party die via de Enrollment API wordt geregistreerd. Voordat je een partyId aanmeldt op Peppol, moet je hebben geverifieerd dat de eindklant daadwerkelijk de organisatie vertegenwoordigt die bij de opgegeven identifiers (KvK, OIN, BTW-nummer) hoort. EUV is een vereiste van het Peppol-netwerk en hoort thuis in je eigen onboardingflow voordat de enrollment-call wordt gedaan.
Voor Peppol-parties in Polen geldt aanvullend dat het KSeF-online- en/of -offline-certificaat bij de eindklant moet worden opgehaald voordat de bijbehorende KSeF-hook kan worden geconfigureerd. De certificaten worden inline meegegeven in het init-blok van de hook (zie KSeF hook). Zonder geldig certificaat van de eindklant is registratie en factuurregistratie via KSeF niet mogelijk.
PUT /api/v1-beta/{partyId}/enroll
De {partyId} is de Peppol-identifier van de te registreren party, in het formaat schemeID:identifier (bijv. 0106:12345678).
De request body bevat drie secties: Services, Party authorizations en Hooks.
In de Services-sectie activeer je de Peppol-service voor de party. Je configureert de SMP-capabilities (welke documenttypes de party kan ontvangen) en optioneel een businessCard voor publicatie in de Peppol Directory.
{
"services": {
"peppol": {
"capabilities": {
"invoices": "on",
"invoiceResponse": "on",
"orderOnly": "inherited"
},
"businessCard": {
"names": "Bedrijfsnaam B.V.",
"geoInfo": "Utrecht, NL",
"email": "[email protected]"
}
}
}
}
De businessCard is optioneel, maar aanbevolen. Zonder businessCard is de party niet vindbaar in de Peppol Directory, ook al is de SMP-registratie actief.
Hier koppel je een of meerdere gebruikers aan de party en definieer je hun rechten. Elke geregistreerde party moet aan minimaal één ApUser zijn gekoppeld.
{
"partyAuthorizations": [
{
"userId": "[email protected]",
"permissions": {
"canSendDocument": true,
"canReceiveDocument": true,
"canRemoveDocument": true,
"canManageHook": true
}
}
]
}
canSendDocumentcanReceiveDocumentcanRemoveDocumentcanManageHookOptioneel kun je direct hooks registreren voor de nieuwe party. Dit is handig als je bij registratie al weet welke notificaties nodig zijn, bijvoorbeeld een webhook voor ontvangen facturen.
{
"hooks": [
{
"action": "https://api.bedrijf.nl/webhooks/invoices",
"topics": ["InvoiceReceived"]
},
{
"action": "mailto:[email protected]",
"topics": ["InvoiceReceived"]
}
]
}
Een complete enrollment-request die alle drie de onderdelen combineert:
{
"services": {
"peppol": {
"capabilities": {
"invoices": "on",
"invoiceResponse": "on"
},
"businessCard": {
"names": "Voorbeeld B.V.",
"geoInfo": "Amsterdam, NL"
}
}
},
"partyAuthorizations": [
{
"userId": "[email protected]",
"permissions": {
"canSendDocument": true,
"canReceiveDocument": true,
"canRemoveDocument": false,
"canManageHook": true
}
}
],
"hooks": [
{
"action": "https://api.voorbeeld.nl/leren/peppol/incoming",
"topics": ["InvoiceReceived"]
}
]
}
Om een party volledig te deregistreren (inclusief alle services, permissies en hooks), gebruik je:
DELETE /api/v1-beta/{partyId}/enroll
Na het verwijderen is de party niet meer bereikbaar op het Peppol-netwerk en worden alle gekoppelde hooks en autorisaties opgeruimd.
De Enrollment API is een beta-endpoint (v1-beta). De functionaliteit is stabiel, maar het endpoint kan in toekomstige versies wijzigen. Bij vragen over de beta-status kun je contact opnemen met TechSupport.
Houd er ook rekening mee dat de SMP-registratie na de enrollment enkele minuten kan duren voordat deze op het volledige Peppol-netwerk is gesynchroniseerd. Dit is inherent aan het SML/SMP-protocol.
De Enrollment API vereist de ApManager-rol. Een ApUser heeft onvoldoende rechten om een enrollment uit te voeren. Controleer bij je API-credentials of de juiste rol is toegewezen. ApManager geeft daarnaast ook toegang tot party-registraties en SMP-beheer.
Na de enrollment kan het enkele minuten duren voordat de SMP-registratie volledig is gesynchroniseerd over het Peppol-netwerk. Dit is inherent aan het SML/SMP-protocol. In de tussentijd kan de party al wel documenten versturen, maar is ontvangst mogelijk nog niet overal bereikbaar.
Ja, de Enrollment API ondersteunt een optionele hooks-sectie in de request body. Je kunt direct bij registratie webhooks of mailhooks configureren, bijvoorbeeld een webhook voor InvoiceReceived. Zo is de party meteen operationeel na de enrollment, zonder dat je achteraf apart hooks hoeft in te stellen.
Wil je bestaande registraties van een andere provider overnemen? Lees dan het artikel over migratie naar eConnect.
Probeer het in de API