Termin buchen
Inhalt
Beschreibung und fachlicher Kontext
Beim Buchen eines Termins handelt es sich um eine custom operation in FHIR.
Mit dieser Operation kann im Anschluss an eine Terminsuche über den 116117 Terminservice ein freier Terminslot für medizinische Leistungen gebucht werden.
Voraussetzung ist die ID eines freien Terminslots sowie ein gültiger und ungebuchter Vermittlungscode. Das heißt, der Vermittlungscode darf nicht abgelaufen sein und muss den Status draft (frei) haben. Sind diese Voraussetzungen nicht erfüllt, gibt die Operation einen Fehler zurück.
War die Terminbuchung erfolgreich, hat der Vermittlungscode den Status active (gebucht). Mit diesem Vermittlungscode darf keine weitere Terminbuchung ausgeführt werden – es sei denn, die vorherige Terminbuchung wurde zwischenzeitlich abgesagt. (Details zur Absage eines Termins sind auf der Seite Terminbuchung absagen zu finden.)
FHIR-Operation
| Name | KBV_OD_KV_DIGITAL_TS_KVEN_Slot_Booking |
|---|---|
| Type | OperationDefinition |
| Kind | operation |
| Code | termin_buchen |
| Canonical URL | https://fhir.kbv.de/OperationDefinition/KBV_OD_KV_DIGITAL_TS_KVEN_Slot_Booking |
Invocations
URL: [base]/$termin_buchen
Parameters (In)
| Name | Cardinality | Type | Documentation |
|---|---|---|---|
| vermittlungscode | 1..1 | canonical(KBV_PR_KV_DIGITAL_TS_DRITTE_Identifier_Vermittlungscode) | Vermittlungscode des Patienten, für den ein Termin gebucht werden soll. Der Vermittlungscode ist eine 12-stellige alphanumerische Folge. Auch für überweisungsfreie Termine ist ein Vermittlungscode notwendig. |
| slotId | 1..1 | uuid | Die UUID des (Zeit-) Slots, in dem der gewünschte Termin liegt. |
| patientendaten | 1..1 | canonical(KBV_PR_KV_DIGITAL_TS_KVEN_Patient) | Die Daten eines Patienten, für den der Termin gebucht werden soll. |
BITTE BEACHTEN: Diese Operation hat keinen Output-Parameter. Im Erfolgsfall kommt also eine Antwort ohne Response Body zurück. Im Fehlerfall kann dennoch ein OperationOutcome im Response Body zurückkommen.
Request
Die FHIR-Operation zum Buchen eines Termins 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/$termin_buchen |
| 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.
|
application/fhir+xml |
Request Body
Der Request Body muss eine Parameters-Ressource mit allen 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. Erlaubt sind alle Großbuchstaben (A-Z) und Zahlen (0-9) mit folgenden Ausnahmen: O 0 I 1 E 3 |
slotId |
ja | Die ID eines Terminslots lässt sich über die Präsenzterminsuche bzw. die Videosprechstundenterminsuche ermitteln. |
patientendaten |
ja | Details zu den Patientendaten sind auf der Seite Patient (Patient) zu finden. |
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/$termin_buchen
Content-Type: application/fhir+xml
Response
Die FHIR-Operation gibt bei Erfolg nur den HTTP-Statuscode 201 Created 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
Es werden KEINE spezifischen Response Header von den Systemen des 116117 Terminservices gesetzt.
Response Body
Im Erfolgsfall wird KEIN Response Body zurückgegeben.
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 Fehlerfall (OperationOutcome-Ressource) sind hier im vorliegenden Projekt zu finden.