Präsenztermine suchen

Inhalt

Beschreibung und fachlicher Kontext
FHIR-Operation
Request
Response

Beschreibung und fachlicher Kontext

Bei der Suche nach Präsenzterminen handelt es sich um eine custom operation in FHIR.

Mit dieser Operation können im 116117 Terminservice freie Terminslots für Präsenztermine gesucht werden.

Es handelt sich dabei immer um eine geolokale Suche. Das bedeutet, dass für die Suche eine Postleitzahl angegeben werden muss und nur Terminslots innerhalb eines bestimmten Suchradius' ausgegeben werden. (Details hierzu sind im Abschnitt Request: Request Body auf dieser Seite zu finden.)

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 Videosprechstundenterminen handeln.)

FHIR-Operation

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

Invocations

URL: [base]/$praesenztermine_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.
postleitzahl	1..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 Präsenzterminen 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/$praesenztermine_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`
`postleitzahl`	ja	Die Postleitzahl muss aus exakt 5 Zahlen (0-9) bestehen und einer KV zugeordnet sein. Da dieser Parameter verpflichtend ist, wird bei der Suche nach Präsenzterminen immer 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 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 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/$praesenztermine_suchen
Content-Type: application/fhir+xml

Request Body (Minimalbeispiel)
Request Body (Maximalbeispiel)

</valueIdentifier>

</parameter>

</parameter>

</Parameters>

</valueIdentifier>

</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)
genutzter Suchradius

Werden keine Terminslots gefunden, wird nur der genutzte Suchradius zurückgegeben.

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, plus 1 (für den zurückgegebenen Suchradius). Daher kann Bundle.total nicht dazu genutzt werden, um die Anzahl der gefundenen Terminslots anzugeben.

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 Präsenzterminslot 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="AMB" />
<display value="ambulatory" />

</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-27 von 10:15 bis 10:30 Uhr für die Leistungsmerkmale 09 (Arztgruppe) und 030 (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="AMB" />
<display value="ambulatory" />

</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="AMB" />
<display value="ambulatory" />

</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 einem Terminprofilhinweis</div>

</text>

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