Organisationen über die Enrollment API auf Peppol registrieren: Services, Berechtigungen und Hooks in einem Aufruf.
Die Enrollment API ist eine Komplettlösung für die Registrierung einer neuen Party im Peppol-Netzwerk. In einem einzigen API-Aufruf konfigurieren Sie den Peppol-Service, verknüpfen Benutzer mit den richtigen Berechtigungen und richten optional Hooks ein. Dieser Artikel beschreibt den Endpoint, die drei Bestandteile der Enrollment und das Entfernen einer Registrierung.
Die Enrollment API erfordert die ApManager-Rolle. Ein ApUser kann kein Enrollment durchführen. Überprüfen Sie vor Beginn, ob Ihre API-Zugangsdaten die richtige Rolle haben.
PUT /api/v1-beta/{partyId}/enroll
Die {partyId} ist der Peppol-Identifier der zu registrierenden Party, im Format schemeID:identifier (z.B. 0106:12345678).
Der Request Body enthält drei Abschnitte: Services, Party authorizations und Hooks.
Im Services-Abschnitt aktivieren Sie den Peppol-Service für die Party. Sie konfigurieren die SMP-Capabilities (welche Dokumenttypen die Party empfangen kann) und optional eine businessCard für die Veröffentlichung im Peppol Directory.
{
"services": {
"peppol": {
"capabilities": {
"invoices": "on",
"invoiceResponse": "on",
"orderOnly": "inherited"
},
"businessCard": {
"names": "Bedrijfsnaam B.V.",
"geoInfo": "Utrecht, NL",
"email": "info@bedrijf.nl"
}
}
}
}
Die businessCard ist optional, wird aber empfohlen. Ohne businessCard ist die Party nicht im Peppol Directory auffindbar, auch wenn die SMP-Registrierung aktiv ist.
Hier verknüpfen Sie einen oder mehrere Benutzer mit der Party und definieren deren Berechtigungen. Jede registrierte Party muss mit mindestens einem ApUser verknüpft sein.
{
"partyAuthorizations": [
{
"userId": "gebruiker@bedrijf.nl",
"permissions": {
"canSendDocument": true,
"canReceiveDocument": true,
"canRemoveDocument": true,
"canManageHook": true
}
}
]
}
canSendDocumentcanReceiveDocumentcanRemoveDocumentcanManageHookOptional können Sie direkt Hooks für die neue Party registrieren. Das ist praktisch, wenn Sie bei der Registrierung bereits wissen, welche Benachrichtigungen benötigt werden, beispielsweise einen Webhook für empfangene Rechnungen.
{
"hooks": [
{
"action": "https://api.bedrijf.nl/webhooks/invoices",
"topics": ["InvoiceReceived"]
},
{
"action": "mailto:facturatie@bedrijf.nl",
"topics": ["InvoiceReceived"]
}
]
}
Ein kompletter Enrollment-Request, der alle drei Bestandteile kombiniert:
{
"services": {
"peppol": {
"capabilities": {
"invoices": "on",
"invoiceResponse": "on"
},
"businessCard": {
"names": "Voorbeeld B.V.",
"geoInfo": "Amsterdam, NL"
}
}
},
"partyAuthorizations": [
{
"userId": "api-user@voorbeeld.nl",
"permissions": {
"canSendDocument": true,
"canReceiveDocument": true,
"canRemoveDocument": false,
"canManageHook": true
}
}
],
"hooks": [
{
"action": "https://api.voorbeeld.nl/leren/peppol/incoming",
"topics": ["InvoiceReceived"]
}
]
}
Um eine Party vollständig zu deregistrieren (einschließlich aller Services, Berechtigungen und Hooks), verwenden Sie:
DELETE /api/v1-beta/{partyId}/enroll
Nach dem Entfernen ist die Party nicht mehr im Peppol-Netzwerk erreichbar und alle verknüpften Hooks und Autorisierungen werden aufgeräumt.
Die Enrollment API ist ein Beta-Endpoint (v1-beta). Die Funktionalität ist stabil, aber der Endpoint kann sich in zukünftigen Versionen ändern. Bei Fragen zum Beta-Status können Sie sich an TechSupport wenden.
Beachten Sie außerdem, dass die SMP-Registrierung nach dem Enrollment einige Minuten dauern kann, bis sie im gesamten Peppol-Netzwerk synchronisiert ist. Dies ist dem SML/SMP-Protokoll inhärent.
Möchten Sie bestehende Registrierungen von einem anderen Provider übernehmen? Lesen Sie dann den Artikel über die Migration zu eConnect.
In der API ausprobieren