Änderungen abrufen (Provenance Search)

Inhalt

1. Beschreibung und fachlicher Kontext
2. Request
   • Request Header
   • Request Body
     • Suchparameter: Betriebsstättennummer (BSNR)
     • Suchparameter: Änderungszeitpunkt
     • Suchparameter: Anzahl der Suchergebnisse
     • Suchparameter: Seite der Suchergebnisse
   • Beispiele
3. Response
   • Response Header
   • Response Body
   • Beispiele

Beschreibung und fachlicher Kontext

Um zu gewährleisten, dass sich das Software-System kontinuierlich mit dem 116117 Terminservice synchronisieren (d.h., regelmäßig alle Änderungen an abrechnungsrelevanten Informationen abrufen) kann, wird ein Endpunkt zur Verfügung gestellt, der nur die letzten Änderungen an den im System des 116117 Terminservice gespeicherten Terminbuchungen zurückgibt.

Hierfür dient die spezielle Ressource Provenance, die eine entsprechende Struktur abbildet, um die letzte Änderung an einer Terminbuchung zu dokumentieren. Details hierzu sind auf der Seite Profil: Änderung (Provenance) zu finden.

Beim Abrufen der Provenances handelt es sich um die FHIR-Standardinteraktion search.

Generelle Hinweise, die für alle Interaktionen gelten, sind auf der Seite Interaktionen gelistet. Dort sind auch detailierte Informationen zum Thema Paging zu finden. Beim Paging ist zu beachten, dass sich die Gesamtzahl der Seiten zwischen dem Abruf von bspw. Seite 1 und Seite 2 ändern kann. Voraussetzung hierfür ist, dass zwischen den beiden Abrufen neue Provenances erzeugt oder bestehende Provenances (aufgrund von Löschfristen) aus dem 116117 Terminservice gelöscht wurden. Eine neue Provenance wird immer dann erzeugt, wenn eine der folgenden Aktionen vorgenommen wird:

• Erstellen eines neuen Appointments (durch die Buchung eines Termins)

• Aktualisieren eines bestehenden Appointments (bspw. durch die Absage eines Termins)

• Löschen eines bestehenden Appointments (bspw. aufgrund von gesetzlichen Löschfristen)

Beim Abrufen von Änderungen (Provenances) sind die Suchergebnisse über alle Seiten hinweg chronologisch sortiert, wobei die älteste Änderung als erstes in den Suchergebnissen erscheint und die neuste Änderung als letztes. Die Systeme des 116117 Terminservice stellen sicher, dass die Suchergebnisse, auch über mehrere Seiten hinweg, immer in exakt derselben Reihenfolge zurückgegeben werden – also auch dann, wenn zwei Änderungen zum selben Zeitpunkt vorgenommen wurden.

Request

Das Abrufen der Änderungen erfordert einen POST-Request. Es können entweder alle noch vorhandenen Änderungen an Terminbuchungen von allen autorisierten Einrichtungen oder nur bestimmte Änderungen (bspw. nur Änderungen an Terminbuchungen von bestimmten autorisierten Einrichtungen) anhand entsprechender Suchparameter im Request Body abgefragt werden (siehe hierzu Abschnitt Request Body).

Bitte beachten: Laut FHIR-Standard wäre auch eine Suche mit Suchparametern innerhalb der URL und/oder mittels GET-Request möglich. Dies wird durch die Systeme des 116117 Terminservices aktuell jedoch NICHT unterstützt. Ein GET-Request auf die oben angegebene URL führt zu einem Fehler. Suchparameter in der URL werden von den Systemen des 116117 Terminservices ignoriert, d.h. weder validiert noch verarbeitet.

Request Header

Folgende Request Header werden von den Systemen des 116117 Terminservices unterstützt und verarbeitet:

Request Body

Der Request Body muss alle Suchparameter enthalten, nach denen die Suchergebnisse gefiltert werden sollen.

In den folgenden Abschnitten werden die einzelnen Suchparameter im Detail beschrieben. Suchparameter, die hier nicht aufgelistet sind, aber dennoch im Request Body übergeben werden, werden von den Systemen des 116117 Terminservices ignoriert. Das bedeutet, dass die Systeme des 116117 Terminservice diese Suchparameter nicht verarbeiten. Es wird in diesem Fall kein Fehler geworfen; die Suche wird ohne die unbekannten Suchparameter durchgeführt.

Bitte beachten: Die Systeme des 116117 Terminservices prüfen bei Angabe mehrerer Suchparameter nur bedingt auf Plausibilität. Das bedeutet, dass nicht zwangsweise eine Fehlermeldung als Response zurückkommt, wenn sich mehrere Suchparameter gegenseitig ausschließen. Ein Beispiel hierfür sind UND-Verknüpfungen bei mehreren BSNRs, die nicht zu einem Praxisverbund gehören. In solchen Fällen kommt der HTTP-Statuscode 200 OK mit einem Searchset Bundle (im Response Body) zurück, welches KEINE Suchergebnisse enthält.

Suchparameter: Betriebsstättennummer (BSNR)

Suchparameter: Änderungszeitpunkt

Suchparameter: Anzahl der Suchergebnisse

Suchparameter: Seite der Suchergebnisse

¹ Wie Parameter mit UND bzw. ODER verknüpft werden können, ist in der HL7-FHIR-Dokumentation unter Search – Standard Parameters: Composite Search Parameters beschrieben.

² Die Präfixe sind in der HL7-FHIR-Dokumentation unter Search – Standard Parameters: Prefixes beschrieben.

