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 PTV11 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
`dringlichkeit`	`in`	Für ein PTV11 muss KEINE Dringlichkeit angeben werden; wird diese dennoch übergeben, muss sie den Wert `urgent` (dringend) haben. Andernfalls kommt ein Fehler (OperationOutcome) zurück. Der Standardwert für die Dringlichkeit für Muster 6 ist `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. Der 116117 Terminservice unterstützt `fhir+xml` und `xml`. Es wird empfohlen, den Wert `fhir+xml` für diesen Header zu setzen.	`application/fhir+xml`
`Accept`	nein	Gibt an, welche Inhaltstypen die Systeme des Anfragenden verstehen. Der 116117 Terminservice unterstützt `fhir+xml` 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 enthalten, die mindestens die folgenden verpflichtenden Eingabeparameter enthalten muss:

leistungsmerkmale: Leistungsmerkmale, die der Patient mit dem Vermittlungscode buchen können soll
bsnr: BSNR der Praxis / medizinischen Einrichtung, die den Vermittlungscode für einen Patienten anfordert
ueberweisenderArzt: Arzt, der dem Patienten die Überweisung ausstellt

Darüber hinaus können auch die folgenden optionalen Eingabeparameter enthalten sein:

dringlichkeit: Dringlichkeit der Überweisung
patient: 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.

<Parameters xmlns="http://hl7.org/fhir">
    <parameter>
        <name value="leistungsmerkmale" />
        <valueCoding>
            <system value="https://fhir.kbv.de/CodeSystem/KBV_CS_SFHIR_BAS_FACHGEBIET_GROB" />
            <code value="13" />
        </valueCoding>
    </parameter>
    <parameter>
        <name value="leistungsmerkmale" />
        <valueCoding>
            <system value="https://fhir.kbv.de/CodeSystem/KBV_CS_SFHIR_BAR2_WBO" />
            <code value="197" />
        </valueCoding>
    </parameter>
    <parameter>
        <name value="dringlichkeit" />
        <valueCoding>
            <system value="http://hl7.org/fhir/request-priority" />
            <code value="urgent" />
        </valueCoding>
    </parameter>
    <parameter>
        <name value="bsnr" />
        <valueIdentifier>
            <type>
                <coding>
                    <system value="http://terminology.hl7.org/CodeSystem/v2-0203" />
                    <code value="BSNR" />
                    <display value="Primary physician office number" />
                </coding>
            </type>
            <system value="https://fhir.kbv.de/NamingSystem/KBV_NS_Base_BSNR" />
            <value value="123456789" />
        </valueIdentifier>
    </parameter>
    <parameter>
        <name value="ueberweisenderArzt" />
        <resource>
            <Practitioner>
                <id value="c412a945-d17e-47c3-a592-da5188750919" />
                <meta>
                    <profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_116117_TERMINSERVICE_VCA_Practitioner|1.1.0" />
                </meta>
                <text>
                    <status value="extensions" />
                    <div xmlns="http://www.w3.org/1999/xhtml">Diese Practitioner-Instanz beschreibt die Ärztin 'Maxi Mustermensch' mit den ANRs '123456711', '123456722' und '123456733'.</div>
                </text>
                <identifier>
                    <type>
                        <coding>
                            <system value="http://terminology.hl7.org/CodeSystem/v2-0203" />
                            <code value="LANR" />
                            <display value="Lifelong physician number" />
                        </coding>
                    </type>
                    <system value="https://fhir.kbv.de/NamingSystem/KBV_NS_Base_ANR" />
                    <value value="123456711" />
                </identifier>
                <identifier>
                    <type>
                        <coding>
                            <system value="http://terminology.hl7.org/CodeSystem/v2-0203" />
                            <code value="LANR" />
                            <display value="Lifelong physician number" />
                        </coding>
                    </type>
                    <system value="https://fhir.kbv.de/NamingSystem/KBV_NS_Base_ANR" />
                    <value value="123456722" />
                </identifier>
                <identifier>
                    <type>
                        <coding>
                            <system value="http://terminology.hl7.org/CodeSystem/v2-0203" />
                            <code value="LANR" />
                            <display value="Lifelong physician number" />
                        </coding>
                    </type>
                    <system value="https://fhir.kbv.de/NamingSystem/KBV_NS_Base_ANR" />
                    <value value="123456733" />
                </identifier>
                <name>
                    <use value="official" />
                    <family value="Mustermensch" />
                    <given value="Maxi" />
                </name>
            </Practitioner>
        </resource>
    </parameter>
    <parameter>
        <name value="patient" />
        <resource>
            <Patient>
                <id value="12df27c6-acdc-4067-b393-93416a1cc511" />
                <meta>
                    <profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_116117_TERMINSERVICE_VCA_Patient|2.2.0" />
                </meta>
                <text>
                    <status value="extensions" />
                    <div xmlns="http://www.w3.org/1999/xhtml">Diese Patient-Instanz beschreibt Gräfin Prof. Maxi von Mustermensch</div>
                </text>
                <identifier>
                    <type>
                        <coding>
                            <system value="http://fhir.de/CodeSystem/identifier-type-de-basis" />
                            <version value="1.4.0" />
                            <code value="GKV" />
                            <display value="Gesetzliche Krankenversicherung" />
                        </coding>
                    </type>
                    <system value="http://fhir.de/sid/gkv/kvid-10" />
                    <value value="A123456789" />
                </identifier>
                <identifier>
                    <type>
                        <coding>
                            <system value="https://fhir.kbv.de/CodeSystem/KBV_CS_Base_identifier_type" />
                            <version value="1.5.0" />
                            <code value="kvk" />
                            <display value="Krankenversichertenkarte" />
                        </coding>
                    </type>
                    <system value="http://fhir.de/sid/gkv/kvk-versichertennummer" />
                    <value value="987654321" />
                </identifier>
                <name>
                    <use value="official" />
                    <family value="Mustermensch">
                        <extension url="http://fhir.de/StructureDefinition/humanname-namenszusatz">
                            <valueString value="Gr&#228;fin" />
                        </extension>
                        <extension url="http://hl7.org/fhir/StructureDefinition/humanname-own-name">
                            <valueString value="Mustermensch" />
                        </extension>
                        <extension url="http://hl7.org/fhir/StructureDefinition/humanname-own-prefix">
                            <valueString value="von" />
                        </extension>
                    </family>
                    <given value="Maxi" />
                    <prefix value="Prof.">
                        <extension url="http://hl7.org/fhir/StructureDefinition/iso21090-EN-qualifier">
                            <valueCode value="AC" />
                        </extension>
                    </prefix>
                </name>
                <telecom>
                    <system value="phone" />
                    <value value="030123456789" />
                </telecom>
                <gender value="other">
                    <extension url="http://fhir.de/StructureDefinition/gender-amtlich-de">
                        <valueCoding>
                            <system value="http://fhir.de/CodeSystem/gender-amtlich-de" />
                            <code value="D" />
                            <display value="divers" />
                        </valueCoding>
                    </extension>
                </gender>
                <birthDate>
                    <extension url="http://hl7.org/fhir/StructureDefinition/data-absent-reason">
                        <valueCode value="unknown" />
                    </extension>
                </birthDate>
                <address>
                    <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>
                        <extension url="http://hl7.org/fhir/StructureDefinition/iso21090-ADXP-additionalLocator">
                            <valueString value="3. OG Seitenfl&#252;gel" />
                        </extension>
                    </line>
                    <city value="Darmstadt" />
                    <postalCode value="64283" />
                    <country value="D" />
                </address>
                <address>
                    <type value="postal" />
                    <line value="Postfach 112233">
                        <extension url="http://hl7.org/fhir/StructureDefinition/iso21090-ADXP-postBox">
                            <valueString value="112233" />
                        </extension>
                    </line>
                    <city value="Darmstadt" />
                    <postalCode value="64283" />
                    <country value="D" />
                </address>
            </Patient>
        </resource>
    </parameter>
</Parameters>

<Parameters xmlns="http://hl7.org/fhir">
    <parameter>
        <name value="leistungsmerkmale" />
        <valueCoding>
            <system value="https://fhir.kbv.de/CodeSystem/KBV_CS_SFHIR_BAS_FACHGEBIET_GROB" />
            <code value="08" />
        </valueCoding>
    </parameter>
    <parameter>
        <name value="bsnr" />
        <valueIdentifier>
            <type>
                <coding>
                    <system value="http://terminology.hl7.org/CodeSystem/v2-0203" />
                    <code value="BSNR" />
                    <display value="Primary physician office number" />
                </coding>
            </type>
            <system value="https://fhir.kbv.de/NamingSystem/KBV_NS_Base_BSNR" />
            <value value="123456789" />
        </valueIdentifier>
    </parameter>
    <parameter>
        <name value="ueberweisenderArzt" />
        <resource>
            <Practitioner>
                <id value="12df27c7-acdc-4467-b393-93416a1cc51x" />
                <meta>
                    <profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_116117_TERMINSERVICE_VCA_Practitioner|1.1.0" />
                </meta>
                <text>
                    <status value="extensions" />
                    <div xmlns="http://www.w3.org/1999/xhtml">Diese Practitioner-Instanz beschreibt den Arzt 'Hans Topp-Glücklich' mit der LANR '123456789'.</div>
                </text>
                <identifier>
                    <type>
                        <coding>
                            <system value="http://terminology.hl7.org/CodeSystem/v2-0203" />
                            <code value="LANR" />
                            <display value="Lifelong physician number" />
                        </coding>
                    </type>
                    <system value="https://fhir.kbv.de/NamingSystem/KBV_NS_Base_ANR" />
                    <value value="123456789" />
                </identifier>
                <name>
                    <use value="official" />
                    <family value="Topp-Gl&#252;cklich" />
                    <given value="Hans" />
                </name>
            </Practitioner>
        </resource>
    </parameter>
</Parameters>

<Parameters xmlns="http://hl7.org/fhir">
    <parameter>
        <name value="vermittlungscode" />
        <valueIdentifier>
            <system value="https://fhir.kbv.de/NamingSystem/KBV_NS_116117_TERMINSERVICE_Vermittlungscode" />
            <value value="XN6P-F4UF-Z5KX" />
        </valueIdentifier>
    </parameter>
    <parameter>
        <name value="url" />
        <valueUrl value="www.116117-termine.de" />
    </parameter>
</Parameters>

<OperationOutcome xmlns="http://hl7.org/fhir">
    <id value="aae373f1-7bfb-4fb4-92ce-8e5322f4d65z" />
    <meta>
        <profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_116117_TERMINSERVICE_VCA_OperationOutcome_Error|1.0.0" />
    </meta>
    <text>
        <status value="extensions" />
        --- 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_116117_TERMINSERVICE_VCA_Errors" />
                <code value="VCA000" />
                <display value="Sonstiger Fehler. Unter diagnostics finden Sie n&#228;here Informationen zum Fehler." />
            </coding>
        </details>
        <diagnostics value="Ung&#252;ltiger Input-Parameter" />
    </issue>
</OperationOutcome>

<OperationOutcome xmlns="http://hl7.org/fhir">
    <id value="aae373f1-5bfb-4fb5-92ce-8e5322f4d63x" />
    <meta>
        <profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_116117_TERMINSERVICE_VCA_OperationOutcome_Error|1.0.0" />
    </meta>
    <text>
        <status value="extensions" />
        --- 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_116117_TERMINSERVICE_VCA_Errors" />
                <code value="VCA002" />
                <display value="Dringlichkeit passt nicht f&#252;r mitgegebene Leistungsmerkmale" />
            </coding>
        </details>
    </issue>
</OperationOutcome>