/ docs
ProduktWissenEntwickler
Plattform Control
Peppol-Registrierung über die API

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.

Voraussetzungen

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.

RolleBerechtigungenApUserRechnungen und Bestellungen senden/empfangen, Hooks für eigene Party verwaltenApManagerAlles von ApUser, plus: Party-Registrierungen, SMP-Verwaltung, Enrollment
Der Enrollment-Endpoint
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.

1. Services

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": { "value": "Bedrijfsnaam B.V.", "state": "on" },
        "address": { "value": "Voorbeeldstraat 1, 1234 AB, Utrecht, NL", "state": "on" },
        "emailAddress": { "value": "info@bedrijf.nl", "state": "on" },
        "state": "on"
      }
    }
  }
}

Die businessCard ist optional, wird aber empfohlen. Ohne businessCard ist die Party nicht im Peppol Directory auffindbar, auch wenn die SMP-Registrierung aktiv ist. Wenn Sie eine businessCard veröffentlichen, sind names und eine address mit Ländercode Pflicht. Die PSB leitet diese Felder nicht aus dem Handelsregister ab.

2. Party authorizations

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
      }
    }
  ]
}
BerechtigungBeschreibungcanSendDocumentDokumente im Namen dieser Party versendencanReceiveDocumentDokumente für diese Party empfangencanRemoveDocumentEmpfangene Dokumente löschencanManageHookHooks für diese Party erstellen und verwalten
3. Hooks

Optional 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"]
    }
  ]
}
Vollständiges Beispiel

Ein kompletter Enrollment-Request, der alle drei Bestandteile kombiniert:

{
  "services": {
    "peppol": {
      "capabilities": {
        "invoices": "on",
        "invoiceResponse": "on"
      },
      "businessCard": {
        "names": { "value": "Voorbeeld B.V.", "state": "on" },
        "address": { "value": "Keizersgracht 1, 1015 AA, Amsterdam, NL", "state": "on" },
        "state": "on"
      }
    }
  },
  "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"]
    }
  ]
}
Eine Registrierung entfernen

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.

Hinweise

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.

Nach einem erfolgreichen PUT /api/v1-beta/{partyId}/enroll ist die Registrierung sofort in der Peppol-SML verarbeitet. Ein Absender kann einen Lookup-Cache haben, der zuerst aktualisiert werden muss. Das Peppol Directory ist nicht sofort aktuell, wegen des eigenen Indexers. In manchen Fällen dauert das einige Minuten.

Möchten Sie bestehende Registrierungen von einem anderen Provider übernehmen? Lesen Sie dann den Artikel über die Migration zu eConnect.

In der API ausprobieren

Verwandt
PreviousPeppol-Lookup
NextMigration