IF_041 – Leistungen erfassen

Der Sammlerdienst nutzt diese Schnittstelle, um Änderungen am Gesamtdatenbestand an den Bereitstelldienst zu übertragen.

Endpunkte

Die Datenänderungen werden über eine REST API übertragen. Die Tabelle enthält alle geplanten Endpunkte:

HTTP Methode	URL	Beschreibung
POST	/{version}/sammlerdienst/import	Importiert Verwaltungsobjekte vom Sammlerdienst.

Authentifizierung

Der Zugriff auf diese Schnittstelle ist nur für berechtigte Nutzer möglich. Aktuell ist nur der Sammlerdienst berechtigt. Die Berechtigungsprüfung durch den Bereitstelldienst erfolgt auf Basis eines OpenID Connect Access Tokens, das der Sammlerdienst beim Aufruf der Schnittstelle mitliefern muss. Detaillierte Informationen bzgl. des Anmeldeverfahrens können dem Dokument „PVOG-Berechtigungsmanagementkonzept“ (öffnet in neuem Tab, Download) entnommen werden.

Verschlüsselung der Übertragungswege

Der Zugriff auf die Schnittstelle muss über eine verschlüsselte Verbindung erfolgen, um ausschließen zu können, dass die Daten während der Übertragung manipuliert werden können. Die Verschlüsselung der Übertragungswege erfolgt auf Basis von TLS (mindestens Version 1.2).

Anfrageparameter

Siehe Abschnitt Nachrichtenformat.

Nachrichtenformat

Die Übertragung der Datenänderungen am Gesamtdatenbestand erfolgt durch direkte Weitergabe vom Sammlerdienst an Bereitstelldienst und Suchdienst. Die Daten werden als XZuFi Transfernachricht im Body der HTTP-Anfrage übergeben werden. Die XZuFi-Spezifikation ist versioniert und zeitweise werden in PVOG mehrere Versionen der XZuFi-Spezifikation unterstützt. Stand 2025 sind das die Versionen 2.2.0 und 2.3.1. Das konkrete Format der Transfernachricht hängt von der Version ab, in der die Daten im Sammlerdienst vorliegen. Pro Transfernachricht müssen die enthaltenen Daten natürlich alle die gleiche Version haben.

Eine Transfernachricht ist ein Objekt vom Typ transfer.operation.040502 (XZuFi 2.2.0, bei späteren Versionen ändert sich die Nummer), welches wiederum Leistungen, Leistungsspezialisierungen, Organisationseinheiten, Onlinedienste, Formulare und Zuständigkeiten in der jeweiligen XZuFi-Version enthält. Eine Transfernachricht kann eine variable Anzahl dieser Verwaltungsobjekte enthalten, aber eine Nachricht kann nur Verwaltungsobjekte enthalten, die keine Referenz auf andere Verwaltungsobjekte enthalten oder Verwaltungsobjekte referenzieren, die in der gleichen Nachricht enthalten sind oder in einer vorherigen Nachricht übertragen wurden. Im XZuFi wird für jedes Verwaltungsobjekt spezifiziert, ob es sich um eine CREATEUPDATE oder DELETE Operation handelt.

Rückgabecodes

Der REST-Endpunkt für das Erfassen von Leistungen antwortet mit den folgenden HTTPStatuscodes auf eingehende Anfragen:

HTTP Statuscode	Bedeutung
200	Daten erfolgreich empfangen.
400	Fehler in der Anfrage.
401	Autorisierung gegenüber Keycloak fehlt.
403	Berechtigung für den Zugriff auf den Endpunkt fehlt.
500	Interner Fehler bei der Verarbeitung der Anfrage.