Videosprechstundentermine suchen

Inhalt

Beschreibung und fachlicher Kontext
FHIR-Operation
Request
Response

Beschreibung und fachlicher Kontext

Bei der Suche nach Videosprechstundenterminen handelt es sich um eine custom operation in FHIR.

Mit dieser Operation können im 116117 Terminservice freie Terminslots für telemedizinische Leistungen (Videosprechstunden) gesucht werden.

Voraussetzung ist ein gültiger und ungebuchter Vermittlungscode. Das heißt, der Vermittlungscode darf nicht abgelaufen sein und der Status des Vermittlungscodes muss den Wert draft (ungebucht bzw. frei) haben. Andernfalls gibt die Suchanfrage einen Fehler zurück.

Durch eine Terminsuche ändert sich der Status des Vermittlungscodes nicht.

Der Zeitraum für den gesetzlichen Anspruch auf eine Terminvermittlung beginnt, sobald bei einer Terminsuche mit einem Vermittlungscode passende (freie) Terminslots gefunden werden. Das bedeutet, die erste Terminsuche mit diesem Vermittlungscode, die Suchergebnisse zurückliefert, markiert den Startzeitpunkt für den gesetzlichen Anspruch auf eine Terminvermittlung. (Hierbei kann es sich auch um eine Suche nach Präsenzterminen handeln.)

FHIR-Operation

Name	KBV_OD_KV_DIGITAL_TS_KVEN_Video_Consultation_Slot_Search
Type	OperationDefinition
Kind	`operation`
Code	`videosprechstundentermine_suchen`
Canonical URL	`https://fhir.kbv.de/OperationDefinition/KBV_OD_KV_DIGITAL_TS_KVEN_Video_Consultation_Slot_Search`

Invocations

URL: [base]/$videosprechstundentermine_suchen

Parameters (In)

Name	Cardinality	Type	Binding	Documentation
vermittlungscode	1..1	canonical(KBV_PR_KV_DIGITAL_TS_KVEN_Identifier_Vermittlungscode)		Der Vermittlungscode des Patienten, für den die Suche ausgeführt wird, ist eine 12-stellige alphanumerische Folge. Der Vermittlungscode darf nicht abgelaufen und noch nicht gebucht (d.h. bereits mit einem Terminslot verknüpft) sein.
start	0..1	date		Beginn des Zeitraums (frühestes Datum), in dem Terminslots gesucht werden sollen. Default-Wert ist das heutige Datum. Das Datum darf nicht in der Vergangenheit liegen.
ende	0..1	date		Ende des Zeitraums (spätestes Datum), in dem Terminslots gesucht werden sollen. Default-Wert ist das heutiges Datum + 35 Tage (5 Wochen). Das Datum ist inklusive; d.h., es werden auch Terminslots am 35. Tag zurückgegeben. Das Datum darf nicht vor dem Datum "start" liegen.
postleitzahl	0..1	string		Die Postleitzahl für den Suchmittelpunkt muss eine gültige, deutsche Postleitzahl sein, die einer KV zugeordnet ist.
leistungsmerkmale	0..100	Coding	KBV_VS_KV_DIGITAL_TS_DRITTE_Specialties (required)	Liste der gesuchten Leistungsmerkmale. Es wird mit einer ODER-Verküpfung gearbeitet; d.h., ein Suchergebnis enthält mindestens eins der angegebenen Leistungsmerkmale (aber nicht zwangsweise alle). Ist der übergebene Vermittlungscode an ein oder mehrere Leistungsmerkmale gebunden, können diese bei der Suche nur noch weiter eingeschränkt, aber nicht erweitert werden.
suchradius	0..1	Coding	KBV_VS_KV_DIGITAL_TS_DRITTE_Search_Radius (required)	Suchradius in Kilometern. Erlaubte Werte: 1, 5, 10, 20, 50, 100, 150. Default-Wert ist 5.

Return Values (Out)

