Terminprofile abrufen (Schedule Search)

Inhalt

Beschreibung und fachlicher Kontext
Request
Response

Beschreibung und fachlicher Kontext

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

Der Abruf ist 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 Terminprofile für die im Software-System hinterlegte Praxis / medizinische Einrichtung vom 116117 Terminservice abgerufen werden. Bei Bedarf können aber auch einzelne Terminprofile abgerufen und so deren aktueller Status überprüft werden.

Beim Abrufen der Terminprofile sind die übertragenen Datenmengen in der Regel gering, da es nur selten vorkommt, dass viele Terminprofile angelegt werden.

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 Terminprofile angelegt oder bestehende Terminprofile 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 Terminprofile anlegt oder löscht.)

Request

Das Abrufen von Terminprofilen erfordert einen POST-Request. Es können entweder alle Terminprofile aller autorisierten Einrichtungen oder nur bestimmte Terminprofile anhand entsprechender Suchparameter im Request Body abgefragt werden (siehe hierzu Abschnitt Request Body).

HTTP Method	`POST`
URL	`https://terminsynchronisation.eterminservice.kv-safenet.de/pvs/terminsynchronisation/api/Schedule/_search`
Request Body	`[suchparameter]`

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:

Header	Verpflichtend?	Beschreibung	Wert
`Authorization`	ja	Im Authentisierungsverfahren erhaltener ACCESS_TOKEN als Bearer Token	`Bearer ey...`
`Content-Type`	ja	Gibt den ursprünglichen Medien- bzw. Dateitypen der Ressource an.	`application/x-www-form-urlencoded`
`Accept`	nein	Gibt an, welche Inhaltstypen die Systeme des Anfragenden verstehen. Der 116117 Terminservice unterstützt die Werte `fhir+xml` und `xml`. Es wird empfohlen, den Wert `fhir+xml` für diesen Header zu setzen.	`application/fhir+xml`

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 Terminprofile 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

Parameter	`_id`
Beschreibung	ID eines Terminprofils
Kardinalität	0..*
Erlaubte Verknüpfungen¹	ODER-Verknüpfung
Erlaubte Präfixe²	-
Suchergebnis	Alle Terminprofile, die eine der angegebenen IDs im Feld `Schedule.id` hinterlegt haben.
Anmerkung	Mithilfe dieses Suchparameters lässt sich gezielt ein einzelnes Terminprofil abrufen. Es müssen alle Zeichen der ID übergeben werden. Eine Suche mit bspw. nur den ersten 3 Zeichen einer ID ist nicht zulässig und führt zu einem Fehler.

Suchparameter: Betriebsstättennummer (BSNR)

Parameter	`bsnr`
Beschreibung	9-stellige BSNR der Praxis / medizinischen Einrichtung, die dem Terminprofil zugeordnet ist.
Kardinalität	0..*
Erlaubte Verknüpfungen¹	ODER-Verknüpfung
Erlaubte Präfixe²	-
Suchergebnis	Alle Terminprofile, die den Praxen / medizinischen Einrichtungen zugeordnet sind, zu denen die angegebenen BSNRs gehören.
Anmerkung	Bei der BSNR handelt es sich um einen custom search parameter. Details hierzu sind auf der Seite Suchparameter: BSNR (SearchParameter) zu finden. Wird der Parameter nicht übergeben, werden alle BSNRs aus dem Access Token als Suchparameter übernommen.

Suchparameter: Arztnummer (ANR)

Parameter	`anr`
Beschreibung	ANR des Arztes, der dem Terminprofil zugeordnet ist.
Kardinalität	0..*
Erlaubte Verknüpfungen¹	ODER-Verknüpfung
Erlaubte Präfixe²	-
Suchergebnis	Alle Terminprofile, die den Ärzten zugeordnet sind, zu denen die angegebenen ANRs gehören.
Anmerkung	Bei der ANR handelt es sich um einen custom search parameter. Details hierzu sind auf der Seite Suchparameter: ANR (SearchParameter) zu finden. Es können entweder nur die ersten 7 Stellen oder alle 9 Stellen der ANR übergeben werden.

Suchparameter: Anzahl der Suchergebnisse

Parameter	`_count`
Beschreibung	Anzahl der Suchergebnisse pro Seite
Kardinalität	0..1
Erlaubte Verknüpfungen¹	-
Erlaubte Präfixe²	-
Suchergebnis	Es werden maximal so viele Terminprofile im Response Body zurückgegeben, wie in `_count` angegeben wurde. (Ressourcen, die in den Terminprofilen referenziert und ebenfalls mit zurückgegeben werden, werden hier nicht mit eingerechnet.)
Anmerkung	Wird der Parameter nicht übergeben, wird der Standardwert von 10 als Suchparameter übernommen. Erlaubte Werte sind alle natürlichen Zahlen zwischen 1 und 10, wobei 1 und 10 ebenfalls erlaubt sind. Es kann sein, dass insgesamt mehr Suchergebnisse gefunden werden, als in `_count` angegeben wurde. In diesem Fall gibt es mehrere Seiten mit Suchergebnissen; die anderen Seiten können über weitere Requests mit dem entsprechenden Wert für den Suchparameter `page` abgerufen werden. Weitere Details zum Thema Paging sind auf der Seite Operationen und Interaktionen zu finden.