Beispiele

Beispiel 1: Suche anhand einer BSNR

# Suche alle Provenances, die Änderungen an Terminbuchungen enthalten, die von der Praxis mit der BSNR 123456789 angeboten werden
POST https://abrechnungsinformation.eterminservice.kv-safenet.de/pvs​/abrechnungsinformation/api/Provenance/_search
Content-Type: application/x-www-form-urlencoded
bsnr=123456789

Beispiel 2: Suche anhand eines Änderungszeitpunktes

# Suche alle Provenances, die Änderungen an Terminbuchungen enthalten, deren Änderungszeitpunkt zeitlich nach dem 14.01.2024, 12:11:17 Uhr liegt
POST https://abrechnungsinformation.eterminservice.kv-safenet.de/pvs​/abrechnungsinformation/api/Provenance/_search
Content-Type: application/x-www-form-urlencoded
recorded=gt2024-01-14T12:11:17-01:00

Beispiel 3: Suche anhand einer BSNR und eines Änderungszeitpunktes

# Suche alle Provenances, die Änderungen an Terminbuchungen enthalten, die von der Praxis mit der BSNR 123456789 angeboten werden und wo der Änderungszeitpunkt zeitlich nach dem 14.01.2024, 12:11:17 Uhr liegt
POST https://abrechnungsinformation.eterminservice.kv-safenet.de/pvs​/abrechnungsinformation/api/Provenance/_search
Content-Type: application/x-www-form-urlencoded
recorded=gt2024-01-14T12:11:17-01:00&bsnr=123456789

Response

Für die Suche von Provenances wird im Erfolgsfall der HTTP-Statuscode 200 OK sowie ein Searchset Bundle im Response Body zurückgegeben.

• Wurden bei der Suche keine Suchparameter übergeben, enthält das zurückgegebene Searchset alle noch vorhandenen Provenanes mit Änderungen an Terminbuchungen der Haupt- und Nebenbetriebsstätten der in der Autorisierung übergebenen BSNR.

• Wurde bei der Suche min. ein Suchparameter übergeben, enthält dieses Searchset alle Provenances, die anhand der Suchparameter in Verbindung mit den autorisierten BSNRs ermittelt werden konnten.

Wie auf der Seite Interaktionen beschrieben, sortieren die Systeme des 116117 Terminservices die Suchergebnisse über alle Seiten hinweg. Dadurch wird sichergestellt, dass die Suchergebnisse auch bei mehrfachem Abschicken desselben Requests immer in derselben Reihenfolge zurückkommen. Dies gilt für alle Seiten der Suchergebnisse – also auch wenn bspw. der Änderungszeitpunkt des letzten Eintrags der ersten Seite exakt mit dem Änderungszeitpunkt des ersten Eintrags der zweiten Seite übereinstimmt.

Im Fehlerfall wird ein dem Fehler entsprechender HTTP-Statuscode (bspw. 400 Bad Request oder 500 Internal Server Error) sowie ein OperationOutcome im Response Body zurückgegeben. Dieses OperationOutcome enthält Details zum aufgetretenen Fehler.

Response Header

Folgende Response Header werden von den Systemen des 116117 Terminservices gesetzt und an den Anfragenden zurückgesendet:

Response Body

Im Erfolgsfall ist im Response Body ein Searchset Bundle enthalten, welches folgende Ressourcen und Informationen enthält:

• Suchergebnisse als Set (ohne Duplikate): Dieses Set kann auch leer sein, wenn anhand der gesetzten Suchparameter keine passenden Provenances gefunden werden konnten.

• Alle Suchparameter, die durch die Systeme des 116117 Terminservices verarbeitet und für die Suche genutzt wurden (im Element Bundle.link).

• Verweis auf die vorherige und / oder nächste Seite der Suchergebnisse, wenn vorhanden (im Element Bundle.link).

  • Bitte beachten: Hierbei handelt es sich um einen Verweis in Form einer URL – um die Seite tatsächlich abzurufen, muss jedoch ein POST-Request mit den Suchparametern im Request Body abgeschickt werden.

  • Details zum Thema Paging sind auf der Seite Interaktionen zu finden.

• In den Provenances referenzierte Ressourcen (im Element Provenance.target.reference), die neu angelegt oder aktualisiert wurden:

  • Terminbuchung (Appointment)

Details zum Searchset Bundle sind unter Profil: Suchergebnisse (Bundle) zu finden.

Bitte beachten:

• Wenn ein Appointment gelöscht wurde, ist das gelöschte Appointment NICHT im Response Body enthalten. Welches Appointment gelöscht wurde, kann anhand der ID identifiziert werden, die in der zugehörigen Provenance-Ressource im Feld Provenance.target.reference enthalten ist:

  • Der Wert im Feld Provenance.target.reference hat immer folgenden Aufbau: urn:uuid:[Appointment-ID]

  • Die Appointment-ID ist immer eine UUID und entspricht dem Wert des Feldes Appointment.id.

• Ressourcen, die in neu erstellten / geänderten Appointments referenziert werden (bspw. Patient und PractitionerRole), werden beim Abruf der Provenances NICHT mit zurückgegeben.

Im Fehlerfall ist im Response Body ein OperationOutcome enthalten. Details hierzu sind unter Profil: Fehler (OperationOutcome) zu finden.

Beispiele

Alle Beispiele für den Erfolgsfall sind hier im vorliegenden Projekt zu finden.

Alle Beispiele für den Fehlerfall sind hier im vorliegenden Projekt zu finden.