Vermittlungscode anfordern
Inhalt
Beschreibung und fachlicher Kontext
Beim Anfordern eines Vermittlungscodes handelt es sich um eine custom operation in FHIR.
Mit dieser Operation kann ein Vermittlungscode für eine Dringlichkeit sowie für ein oder mehrere Leistungsmerkmale vom 116117 Terminservice angefordert werden. Der so erstellte Vermittlungscode hat den Status draft (ungebucht bzw. frei) und ist an die angegebene Dringlichkeit sowie die angegebenen Leistungsmerkmale gebunden. Im Anschluss lässt sich mit diesem Vermittlungscode eine Terminsuche und -buchung ausführen.
Der Zeitpunkt für den Start des gesetzlichen Anspruchs auf eine Terminvermittlung ist noch nicht festgelegt. Dieser wird erst mit der erstmaligen Terminsuche ausgelöst. Details zur Vermittlungsfrist eines Vermittlungscodes sind im Abschnitt Informationsgehalt: Dringlichkeit auf der Seite Vermittlungscode zu finden.
FHIR-Operation
| Name | KBV_OD_KV_DIGITAL_TS_KVEN_Vermittlungscode_Request |
|---|---|
| Type | OperationDefinition |
| Kind | operation |
| Code | vermittlungscode_anfordern |
| Canonical URL | https://fhir.kbv.de/OperationDefinition/KBV_OD_KV_DIGITAL_TS_KVEN_Vermittlungscode_Request |
Invocations
URL: [base]/$vermittlungscode_anfordern
Parameters (In)
| Name | Cardinality | Type | Binding | Documentation |
|---|---|---|---|---|
| leistungsmerkmale | 1..100 | Coding | KBV_VS_KV_DIGITAL_TS_DRITTE_Specialties (required) | Liste der für die Vermittlung benötigten Leistungsmerkmale |
| dringlichkeit | 1..1 | Coding | KBV_VS_KV_DIGITAL_TS_DRITTE_Urgency (required) | Die Dringlichkeit einer Überweisung: routine = nicht dringend | urgent = dringend / PT-Akutbehandlung | asap = akut |
Return Values (Out)
| Name | Cardinality | Type | Documentation |
|---|---|---|---|
| vermittlungscode | 1..1 | canonical(KBV_PR_KV_DIGITAL_TS_KVEN_Identifier_Vermittlungscode) | Der neue Vermittlungscode hat die gewünschte Dringlichkeit und ist mit den gewünschten Leistungsmerkmalen verknüpft. |
Request
Die FHIR-Operation zum Anfordern eines Vermittlungscodes 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/$vermittlungscode_anfordern |
| 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 den Eingabeparametern enthalten.
| Parameter | Verpflichtend? | Anmerkung |
|---|---|---|
dringlichkeit |
ja | Es muss genau eine Dringlichkeit angegeben werden. Details zu den Dringlichkeiten sind im Abschnitt Informationsgehalt: Dringlichkeit auf der Seite Vermittlungscode zu finden. |
leistungsmerkmale |
ja | Es muss mindestens ein Leistungsmerkmal angegeben werden. Es dürfen sowohl überweisungsfreie als auch überweisungspflichtige Leistungsmerkmale angegeben werden. |
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/$vermittlungscode_anfordern
Content-Type: application/fhir+xml
Response
Die FHIR-Operation gibt bei Erfolg den HTTP-Statuscode 200 OK und einen Vermittlungscode im Response Body zurück.
Im Fehlerfall wird ein entsprechender HTTP-Statuscode (bspw. 400 Bad Request oder 500 Internal Server Error) sowie ggf. 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 eine Identifier-Ressource enthalten, die den Vermittlungscode enthält. Details zum Identifier-Profil sind auf der Seite Vermittlungscode (Identifier) zu finden.
Im Fehlerfall kann im Response Body ein OperationOutcome enthalten sein. Details zum OperationOutcome sind unter Fehler (OperationOutcome) zu finden.
Bitte beachten: Es gibt HTTP-Statuscodes, bei denen im Response Body kein OperationOutcome enthalten ist. Nähere Informationen zu den HTTP-Statuscodes und möglichen Fehlerfällen sind auf der Seite FAQ zu finden.
Beispiele
Beispiel für den Response Body im Erfolgsfall (Identifier-Ressource):
<identifier> <system value="https://fhir.kbv.de/NamingSystem/KBV_NS_116117_TERMINSERVICE_Vermittlungscode" /> <value value="XN6XF4UPZ5KX" /> </identifier>
Alle Beispiele für den Response Body im Fehlerfall (mit OperationOutcome-Ressource) sind hier im vorliegenden Projekt zu finden.