Suchparameter: Seite der Suchergebnisse

Parameter	`page`
Beschreibung	Seite der Suchergebnisse, die zurückgegeben werden soll.
Kardinalität	0..1
Erlaubte Verknüpfungen¹	-
Erlaubte Präfixe²	-
Suchergebnis	Es wird die angegebene Seite der Suchergebnisse zurückgegeben.
Anmerkung	Wird der Parameter nicht übergeben, wird der Standardwert von 1 als Suchparameter übernommen. Es wird dann also immer die 1. Seite zurückgegeben. Welche Suchergebnisse zurückgegeben werden, hängt auch vom Wert des Suchparameters `_count` ab. Wird bspw. mit `_count=5` und `page=2` gesucht, werden die Suchergebnisse 6 bis 10 zurückgegeben. Wird eine nicht existente Seitenzahl angegeben, ist der Request dennoch valide – im Response Body sind in diesem Fall jedoch keine Suchergebnisse enthalten. Wenn bspw. insgesamt 15 Suchergebnisse gefunden wurden und 10 Suchergebnisse pro Seite zurückgegeben werden, enthält der Response Body auf eine Suchanfrage mit `page=3` keine Suchergebnisse. Weitere Details zum Thema Paging sind auf der Seite Operationen und Interaktionen zu finden.

¹ 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 Terminprofile, die der Praxis mit der BSNR 123456789 zugeordnet sind
POST https://terminsynchronisation.eterminservice.kv-safenet.de/pvs/terminsynchronisation/api/Schedule/_search
Content-Type: application/x-www-form-urlencoded
bsnr=123456789

Weitere Beispiele

Beispiel 1: Suche anhand mehrerer IDs

# Suche alle Terminprofile, 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/Schedule/_search
Content-Type: application/x-www-form-urlencoded
_id=084c8796-a6e8-402d-9170-67a9d05b79a0,68698730-6e1c-4a09-83e1-b730dcb7fe81

Beispiel 2: Suche anhand einer ANR

# Suche alle Terminprofile, die dem Arzt mit der ANR 123456789 zugeordnet sind
POST https://terminsynchronisation.eterminservice.kv-safenet.de/pvs/terminsynchronisation/api/Schedule/_search
Content-Type: application/x-www-form-urlencoded
anr=123456789

Response

Für die Suche von Terminprofilen 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 Terminprofile der Haupt- und Nebenbetriebsstätten der in der Autorisierung übergebenen BSNRs.
Wurde bei der Suche mindestens ein Suchparameter übergeben, enthält dieses Searchset alle Terminprofile, 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:

Header	Beschreibung	Wert
`Content-Type`	Gibt den ursprünglichen Medien- bzw. Dateitypen der Ressource an.	`application/fhir+xml`

Response Body

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

