Terminslots abrufen (Slot Search)

Inhalt

1. Beschreibung und fachlicher Kontext
2. Request
   • Request Header
   • Request Body
     • Suchparameter: ID
     • Suchparameter: Betriebsstättennummer (BSNR)
     • Suchparameter: Arztnummer (ANR)
     • Suchparameter: Startzeitpunkt des Terminslots
     • Suchparameter: Terminprofil-ID
     • Suchparameter: Anzahl der Suchergebnisse
     • Suchparameter: Seite der Suchergebnisse
   • Beispiele
     • Initiale Synchronisation
     • Weitere Beispiele
3. Response
   • Response Header
   • Response Body
   • Beispiele

Beschreibung und fachlicher Kontext

Beim Abrufen von Terminslots handelt es sich um die FHIR-Standardinteraktion search. Diese ermöglicht das Synchronisieren mit dem 116117 Terminservice, um den aktuellen Status einzelner oder mehrerer Terminslots abzurufen.

Der Abruf ist vor allem für die initiale Synchronisation der Daten bzw. die Synchronisation nach längerer Zeit (bspw. aufgrund von Betriebsferien) notwendig. In beiden Fällen müssen alle vorhandenen Terminslots für die im Software-System hinterlegte Praxis / medizinische Einrichtung vom 116117 Terminservice abgerufen werden. Bei Bedarf können aber auch einzelne Terminslots abgerufen und so deren aktueller Status überprüft werden.

Bei der initialen Synchronisation kann es vorkommen, dass der 116117 Terminservice Terminslots an das TVS zurückgibt, die das TVS entweder gar nicht kennt oder bereits im eigenen System gespeichert hat. Voraussetzung hierfür ist, dass die Praxis / medizinische Einrichtung bereits VOR der Nutzung der hier beschriebenen Schnittstelle Terminslots an den 116117 Terminservice gemeldet hat. Wurden diese gemeldeten Terminslots auch im eigenen TVS gespeichert, gibt es diese Terminslots quasi doppelt: einmal im TVS selbst und einmal im 116117 Terminservice. Wurden diese gemeldeten Terminslots nur im eigenen TVS, aber nicht im 116117 Terminservice gelöscht, sind diese Terminslots dem TVS nicht (mehr) bekannt.

Werden bei der initialen Synchronisation Terminslots zurückgegeben, sollte das TVS den Nutzer in geeigneter Form darüber informieren, dass er die gefundenen Terminslots prüfen und pro Terminslot eine der folgenden Optionen auswählen soll:

• Der gefundene Terminslot soll aus dem 116117 Terminservice gelöscht werden, wenn dieser dort gar nicht mehr zur Terminbuchung zur Verfügung stehen soll.

• Der gefundene Terminslot soll aus dem 116117 Terminservice gelöscht und der äquivalente Terminslot aus dem eigenen System anschließend erneut an den 116117 Terminservice übertragen werden. (Dies ist hilfreich, wenn der Terminslot im eigenen TVS geändert wurde und diese Änderungen an den 116117 Terminservice übermittelt werden sollen.)

• Der äquivalente Terminslot im eigenen TVS soll eine Markierung o.ä. erhalten, um zu signalisieren, dass es sich dabei um einen Terminslot handelt, der über den 116117 Terminservice gebucht werden kann. (Dies ist hilfreich, wenn der Terminslot im eigenen TVS identisch mit dem aus dem 116117 Terminservice ist. Technisch gesehen, sollte hier eine Verknüpfung zwischen dem Terminslot im TVS und dem Terminslot aus dem 116117 Terminservice vorgenommen werden.)

Dadurch soll verhindert werden, dass ...

• ... Patienten über den 116117 Terminservice Terminslots buchen, die die Praxis / medizinische Einrichtung nicht mehr anbietet oder bereits anderweitig vergeben hat.

• ... die Praxis / medizinische Einrichtung versehentlich Terminslots über das eigene TVS bucht oder löscht (ohne dies dem 116117 Terminservice zu melden), die zuvor bereits über den 116117 Terminservice gebucht wurden.

• ... die Praxis / medizinische Einrichtung eine Terminbuchung nicht mitbekommt, da der Terminslot im eigenen TVS nicht mit dem Terminslot aus dem 116117 Terminservice verknüpft ist und daher noch als frei angezeigt wird.

Beim Abrufen der Terminslots können als Antwort unter Umständen größere Datenmengen zurückgegeben werden. Dies hängt vor allem davon ab, wie aktiv eine Praxis / medizinische Einrichtung den 116117 Terminservice bisher genutzt hat. Hat die Praxis / medizinische Einrichtung in der Vergangenheit viele Terminslots an den 116117 Terminservice gemeldet (und nicht wieder gelöscht), so werden beim Abruf der Terminslots für diese Praxis / medizinische Einrichtung auch mehr Daten zurückkommen.