Name	Cardinality	Type	Documentation
suchergebnisse	1..1	canonical(KBV_PR_KV_DIGITAL_TS_KVEN_Bundle_Operation_Result)	Die Suchergebnisse enthalten den Suchparametern entsprechende, freie Terminslots, die zugehörigen Terminprofile, Praxen und deren Standort und den für die Suche verwendeten Suchradius.

Request

Die FHIR-Operation zum Suchen von Videosprechstundenterminen erfordert einen POST-Request.

Die Eingabeparameter für diese FHIR-Operation müssen als Parameters-Ressource im Request Body übergeben werden (siehe hierzu Abschnitt Request Body).

HTTP Method	`POST`
URL	`https://terminefuerkven.eterminservice.kv-safenet.de/terminefuerkven/api/v1/$videosprechstundentermine_suchen`
Request Body	`[parameters]`

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`	nein	Gibt den ursprünglichen Medien- bzw. Dateitypen der Ressource an. Der 116117 Terminservice unterstützt die Werte `fhir+xml`, `xml+fhir` und `xml`. Es wird empfohlen, den Wert `fhir+xml` für diesen Header zu setzen.	`application/fhir+xml`

Request Body

Der Request Body muss eine Parameters-Ressource mit den Eingabeparametern enthalten.

In der folgenden Tabelle finden sich alle zulässigen Eingabeparameter sowie die Angabe, ob es sich dabei um einen verpflichtenden Parameter handelt und ggf. Anmerkungen zu diesem Parameter:

Parameter	Verpflichtend?	Anmerkung
`vermittlungscode`	ja	Der Vermittlungscode ist ohne Bindestriche anzugeben. Das heißt, er muss aus exakt 12 alphanumerischen Zeichen bestehen. Erlaubt sind alle Großbuchstaben (A-Z) und Zahlen (0-9) mit folgenden Ausnahmen: `O 0 I 1 E 3`
`start`	nein	Das Datum muss sich am heutigen oder einem zukünftigen Tag befinden.
`ende`	nein	Das Datum muss zeitlich nach dem Parameter `start` liegen. Der Default-Wert ist das heutige Datum + 35 Tage (5 Wochen).
`postleitzahl`	nein	Die Postleitzahl muss aus exakt 5 Zahlen (0-9) bestehen und einer KV zugeordnet sein. Wird dieser Parameter übergeben, wird eine geolokale Suche mit einem Suchradius durchgeführt. Die angegebene Postleitzahl wird dabei als Suchmittelpunkt festgelegt. (Weitere Details zum Suchradius sind auf der Seite Genutzter Suchradius (OperationOutcome) zu finden.)
`leistungsmerkmale`	nein	Es muss mindestens ein Leistungsmerkmal vorhanden sein: entweder als Eingabeparameter übergeben oder mit dem genutzten Vermittlungscode assoziiert (dafür muss `ServiceRequest.extension:statusLeistungsmerkmalzuweisung` den Wert `gebunden` haben). Hinweis: Vermittlungscodes, die über die Operation Vermittlungscode anfordern erzeugt wurden, sind immer mit mindestens einem Leistungsmerkmal assoziiert.
`suchradius`	nein	Der Default-Wert beträgt 5 km und wird immer dann genutzt, wenn eine Postleitzahl (Parameter `postleitzahl`), aber kein Suchradius übergeben wurde. Werden keine freien Terminslots mit dem festgelegten Suchradius gefunden, wird dieser systemseitig entsprechend den im CodeSystem festgelegten Werten schrittweise vergrößert. Das heißt, wenn mit einem Radius von 5 km keine Slots gefunden wurden, wird der Radius zunächst auf 10 km erweitert, dann auf 20 km usw., bis zum Maximum von 150 km. Um klarzustellen, welcher Radius zu den Suchergebnissen geführt hat, wird dieser für geolokale Suchen immer als Teil des Result Bundles zurückgegeben. (Weitere Details hierzu sind auf der Seite Genutzter Suchradius (OperationOutcome) zu finden.)

Eine ausführliche Beschreibung des Parameters-Profils ist hier in der offiziellen HL7-Dokumentation zu finden.

Beispiele

Alle Beispiele für den Request Body (Parameters-Ressource) sind hier im vorliegenden Projekt zu finden.

# Request
POST https://terminefuerkven.eterminservice.kv-safenet.de/terminefuerkven/api/v1/$videosprechstundentermine_suchen
Content-Type: application/fhir+xml

Request Body (Minimalbeispiel)
Request Body (Maximalbeispiel)

</valueIdentifier>

</parameter>

</Parameters>

</valueIdentifier>

</parameter>

</parameter>

</parameter>

</parameter>

</valueCoding>

</parameter>

</valueCoding>

</parameter>

</valueCoding>

</parameter>

</Parameters>

Response

Die FHIR-Operation gibt bei Erfolg den HTTP-Statuscode 200 OK sowie ein Bundle im Response Body zurück.

Im Fehlerfall wird ein dem Fehler entsprechender HTTP-Statuscode (bspw. 400 Bad Request oder 500 Internal Server Error) und ggf. ein OperationOutcome im Response Body zurückgegeben. Das 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 Bundle enthalten, welches alle relevanten Ressourcen für die Terminsuche (im Element Bundle.entry) enthält:

Terminslots
Terminprofile, auf denen die gefundenen Terminslots basieren
Praxen / medizinischen Einrichtungen, die die gefundenen Terminslots anbieten
Standorte, die zu den Praxen / medizinischen Einrichtungen gehören
ggf. Ärzte, die die gefundenen Termin durchführen (sofern angegeben)
ggf. genutzter Suchradius (nur bei geolokalen Suchen, also Suchen mit einer Postleitzahl)

Werden bei geolokalen Suchen keine Terminslots gefunden, wird nur der genutzte Suchradius zurückgegeben. Bei nicht geolokalen Suchen kommt in diesem Fall ein leeres Bundle zurück.

Die Terminprofile, die Praxen / medizinische Einrichtungen, die Standorte der Praxen / medizinischen Einrichtungen und die Ärzte werden jeweils nur 1x zurückgegeben, auch wenn sie zu mehreren Terminslots gehören. Das bedeutet, dass es keine Duplikate in den Suchergebnissen gibt. Die Zuordnung zu den gefundenen Terminslots erfolgt anhand von Referenzen. Wie die einzelnen Profile aufeinander referenzieren, ist auf der Seite Profile im Abschnitt Referenzen zwischen Profilen dargestellt.

Die Gesamtzahl aller Einträge, die sich im Element Bundle.entry befinden, wird im Element Bunlde.total angegeben. Dies ist somit die Summe der Anzahlen aller Terminslots, Terminprofile, Praxen / medizinischen Einrichtungen und Geolocations, bei geolokalen Suchen plus 1 (für den zurückgegebenen Suchradius). Daher kann Bundle.total nicht dazu genutzt werden, um die Anzahl der gefundenen Terminslots anzugeben.

Weitere Details zum Bundle sind auf der Seite Result Bundle (Bundle) zu finden.

Im Fehlerfall kann im Response Body ein OperationOutcome enthalten sein. Details hierzu sind auf der Seite Fehler (OperationOutcome) zu finden.

Bitte beachten: Es gibt HTTP-Statuscodes, bei denen im Response Body kein OperationOutcome enthalten ist. Nähere Informationen dazu sind auf der Seite FAQ zu finden.

Beispiele

Alle Beispiele für den Response Body im Erfolgsfall (Bundle-Ressource) sind hier im vorliegenden Projekt zu finden.

Alle Beispiele für den Response Body im Fehlerfall (OperationOutcome-Ressource) sind hier im vorliegenden Projekt zu finden.

<meta>

</meta>

<entry>

<Slot>

<meta>

</meta>

<text>

<div xmlns="http://www.w3.org/1999/xhtml">Diese Slot-Instanz enthält einen Videosprechstundenterminslot am 2024-01-27 von 10:15 bis 10:30 Uhr für das Leistungsmerkmal 09 (Arztgruppe)</div>

</text>

</identifier>

<system value="https://fhir.kbv.de/CodeSystem/KBV_CS_SFHIR_BPL_ARZTGRUPPE" />
<code value="09" />
<display value="Kinder- und Jugendärzte" />

</coding>

</specialty>

<system value="http://terminology.hl7.org/CodeSystem/v3-ActCode" />
<code value="VR" />
<display value="virtual" />

</coding>

</appointmentType>

</schedule>

</Slot>

</resource>

</search>

</entry>

<entry>

<Slot>

<meta>

</meta>

<text>

<div xmlns="http://www.w3.org/1999/xhtml">Diese Slot-Instanz enthält einen Videosprechstundenterminslot am 2024-01-27 von 10:15 bis 10:30 Uhr für die Leistungsmerkmale 09 (Arztgruppe) und 341 (WBO)</div>

</text>

</identifier>

<system value="https://fhir.kbv.de/CodeSystem/KBV_CS_SFHIR_BPL_ARZTGRUPPE" />
<code value="09" />
<display value="Kinder- und Jugendärzte" />

</coding>

</specialty>

<system value="https://fhir.kbv.de/CodeSystem/KBV_CS_SFHIR_BAR2_WBO" />
<code value="030" />
<display value="FÄ/FA Augenheilkunde" />

</coding>

</specialty>

<system value="http://terminology.hl7.org/CodeSystem/v3-ActCode" />
<code value="VR" />
<display value="virtual" />

</coding>

</appointmentType>

</schedule>

</Slot>

</resource>

</search>

</entry>

<entry>

<Slot>

<meta>

</meta>

<text>

<div xmlns="http://www.w3.org/1999/xhtml">Diese Slot-Instanz enthält einen Präsenzterminslot am 2024-01-28 von 10:05 bis 10:20 Uhr für das Leistungsmerkmal 030 (WBO)</div>

</text>

</identifier>

<system value="https://fhir.kbv.de/CodeSystem/KBV_CS_SFHIR_BAR2_WBO" />
<code value="030" />
<display value="FÄ/FA Augenheilkunde" />

</coding>

</specialty>

<system value="http://terminology.hl7.org/CodeSystem/v3-ActCode" />
<code value="VR" />
<display value="virtual" />

</coding>

</appointmentType>

</schedule>

</Slot>

</resource>

</search>

</entry>

<entry>

<meta>

</meta>

<text>

<div xmlns="http://www.w3.org/1999/xhtml">Diese Organization-Instanz beschreibt die Praxis 'Dr. med. Hans Topp-Glücklich'. Diese Praxis befindet sich in der Musterstr. 1, 64283 Darmstadt.</div>

</text>

<type>

<system value="http://terminology.hl7.org/CodeSystem/v2-0203" />
<code value="BSNR" />
<display value="Primary physician office number" />

</coding>

</type>

</identifier>

<type value="both" />
<line value="Musterstr. 1">
<extension url="http://hl7.org/fhir/StructureDefinition/iso21090-ADXP-houseNumber">
<valueString value="1" />
</extension>
<extension url="http://hl7.org/fhir/StructureDefinition/iso21090-ADXP-streetName">
<valueString value="Musterstr." />
</extension>
</line>
<city value="Darmstadt" />
<postalCode value="64283" />

</address>

</Organization>

</resource>

</search>

</entry>

<entry>

<meta>

</meta>

<text>

<div xmlns="http://www.w3.org/1999/xhtml">Diese Organization-Instanz beschreibt die Praxis 'Dr. med. Hans Topp-Glücklich'. Diese Praxis befindet sich in der Musterstr. 1, 64283 Darmstadt.</div>

</text>

<type>

<system value="http://terminology.hl7.org/CodeSystem/v2-0203" />
<code value="BSNR" />
<display value="Primary physician office number" />

</coding>

</type>

</identifier>

</telecom>

<type value="both" />
<line value="Musterstr. 1" />
<city value="Darmstadt" />
<postalCode value="64283" />

</address>

</Organization>

</resource>

</search>

</entry>

<entry>

<meta>

</meta>

<text>

<div xmlns="http://www.w3.org/1999/xhtml">Diese Schedule-Instanz enthält ein Terminprofil mit der Diagnosefremdsprache Thai (Thailand)</div>

</text>

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

</valueCoding>

</extension>

</extension>

</identifier>

<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 der Diagnosefremdsprache Thai (Thailand)</div>

</text>

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

</valueCoding>

</extension>

</extension>

</identifier>

<actor>

</actor>

<actor>

</actor>

</Schedule>

</resource>

</search>

</entry>

<entry>

<meta>

</meta>

<text>

<div xmlns="http://www.w3.org/1999/xhtml">Diese Location-Instanz enthält einen Standort mit den Koordinaten longitude 8.651177 und latitude 49.872775</div>

</text>

</extension>

</position>

</managingOrganization>

</Location>

</resource>

</search>

</entry>

<entry>

<meta>

</meta>

<text>

<div xmlns="http://www.w3.org/1999/xhtml">Diese Location-Instanz enthält einen Standort mit den Koordinaten longitude 8.651177 und latitude 49.872775</div>

</text>

</extension>

<system value="https://fhir.kbv.de/CodeSystem/KBV_CS_SFHIR_BAR2_BARRIEREFREIHEIT" />
<code value="02" />
<display value="Stufenloser Eingang/Zugang" />

</coding>

</valueCodeableConcept>

</extension>

<system value="https://fhir.kbv.de/CodeSystem/KBV_CS_SFHIR_BAR2_BARRIEREFREIHEIT" />
<code value="08" />
<display value="Orientierungshilfen für Sehbehinderte" />

</coding>

</valueCodeableConcept>

</extension>

</valueCodeableConcept>

</extension>

</position>

</managingOrganization>

</Location>

</resource>

</search>

</entry>

<entry>

<meta>

</meta>

<text>

<div xmlns="http://www.w3.org/1999/xhtml">Diese Practitioner-Instanz beschreibt eine behandelnde Person mit der ANR 123456789</div>

</text>

<type>

<system value="http://terminology.hl7.org/CodeSystem/v2-0203" />
<code value="LANR" />
<display value="Lifelong physician number" />

</coding>

</type>

</identifier>

<name>

<use value="official" />
<family value="Mustermensch" />
<given value="Michel" />

</name>

</Practitioner>

</resource>

</search>

</entry>

<entry>

<meta>

</meta>

<text>

<div xmlns="http://www.w3.org/1999/xhtml">Diese OperationOutcome-Instanz enthält einen genutzten Suchradius von 10 km</div>

</text>

<issue>

<system value="https://fhir.kbv.de/CodeSystem/KBV_CS_KV_DIGITAL_TS_DRITTE_Search_Radius" />
<code value="10" />
<display value="10 km" />

</coding>

</details>

</issue>

</OperationOutcome>

</resource>

</search>

</entry>

</Bundle>

<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_KV_DIGITAL_TS_KVEN_Errors" />
<code value="TFKV001" />
<display value="Allgemeiner Fehler" />

</coding>

</details>

</issue>

</OperationOutcome>

<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_KV_DIGITAL_TS_KVEN_Errors" />
<code value="TFKV000" />
<display value="Sonstiger Fehler. Unter diagnostics finden Sie nähere Informationen zum Fehler." />
</coding>
</details>
<diagnostics value="Ungültiger Input-Parameter" />

</issue>

</OperationOutcome>