Suchergebnisse, wenn vorhanden: Terminprofile (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.
In den Schedules referenzierte Ressourcen:
- PractitionerRole

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.

<meta>

</meta>

<link>

</link>

<entry>

<meta>

<versionId value="1" />
<lastUpdated value="2024-09-01T16:32:24+02:00" />
<profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_116117_TERMINSERVICE_TVS_TERMINSYNCHRONISATION_Schedule_Slot_Profile|1.0.0" />

</meta>

<text>

<div xmlns="http://www.w3.org/1999/xhtml">Diese Schedule-Instanz enthält ein Terminprofil mit dem Namen Sprechstunde auf Thai oder Schottisch-Gälisch mit der Dauer 30 min.</div>

</text>

</extension>

<system value="https://fhir.kbv.de/CodeSystem/KBV_CS_SFHIR_BAR_FREMDSPRACHE" />
<code value="83" />
<display value="Thai (Thailand)" />

</valueCoding>

</extension>

<system value="https://fhir.kbv.de/CodeSystem/KBV_CS_SFHIR_BAR_FREMDSPRACHE" />
<code value="107" />
<display value="Schottisch-Gälisch" />

</valueCoding>

</extension>

<value value="30" />
<unit value="minutes" />
<system value="http://unitsofmeasure.org" />
<code value="min" />

</valueDuration>

</extension>

<system value="https://fhir.kbv.de/CodeSystem/KBV_CS_116117_TERMINSERVICE_TVS_TERMINSYNCHRONISATION_Schedule_Slot_Profile_Type" />
<version value="1.0.0" />
<code value="​MANUELL" />
<display value="Im 116117 Terminservice vom Nutzer manuell angelegtes Terminprofil." />

</valueCoding>

</extension>

<actor>

</actor>

</Schedule>

</resource>

</search>

</entry>

<entry>

<meta>

</meta>

<text>

<div xmlns="http://www.w3.org/1999/xhtml">Diese Schedule-Instanz enthält ein Terminprofil mit dem Namen Videosprechstunde auf Thai und Schottisch-Gälisch und der Dauer 60 min.</div>

</text>

</extension>

<system value="https://fhir.kbv.de/CodeSystem/KBV_CS_SFHIR_BAR_FREMDSPRACHE" />
<code value="83" />
<display value="Thai (Thailand)" />

</valueCoding>

</extension>

<system value="https://fhir.kbv.de/CodeSystem/KBV_CS_SFHIR_BAR_FREMDSPRACHE" />
<code value="107" />
<display value="Schottisch-Gälisch" />

</valueCoding>

</extension>

<value value="60" />
<unit value="minutes" />
<system value="http://unitsofmeasure.org" />
<code value="min" />

</valueDuration>

</extension>

<system value="https://fhir.kbv.de/CodeSystem/KBV_CS_116117_TERMINSERVICE_TVS_TERMINSYNCHRONISATION_Schedule_Slot_Profile_Type" />
<version value="1.0.0" />
<code value="AUTOMATISCH" />
<display value="Vom 116117 Terminservice automatisch angelegtes Terminprofil basierend auf den Leistungsmerkmalen des jeweiligen Arztes" />

</valueCoding>

</extension>

<system value="https://fhir.kbv.de/CodeSystem/KBV_CS_SFHIR_BAS_FACHGEBIET_GROB" />
<code value="09" />
<display value="Kinderarzt / Kinderärztin" />

</coding>

</serviceType>

<system value="https://fhir.kbv.de/CodeSystem/KBV_CS_SFHIR_BAR2_WBO" />
<code value="341" />
<display value="FÄ/FA Kinder- und Jugendmedizin" />

</coding>

</serviceType>

<actor>

</actor>

</Schedule>

</resource>

</search>

</entry>

<entry>

<meta>

</meta>

<text>

<div xmlns="http://www.w3.org/1999/xhtml">Diese PractitionerRole-Instanz enthält die BSNR einer Praxis und die Referenz auf eine Practitioner-Instanz.</div>

</text>

</practitioner>

</identifier>

</organization>

</PractitionerRole>

</resource>

</search>

</entry>

<entry>

<meta>

</meta>

<text>

<div xmlns="http://www.w3.org/1999/xhtml">Diese PractitionerRole-Instanz enthält nur die BSNR einer Praxis.</div>

</text>

</identifier>

</organization>

</PractitionerRole>

</resource>

</search>

</entry>

</Bundle>

<meta>

</meta>

<link>

</link>

<entry>

<meta>

<versionId value="2" />
<lastUpdated value="2024-09-01T16:32:24+02:00" />
<profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_116117_TERMINSERVICE_TVS_TERMINSYNCHRONISATION_Schedule_Slot_Profile|1.0.0" />

</meta>

<text>

<div xmlns="http://www.w3.org/1999/xhtml">Diese Schedule-Instanz enthält ein Terminprofil mit dem Namen Sprechstunde M. Mustermensch mit der Dauer 15 min.</div>

</text>

</extension>

<value value="15" />
<unit value="minutes" />
<system value="http://unitsofmeasure.org" />
<code value="min" />

</valueDuration>

</extension>

<actor>

</actor>

</Schedule>

</resource>

</search>

</entry>

<entry>

<meta>

</meta>

<text>

<div xmlns="http://www.w3.org/1999/xhtml">Diese PractitionerRole-Instanz enthält die BSNR einer Praxis und die Referenz auf eine Practitioner-Instanz.</div>

</text>

</practitioner>

</identifier>

</organization>

</PractitionerRole>

</resource>

</search>

</entry>

</Bundle>

<meta>

</meta>

<text>

--- We have skipped the narrative for better readability of the resource ---

</text>

<issue>

<severity value="fatal" />
<code value="value" />
<details>
<coding>
<system value="https://fhir.kbv.de/CodeSystem/KBV_CS_116117_TERMINSERVICE_TVS_TERMINSYNCHRONISATION_Errors" />
<code value="TVSTS0000" />
<display value="Sonstiger Fehler. Unter diagnostics finden Sie nähere Informationen zum Fehler." />
</coding>
</details>
<diagnostics value="Ungültiger Input-Parameter" />

</issue>

</OperationOutcome>

<meta>

</meta>

<text>

--- We have skipped the narrative for better readability of the resource ---

</text>

<issue>

<system value="https://fhir.kbv.de/CodeSystem/KBV_CS_116117_TERMINSERVICE_TVS_TERMINSYNCHRONISATION_Errors" />
<code value="TVSTS0018" />
<display value="Die Dringlichkeit ist ungültig." />

</coding>

</details>

</issue>

</OperationOutcome>