Ä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

Für die kontinuierliche Synchronisation mit dem 116117 Terminservice wird ein Endpunkt zur Verfügung gestellt, der nur die aktuellen Änderungen an den im 116117 Terminservice gespeicherten Terminbuchungen zurückgibt.

Um eine Änderung an einer Terminbuchung in FHIR abzubilden, wurde ein Provenance-Profil definiert. Eine Änderung kann dabei die Erstellung, Aktualisierung oder Löschung einer Terminbuchung sein. Details hierzu sind auf der Seite Profil: Änderung (Provenance) zu finden.

Bitte beachten: Aktuell besteht KEINE Möglichkeit, Änderungen an Patientendaten (bspw. das Hinzufügen einer E-Mail-Adresse) über diesen Endpunkt abzurufen. Die Patientendaten werden nur beim Abrufen von Terminbuchungen mit zurückgeliefert, da nur in der Terminbuchung selbst der zugehörige Patient referenziert wird. Daher wird empfohlen, die Terminbuchung noch einmal direkt (bspw. anhand ihrer ID) abzurufen, wenn die Patientendaten eingesehen werden sollen. Details hierzu sind unter Terminbuchungen abrufen (Appointment Search) zu finden.

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

Ein PVS kann automatisiert und in regelmäßigen Abständen alle aktuellen Provenances abrufen, um sich kontinuierlich mit dem 116117 Terminservice zu synchronisieren. Es ist dabei ausreichend, nur die Änderungen abzurufen, die seit dem letzten Abruf erfolgt sind. Der zeitliche Abstand zwischen den einzelnen Abrufen kann frei gewählt werden, darf jedoch 60 Minuten NICHT unterschreiten.

Ein PVS kann nur Änderungen an Terminbuchungen abrufen, die von den im PVS hinterlegten Praxen / medizinischen Einrichtungen angeboten werden.

Der 116117 Terminservice sortiert die Suchergebnisse über alle Seiten hinweg chronologisch. Die älteste Änderung erscheint dabei als erstes in den Suchergebnissen 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.

Generelle Hinweise, die für alle Interaktionen gelten, sind auf der Seite Interaktionen gelistet. Dort sind auch detaillierte 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 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)

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, also 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 ein Fehler als Response zurückkommt, wenn sich mehrere Suchparameter gegenseitig ausschließen. Ein Beispiel hierfür ist eine UND-Verknüpfung bei mehreren BSNRs. 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 BSNRs.

• Wurde bei der Suche mindestens 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, wenn vorhanden: Provenances (im Element Bundle.entry)

• 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:

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

• 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.

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.