Operation: Vermittlungscode anfordern
Beschreibung und fachlicher Kontext
Beim Anfordern eines Vermittlungscodes handelt es sich um eine custom operation in FHIR. Diese wird über das REST-Protokoll zugänglich gemacht. Abweichungen vom Standard dienen der technischen Umsetzung der zugrundeliegenden Gesetze und der Integration in die internen Prozesse des 116117 Terminservice.
Mit dieser Operation lässt sich über ein Praxisverwaltungssystem (PVS) im 116117 Terminservice ein Vermittlungscode anfordern. Der Vermittlungscode kann anschließend zusammen mit der URL, die ebenfalls zurückgegeben wird, auf die Überweisung (Muster 6) oder das PTV 11 aufgebracht werden.
Das bedeutet, dass diese Operation nur für überweisungsausstellende Ärzte und Psychotherapeuten, nicht aber für ausschließlich behandelnde Ärzte relevant ist, die selbst keine Überweisungen ausstellen.
FHIR-Operation
| Name | KBV_OD_116117_TERMINSERVICE_VCA_Vermittlungscode_Request |
|---|---|
| Type | OperationDefinition |
| Kind | operation |
| Code | vermittlungscode_anfordern |
| Canonical URL | https://fhir.kbv.de/OperationDefinition/KBV_OD_116117_TERMINSERVICE_VCA_Vermittlungscode_Request |
Invocations
URL: [base]/$vermittlungscode_anfordern
Parameters (In)
| Name | Cardinality | Type | Binding | Documentation |
|---|---|---|---|---|
| leistungsmerkmale | 1..100 | Coding | KBV_VS_116117_TERMINSERVICE_VCA_Specialties (required) | Liste der für die Vermittlung benötigten Leistungsmerkmale |
| dringlichkeit | 0..1 | Coding | KBV_VS_116117_TERMINSERVICE_VCA_Urgency (required) | Dringlichkeit einer Überweisung (Muster06): default ist urgent (dringend). Dringlichkeit für PTV11 muss nicht übergeben werden; wenn eine übergeben wird, muss diese urgent (dringend) sein. |
| bsnr | 1..1 | canonical(IdentifierBsnr) | Die BSNR der Einrichtung, die den Vermittlungscode anfordert | |
| ueberweisenderArzt | 1..1 | canonical(KBV_PR_116117_TERMINSERVICE_VCA_Practitioner) | Arzt, der die Überweisung ausstellt | |
| patient | 0..1 | canonical(KBV_PR_116117_TERMINSERVICE_VCA_Patient) | Patient, der die Überweisung benötigt und die Einwilligung zur Datenweitergabe erteilt hat |
Return Values (Out)
| Name | Cardinality | Type | Documentation |
|---|---|---|---|
| vermittlungscode | 1..1 | canonical(KBV_PR_116117_TERMINSERVICE_VCA_Identifier_Vermittlungscode) | Neuer Vermittlungscode mit den gewünschten Leistungsmerkmalen und der angegebenen Dringlichkeit. |
| url | 1..1 | url | URL, welche auf das Muster06 bzw. auf PTV11 aufgedruckt werden soll |
Mit dieser Operation kann ein Vermittlungscode angefordert werden.
Anmerkungen
In der folgenden Tabelle finden sich zudem weitere Anmerkungen zu einzelnen Parametern:
| Parameter | Art | Anmerkung |
|---|---|---|
leistungsmerkmale |
in |
Details dazu, welche Leistungsmerkmale für Muster 6 und PTV 11 übergeben werden können, sind auf der Seite Verwendung der Schnittstelle in den jeweiligen Abschnittten zu finden. Beim Anfordern eines Vermittlungscodes für das Muster 6 ist darüber hinaus zu beachten, dass sich die maximale Anzahl der Leistungsmerkmale auf die Fachgruppen und Zusatz-Weiterbildungen bezieht, die tatsächlich zum Vermittlungscode gespeichert werden. Wenn Fachgebiete oder Fachrichtungen übergeben werden, ermitteln die Systeme des 116117 Terminservice, welche Fachgruppen dazu gehören und speichern dann nur die Fachgruppen (und Zusatz-Weiterbildungen, wenn im Request vorhanden). Da es Fachgebiete und Fachrichtungen mit mehr als einer Fachgruppe gibt, kann es sein, dass insgesamt mehr Leistungsmerkmale zu einem Vermittlungscode gespeichert werden, als im Request angegeben. |
dringlichkeit |
in |
Für ein PTV 11 muss KEINE Dringlichkeit angeben werden; wird diese dennoch übergeben, muss sie den Wert urgent (dringend). |
bsnr |
in |
Details zur BSNR sind im zugehörigen NamingSystem KBV_NS_Base_BSNR beschrieben. |
vermittlungscode |
out |
Der Vermittlungscode besteht aus 12 zufälligen alphanumerischen Zeichen, die zur besseren Lesbarkeit an der 4. und 8. Stelle mit einem Bindestrich getrennt werden (Bsp.: XN6P-F4HP-Z5KX). Erlaubt sind alle Großbuchstaben (A-Z) und Zahlen (0-9) mit folgenden Ausnahmen: O 0 I 1 E 3 |
Request
Die FHIR-Operation zum Abrufen eines Vermittlungscodes erfordert einen POST-Request.
Die FHIR-Operation erfordert und erlaubt verschiedene Eingabeparameter. Die Eingabeparameter müssen in einer Parameters-Ressource im XML-Format im Request Body übergeben werden (siehe hierzu Abschnitt Request Body
).
| HTTP Method | POST |
| URL | https://vermittlungscode-anfordern.eterminservice.kv-safenet.de/pvs/vermittlungscode-anfordern/api/$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 |
ja | Gibt den ursprünglichen Medien- bzw. Dateitypen der Ressource an.
|
application/fhir+xml |
Accept |
nein | Gibt an, welche Inhaltstypen die Systeme des Anfragenden verstehen.
|
application/fhir+xml |
Request Body
Der Request Body muss eine Parameters-Ressource enthalten, die mindestens die folgenden verpflichtenden Eingabeparameter enthalten muss:
leistungsmerkmale: Leistungsmerkmale, die der Patient mit dem Vermittlungscode buchen können sollbsnr: BSNR der Praxis / medizinischen Einrichtung, die den Vermittlungscode für einen Patienten anfordertueberweisenderArzt: Arzt, der dem Patienten die Überweisung ausstellt
Darüber hinaus können auch die folgenden optionalen Eingabeparameter enthalten sein:
dringlichkeit: Dringlichkeit der Überweisungpatient: Patient, für den die Überweisung ausgestellt wurde
Beispiel
POST https://vermittlungscode-anfordern.eterminservice.kv-safenet.de/pvs/vermittlungscode-anfordern/api/$vermittlungscode_anfordern
Content-Type: application/fhir+xml
WICHTIG: Der Request Body mit der Parameters-Ressource ist in diesem Beispiel NICHT enthalten. Beispiele für Parameters-Ressourcen mit den Eingabeparametern sind hier im vorliegenden Projekt zu finden. Einige Beispiele sind auch noch einmal am Ende dieser Seite dargestellt.
Response
Die FHIR-Operation gibt bei Erfolg den HTTP-Statuscode 200 OK und eine Parameters-Ressource mit den Ausgabeparametern der FHIR-Operation als Response Body zurück.
Im Fehlerfall wird ein dem Fehler entsprechender HTTP-Statuscode (bspw. 400 Bad Request oder 500 Internal Server Error) sowie 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 Parameters-Ressource mit den Ausgabeparametern der FHIR-Operation im XML-Format enthalten. Die Parameters-Ressource inkludiert den angefragten Vermittlungscode sowie die URL, unter der Termine mit dem Vermittlungscode gebucht werden können.
Im Fehlerfall ist im Response Body ein OperationOutcome enthalten. Details hierzu sind unter Profil: Fehler (OperationOutcome) zu finden.
Beispiele
Beispiel 1: Erfolgsfall
HTTP/1.1 200
x-ets-application: Vermittlungscode-anfordern
content-type: application/fhir+xml
Beispiel 2: Fehlerfall
HTTP/1.1 400
x-ets-application: Vermittlungscode-anfordern
content-type: application/fhir+xml
Alle Beispiele für die Parameters-Ressourcen mit den Ausgabeparametern (Response Body) sind hier im vorliegenden Projekt zu finden.
Alle Beispiele für den Fehlerfall sind hier im vorliegenden Projekt zu finden.