In diesem Artikel durchlaufen Sie die ersten Schritte zur Arbeit mit der PSB API: von der Beantragung eines Kontos bis zu Ihrem ersten API-Aufruf. Am Ende haben Sie eine funktionierende Verbindung zur Testumgebung und verstehen, wie die API aufgebaut ist.

Um die PSB API zu nutzen, benötigen Sie Credentials. Diese beantragen Sie über den Sandbox-Assistenten. Nach der Anmeldung erhalten Sie drei Angaben:

Tipp: Beantragen Sie Credentials direkt für die Akzeptanz- und die Produktionsumgebung. So können Sie sicher testen, ohne versehentlich echte Rechnungen zu versenden.

Je nach gewähltem OAuth2-Flow erhalten Sie möglicherweise auch einen username und ein password für den Resource Owner Password Credentials Flow. Für Server-zu-Server-Integrationen wird der Client Credentials Flow empfohlen, und Sie benötigen nur clientId und clientSecret.

Der PSB verfügt über zwei Umgebungen. Verwenden Sie die Akzeptanzumgebung für Entwicklung und Tests und die Produktionsumgebung für echte Transaktionen.

Die Akzeptanzumgebung funktioniert identisch zur Produktion: Token-Anfragen, API-Aufrufe und Webhooks verhalten sich gleich. Der Unterschied ist, dass Dokumente nicht an das echte Peppol-Netzwerk gesendet werden.

Wichtig: Verwenden Sie separate Credentials für Akzeptanz und Produktion. So verhindern Sie, dass Test-Credentials versehentlich in einer Produktionsumgebung landen.

Jede API-Anfrage an den PSB erfordert ein Bearer Token. Dieses Token fordern Sie beim Identity Server über eine POST-Anfrage an /connect/token an.

POST /connect/token HTTP/1.1
Host: accp-identity.econnect.eu
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=Ihre-client-id
&client_secret=Ihr-client-secret
&scope=ap

Bei Erfolg erhalten Sie eine JSON-Antwort mit dem Access Token:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "ap"
}

Das Token ist 3600 Sekunden (1 Stunde) gültig. Nach Ablauf fordern Sie einfach ein neues Token an. Der vollständige Authentifizierungsprozess, einschließlich des Resource Owner Password Credentials Flow und der Token-Erneuerung, wird im Authentifizierungsartikel beschrieben.

Mit einem gültigen Token können Sie die API aufrufen. Ein guter Startpunkt ist der GET /api/v1/me Endpoint, der Informationen über Ihr Konto und die damit verknüpften Organisationen (Parties) zurückgibt.

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

Eine erfolgreiche Antwort enthält Ihre Kontodaten und eine Liste der Parties, für die Sie autorisiert sind. Jede Party hat eine PartyId (zum Beispiel eine Handelsregisternummer oder OIN) und Berechtigungen, die bestimmen, was Sie tun dürfen: Dokumente senden, empfangen, löschen oder Hooks verwalten.

Sie können Dokumente in jedem Format einliefern, das der PSB unterstützt: UBL 2.1, NLCIUS, BIS Billing V3, PINT, CII, XRechnung, Factur-X, FatturaPA und mehr als 20 weitere Standards. Der PSB erkennt das Format automatisch und transformiert es in das Format, das der Empfänger erwartet. Sie müssen nicht wissen, welches Format der Empfänger verwendet.

Die PSB API gibt alle Antworten im JSON-Format zurück. Dokumente selbst (Rechnungen, Bestellungen) werden als XML gesendet und empfangen.

HTTP-Statuscodes folgen den üblichen REST-Konventionen:

Bei einem 4xx-Fehler enthält die Antwort eine Fehlermeldung, die angibt, was schiefgegangen ist. Bei 5xx-Fehlern empfiehlt es sich, die Anfrage mit exponentiellem Backoff erneut zu senden.

Der PSB kennt zwei Rollen, die bestimmen, was ein Benutzer tun darf.

ApUser ist die Standardrolle. Damit können Sie Dokumente senden und empfangen sowie Webhooks für die Parties verwalten, mit denen Sie verknüpft sind.

ApManager verfügt zusätzlich über Verwaltungsrechte: Benutzer anlegen und löschen, Organisationen im Peppol SMP/SML-Register registrieren und die Enrollment API nutzen, um neue Parties einzurichten.

Pro Party werden Berechtigungen einzeln festgelegt: canSendDocument, canReceiveDocument, canRemoveDocument und canManageHook. Jede registrierte Party muss mit mindestens einem ApUser-Konto verknüpft sein.

Die vollständige API-Referenz ist als Swagger UI unter psb.econnect.eu verfügbar. Dort können Sie Endpoints erkunden, Request- und Response-Formate einsehen und API-Aufrufe mit Ihrem eigenen Token testen. Die swagger.json ist ebenfalls herunterladbar, sodass Sie mit Tools wie OpenAPI Generator Client-Code in der Sprache Ihrer Wahl generieren können.