Buchungsinformationen abrufen

Inhalt

Beschreibung und fachlicher Kontext
FHIR-Operation
Request
Response

Beschreibung und fachlicher Kontext

Beim Abrufen von Buchungsinformationen handelt es sich um eine custom operation in FHIR.

Mit dieser Operation lassen sich im Anschluss an eine Terminbuchung über den 116117 Terminservice Informationen über diese Buchung abrufen.

Voraussetzung ist, dass die Buchung über den 116117 Terminservice erfolgte sowie ein gültiger Vermittlungscode mit dem Status active (gebucht). Das heißt, es muss eine nicht abgesagte Buchung zu diesem Vermittlungscode vorliegen. Andernfalls gibt die Operation einen Fehler zurück.

Durch das Abrufen der Terminbuchungsinformationen ändert sich der Status des Vermittlungscodes nicht.

FHIR-Operation

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

Invocations

URL: [base]/$buchungsinformationen_abrufen

Parameters (In)

Name	Cardinality	Type	Documentation
vermittlungscode	1..1	canonical(KBV_PR_KV_DIGITAL_TS_KVEN_Identifier_Vermittlungscode)	Der Vermittlungscode des Patienten, für den die Buchungsinformationen abgerufen werden sollen, ist eine 12-stellige alphanumerische Folge.

Return Values (Out)

Name	Cardinality	Type	Documentation
suchergebnis	0..1	canonical(KBV_PR_KV_DIGITAL_TS_KVEN_Bundle_Operation_Result)	Bundle mit den Details zum Termin, dem zugehörigen Terminprofil, der Praxis und deren Standort

Request

Die FHIR-Operation zum Abrufen von Buchungsinformationen erfordert einen POST-Request.

Der Eingabeparameter für diese FHIR-Operation muss 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/$buchungsinformationen_abrufen`
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 dem Eingabeparameter vermittlungscode enthalten.

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

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

Beispiel

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/$buchungsinformationen_abrufen
Content-Type: application/fhir+xml

Request Body

</valueIdentifier>

</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 Buchungsinformationen (im Element Bundle.entry) enthält:

Terminbuchung
Terminprofil, auf dem der gebuchte Termin basiert
Praxis / medizinischen Einrichtung, die den Termin anbietet
Standort, an dem sich die Praxis / medizinische Einrichtung befindet
ggf. Arzt, der den Termin durchführt (sofern angegeben)

Die genannten Ressourcen sind jeweils genau 1x im Bundle enthalten.

Wenn geprüft werden soll, ob das richtige Terminprofil, die richtige Praxis / medizinische Einrichtung sowie der korrekte Standort zurückgegeben wurde, kann dies anhand der Referenzen der Profile untereinander validiert werden. Wie die einzelnen Profile aufeinander referenzieren, ist auf der Seite Profile im Abschnitt Referenzen zwischen Profilen dargestellt.

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>

<meta>

</meta>

<text>

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

</text>

<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="341" />
<display value="FÄ/FA Kinder- und Jugendmedizin" />

</coding>

</specialty>

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

</coding>

</appointmentType>

<actor>

</actor>

</participant>

</Appointment>

</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 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">
<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 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="08" />
<display value="Orientierungshilfen für Sehbehinderte" />

</coding>

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

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