Generelle Hinweise, die für alle search interactions gelten, sind auf der Seite Operationen und 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 Terminslots angelegt oder bestehende Terminslots gelöscht wurden. (Dass ein TVS dies nur über den 116117 Terminservice mitbekommt, kann bspw. daran liegen, dass die Praxis / medizinische Einrichtung einem Praxisverbund angehört. In diesem Fall kann es sein, dass eine andere Praxis / medizinische Einrichtung aus dem Praxisverbund Terminslots anlegt oder löscht.)

Request

Das Abrufen von Terminslots erfordert einen POST-Request. Es können entweder alle Terminslots aller autorisierten Einrichtungen oder nur bestimmte Terminslots 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.

Für die initiale Synchronisation bzw. die Synchronisation nach längerer Zeit wird beim Abruf nur der Suchparameter bsnr benötigt, da in diesem Fall alle Terminslots benötigt werden, um eine vollständige Synchronisation mit dem 116117 Terminservice sicherzustellen.

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. Beispiele hierfür sind UND-Verknüpfungen bei mehreren BSNRs oder eine UND-Verknüpfung einer ANR und einer BSNR, wobei der zur ANR zugehörige Arzt nicht in der Praxis / medizinischen Einrichtung arbeitet, die zur angegebene BSNR gehört. 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: ID

Suchparameter: Betriebsstättennummer (BSNR)

Suchparameter: Arztnummer (ANR)

Suchparameter: Startzeitpunkt des Terminslots

Suchparameter: Terminprofil-ID

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 möglichen Präfixe sind in der HL7-FHIR-Dokumentation unter Search - Standard Parameters: Prefixes beschrieben.

Beispiele

Initiale Synchronisation

Beispiel: Suche anhand einer BSNR

# Suche alle Terminslots, die von der Praxis mit der BSNR 123456789 angeboten werden
POST https://terminsynchronisation.eterminservice.kv-safenet.de/pvs​/terminsynchronisation/api/Slot/_search
Content-Type: application/x-www-form-urlencoded
bsnr=123456789

Weitere Beispiele

Beispiel 1: Suche anhand einer ANR

# Suche alle Terminslots, die von dem Arzt angeboten werden, dessen ANRs mit den Ziffern 1234567 beginnen
POST https://terminsynchronisation.eterminservice.kv-safenet.de/pvs​/terminsynchronisation/api/Slot/_search
Content-Type: application/x-www-form-urlencoded
anr=1234567

Beispiel 2: Suche anhand mehrerer IDs

# Suche alle Terminslots, die eine der folgenden IDs haben: 084c8796-a6e8-402d-9170-67a9d05b79a0, 68698730-6e1c-4a09-83e1-b730dcb7fe81
POST https://terminsynchronisation.eterminservice.kv-safenet.de/pvs​/terminsynchronisation/api/Slot/_search
Content-Type: application/x-www-form-urlencoded
_id=084c8796-a6e8-402d-9170-67a9d05b79a0,68698730-6e1c-4a09-83e1-b730dcb7fe81

Beispiel 3: Suche anhand einer Terminprofil-ID und eines Zeitpunktes

# Suche alle Terminslots, die auf dem Terminprofil mit der ID 48931c91-8fac-4ed0-a0f5-c3a381a60a31 basieren und zeitlich nach dem 14.01.2024, 10:00 Uhr starten
POST https://terminsynchronisation.eterminservice.kv-safenet.de/pvs​/terminsynchronisation/api/Slot/_search
Content-Type: application/x-www-form-urlencoded
schedule=48931c91-8fac-4ed0-a0f5-c3a381a60a31&start=gt2024-01-14T10:00:00+01:00

Beispiel 4: Suche anhand eines Zeitraumes und einer BSNR

# Suche alle Terminslots, die im Zeitraum zwischen dem 14.01.2024, 10:00 Uhr und dem 16.01.2024, 12:35 Uhr starten und von der Praxis mit der BSNR 123456789 angeboten werden
POST https://terminsynchronisation.eterminservice.kv-safenet.de/pvs​/terminsynchronisation/api/Slot/_search
Content-Type: application/x-www-form-urlencoded
start=lt2024-01-16T12:35:00+02:00&start=gt2024-01-14T10:00:00+02:00&bsnr=123456789

Response

Für die Suche von Terminslots 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 Terminslots der Haupt- und Nebenbetriebsstätten der in der Autorisierung übergebenen BSNRs.

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

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: Terminslots (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 Operationen und Interaktionen zu finden.

Bitte beachten: Im Searchset Bundle sind KEINE Ressourcen inkludiert, die in einem Slot referenziert werden. Die referenzierten Ressourcen müssen bei Bedarf separat abgerufen werden.

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

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.