1.0.0
Ermittlung eines zuständigen Onlinedienst-Datenobjektes mit Hilfe der PVOG-API
Um die Daten eines Onlinedienst-Datenobjektes mit Hilfe der PVOG Suchdienst API zu ermitteln ist wie folgt vorzugehen:
1. Teilschritt: Ermittlung der ID der Leistungsbeschreibung
Siehe Abschnitt Ermittlung der ID der Leistungsbeschreibung
2. Teilschritt: Ermittlung der ID des Onlinedienstes
Der Onlinedienst benutzt den Endpunkt /v3/relations/{ars}/jzufi (öffnet in neuem Tab) mit den URL-Parametern ars = <der ARS> und lbids = <die in Schritt 1 ermittelte ID der Leistungsbeschreibung>. Zusätzlich muss der Onlinedienst einen validDate URL-Parameter angeben, um die Angaben auf diejenigen Top-Level-Elemente zu beschränken, die zum angegebenen Zeitpunkt (in der Regel das Datum der Antragstellung) gültig sind.
Als Alternative zur Verwendung des Endpunktes /v3/relations/{ars}/jzufi (öffnet in neuem Tab) bietet es sich an, die Response eines Aufrufs des Endpunktes /v5/servicedescriptions/{ars}/detail (öffnet in neuem Tab) auszuwerten. Dies gilt speziell dann, wenn dieser Endpunkt ohnehin bereits benutzt wurde, um Details der Leistungsbeschreibung zu ermitteln.
Die Response dieses Endpunktes enthält das Array onlineServiceLinks[] und darin wiederum onlineServiceLinks[]:id, das die ID des Onlinedienstes enthält.
Der Endpunkt /v5/servicedescriptions/{ars}/detail (öffnet in neuem Tab) filtert jedoch mindestens diese Liste der Onlinedienste nach der gewünschten Sprache, die beim Aufruf im Header accept-Language übergeben wurde. Wenn ein Onlinedienst nicht die in diesem Header angegebene Sprache in seiner Angabe sprachversion eingetragen hat, so wird er aus onlineServiceLinks[] ersatzlos gestrichen. Insbesondere wird nicht eine anderssprachige Variante des Onlinedienstes als Fallback für die gewünschte Sprache aufgeführt.
Der Endpunkt /v5/servicedescriptions/{ars}/detail (öffnet in neuem Tab) sollte daher zur Identifikation des Onlinedienstes nur dann genutzt werden, wenn sichergestellt ist, dass der accept-Language Header nicht mitgesendet wird oder die Sprache de enthält. Nur für Deutsch kann sicher angenommen werden, dass die Daten vorhanden sind.
Die Response enthält ein Element content[]:zustaendigkeit[],dessen Element id:schemeID den Wert "ZustaendigkeitOnlinedienst" hat. Dieses Element wird im Weiteren ausgewertet.
Zur Bestimmung der ID sind zwei Wege möglich:
2a. Bestimmung der OnlinedienstID aus den Elementen der zustaendigkeit
Das Element content[]:zustaendigkeit[]:id:value enthält als Wert einen String aus drei Segmenten, jeweils durch einen Punkt „.“ getrennt:
<LeistungId>.<OnlinedienstShortId>.<ARS>
Daneben findet sich ein Element content[]:zustaendigkeit[]:id:schemeAgencyId dessen Wert <SchemaAgencyId> benötigt wird.
Die ID des Onlinedienstes ergibt sich nun durch Konkatenation aus drei Bestandteilen mit dem Trennzeichen „.“:
OnlinedienstID = <SchemaAgencyId>.OD.<OnlinedienstShortId>
2b. Bestimmung der OnlinedienstID aus den Elementen der uebergeordnetesObjektId
Das content[]-Element, dessen zustaendigkeit[] ein Element enthält, dessen Element id:schemeID den Wert "ZustaendigkeitOnlinedienst" hat, enthält neben dem zustaendigkeit[]-Element auch ein uebergeordnetesObjektId-Element. Die Werte <SchemaAgencyId> des Elements uebergeordnetesObjektId:schemeAgencyId und <OnlinedienstShortId> des Elements uebergeordnetesObjektId:value werden benötigt, um die OnlinedienstID zu bilden:
Die ID des Onlinedienstes ergibt sich wieder durch Konkatenation aus drei Bestandteilen mit dem Trennzeichen „.“:
OnlinedienstID = <SchemaAgencyId>.OD.<OnlinedienstShortId>
3. Teilschritt: Ermittlung der der Daten des zuständigen Onlinedienstes
Mit dieser OnlinedienstID kann dann über den Endpunkt /v2/onlineservices/detail (öffnet in neuem Tab) das Onlinedienst-Datenobjekt ausgelesen werden.
Der oben dargestellte Ablauf kann mehrere Onlinedienst-Datenobjekte liefern, die alle für die Leistungsbeschreibung im Gebiet des ARS zuständig sind. Dies kann insbesondere dann eintreten, wenn "Hilfsdienste" wie ein Onlinedienst zur Terminvereinbarung im PVOG für diese Leistung in diesem Gebiet hinterlegt sind.
In diesem Fall muss der Onlinedienst alle identifizierten Onlinedienst-Datenobjekte vollständig auslesen und bei jedem dieser Datenobjekte den Parameter idOnlinedienstGlobal mit der eigenen Produkt-ID abgleichen. Nur genau eines der zuständigen Onlinedienst-Datenobjekt sollte eine passende idOnlinedienstGlobal haben.
Dies macht deutlich, dass die Eintragung von "Hilfsdiensten" wie Terminfindungsdiensten zwingend nach sich zieht, dass der Parameter idOnlinedienstGlobal für den eigentlichen Antragsdienst im Redaktionssystem gepflegt wird und dass der Onlinedienst (i.e. das IT-System) diesen Parameter dann auch wie hier beschrieben auswerten muss.
Auf die Angabe des zusätzlichen URL-Parameters validDate kann hier verzichtet werden, wenn bereits zu Beginn von Schritt 2 sichergestellt wurde, dass nur eine ID des Onlinedienstes identifiziert wurde, die auch zum gewünschten Zeitpunkt gültig ist. Die Angabe von validDate beim Aufruf von /v2/onlineservices/detail (öffnet in neuem Tab) entfernt Stand Q2/2024 nicht die Unter-Elemente des Onlinedienstes mit eigener gueltigkeit wie z.B. relations, die zum angegebenen Zeitpunkt nicht gültig sind. Diese Prüfung und Datenbereinigung muss der Onlinedienst selbst durchführen.