Terminprofil aktualisieren (Schedule Update)

Inhalt

  1. Beschreibung und fachlicher Kontext
  2. Request
  3. Response

Beschreibung und fachlicher Kontext

Beim Aktualisieren eines Terminprofils handelt es sich um die FHIR-Standardinteraktion update.

Diese Interaktion ermöglicht die Übermittlung eines geänderten Terminprofils an die Systeme des 116117 Terminservices. Aktuell können folgende Werte angepasst werden:

  • Name des Terminprofils
  • Termindauer
  • Angebotene Diagnosefremdsprachen
  • Angebotene Leistungsmerkmale
  • Terminprofilhinweis
  • Zugewiesener Arzt

Dabei ist zu beachten, dass die angebotenen Leistungsmerkmale nur geändert werden können, wenn der Terminprofil-Typ MANUELL oder EXTERN ist. (Diagnosefremdsprachen und Leistungsmerkmale können sich zudem automatisch ändern, wenn sich die Leistungsmerkmale oder Diagnosefremdsprachen in den Stammdaten eines Arztes verändern, dem das Terminprofil zugewiesen ist oder der in der Praxis / medizinischen Einrichtung arbeitet, der das Terminprofil zugeordnet ist.)

Übermittelt das TVS eine Terminprofil-Ressource an die Systeme des 116117 Terminservices, in der auch andere Felder geändert wurden, so werden diese Änderungen ignoriert. Die Systeme des 116117 Terminservices werten nur die oben benannten Daten der übermittelten Terminprofil-Ressource aus. Das bedeutet, dass auch nur diese Werte im 116117 Terminservice angepasst werden.

Das Aktualisieren eines Terminprofils ist versionsabhängig. Das bedeutet, dass das TVS die Version des zu aktualisierenden Terminprofils in der Update-Anfrage an den 116117 Terminservice übermitteln muss. Stimmt die Version nicht mit der Version überein, die im 116117 Terminservice für dieses Terminprofil hinterelegt ist, bekommt der Anfragende einen Fehler zurück.


Request

Das Aktualisieren eines Terminprofils erfordert einen PUT-Request.

Die ID des zu aktualisierenden Terminprofils muss in der URL übergeben werden. In der folgenden Tabelle ist für die Terminprofil-ID der Platzhalter [id] in der Zeile URL eingetragen. Die Terminprofil-ID ist im Feld Schedule.id der Schedule-Ressource zu finden.

Die aktuelle Version des zu aktualisierenden Terminprofils muss als Request Header übergeben werden. In der folgenden Tabelle ist für die Version des Terminprofils der Platzhalter [version] in der Zeile Request Header eingetragen. Die Version des Terminprofils ist im Feld Schedule.meta.versionId der Schedule-Ressource zu finden.

Das geänderte Terminprofil muss im Request Body übergeben werden (siehe hierzu Abschnitt Request Body).

HTTP Method PUT
URL https://terminsynchronisation.eterminservice.kv-safenet.de/tvs​/terminsynchronisation/api/Schedule/[id]
Request Header If-Match: [version]
Request Body [schedule]

Bitte beachten: Laut FHIR-Standard handelt es sich bei einem PUT-Request eigentlich um ein Upsert. Das bedeutet, dass die übermittelte Ressource neu erstellt wird, wenn sie noch nicht im Zielsystem existiert. Die Systeme des 116117 Terminservices unterstützen dies jedoch NICHT. Existiert das übermittelte Terminprofil nicht in den Systemen des 116117 Terminservices, wird ein Fehler zurückgegeben.


Request Header

Folgende Request Header werden von den Systemen des 116117 Terminservices unterstützt und verarbeitet:

Header Verpflichtend? Beschreibung Wert
If-Match ja Aktuelle Version des zu aktualisierenden Terminprofils, zu finden im Feld Schedule.meta.versionId. 1
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 die Werte 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 die Werte fhir+xml und xml.
  • Es wird empfohlen, den Wert fhir+xml für diesen Header zu setzen.
 application/fhir+xml

Bitte beachten: Laut FHIR-Standard kann über den Prefer Header vom Anfragenden festgelegt werden, ob die aktualisierte Ressource im Response Body enthalten sein soll. Die Systeme des 116117 Terminservices werten diesen Header NICHT aus. Das im 116117 Terminservice aktualisierte Terminprofil wird NICHT in der Antwort (Response) auf einen PUT-Request zurückgegeben.


Request Body

Der Request Body muss das Terminprofil enthalten, das im 116117 Terminservice aktualisiert werden soll. Eine ausführliche Beschreibung des Terminprofil-Profils sowie Beispiele sind unter Profil: Terminprofil (Schedule) zu finden.


Bitte beachten:

  • Beim übermittelten Terminprofil MUSS der Wert Schedule.id gesetzt sein. Dieser Wert muss zudem mit der Terminprofil-ID aus der URL übereinstimmen. Dies soll sicherstellen, dass das richtige Terminprofil aktualisiert wird.

  • Aktuell können nur bestimmte Werte aktualisiert werden, die in der nachfolgenden Tabelle aufgelistet sind. Änderungen an anderen Werten (bspw. Terminprofiltyp) werden von den Systemen des 116117 Terminservices ignoriert.

    Angebotene Leistungsmerkmale können nur dann durch das TVS geändert werden, wenn der Terminprofil-Typ MANUELL oder EXTERN ist.

Wert FHIR-Element
Name des Terminprofils Schedule.extension:terminprofilname
Termindauer Schedule.extension:weitereParameter.extension:termindauer
Angebotene Diagnosefremdsprachen Schedule.extension:diagnosefremdsprachen
Angebotene Leistungsmerkmale Schedule.serviceType
Terminprofilhinweis Schedule.comment
Zugewiesener Arzt Schedule.actor

Beispiele

# Aktualisiere das Terminprofil mit der ID "1ec4f924-cd75-45eb-97df-8848ff792fd5" und der aktuelle Version "1"
PUT https://terminsynchronisation.eterminservice.kv-safenet.de/tvs​/terminsynchronisation/api/Schedule/1ec4f924-cd75-45eb-97df-8848ff792fd5
Content-Type: application/fhir+xml
If-Match: 1

WICHTIG: Der Request Body mit dem geänderten Terminprofil ist in diesem Beispiel NICHT enthalten. Beispiele für Terminprofile sind hier im vorliegenden Projekt zu finden. Einige Beispiele sind auch noch einmal am Ende dieser Seite dargestellt.


Response

Für das Aktualisieren eines Terminprofils wird im Erfolgsfall der HTTP-Statuscode 200 OK und die neue Version der aktualisierten Ressource als Response Header zurückgegeben.

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
ETag Gibt die Version der aktualisierten Ressource an. 2

Response Body

Im Erfolgsfall wird KEIN Response Body zurückgegeben.

Im Fehlerfall ist im Response Body ein OperationOutcome enthalten. Details hierzu sind unter Profil: Fehler (OperationOutcome) zu finden.


Beispiele

Alle Beispiele für den Fehlerfall sind hier im vorliegenden Projekt zu finden.


<Schedule xmlns="http://hl7.org/fhir">
    <id value="9b98f95a-74a9-4b6b-ba30-fc951068727d" />
    <meta>
        <versionId value="2" />
        <profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_116117_TERMINSERVICE_TVS_TERMINSYNCHRONISATION_Schedule_Slot_Profile|1.0.0" />
    </meta>
    <text>
        <status value="extensions" />
        --- We have skipped the narrative for better readability of the resource ---
    </text>
    <extension url="http://hl7.org/fhir/5.0/StructureDefinition/extension-Schedule.name">
        <valueString value="Sprechstunde auf Thai oder Schottisch-G&#228;lisch" />
    </extension>
    <extension url="https://fhir.kbv.de/StructureDefinition/KBV_EX_116117_TERMINSERVICE_TVS_TERMINSYNCHRONISATION_Foreign_Languages_For_Diagnostic_Outcome">
        <valueCoding>
            <system value="https://fhir.kbv.de/CodeSystem/KBV_CS_SFHIR_BAR_FREMDSPRACHE" />
            <code value="83" />
            <display value="Thai (Thailand)" />
        </valueCoding>
    </extension>
    <extension url="https://fhir.kbv.de/StructureDefinition/KBV_EX_116117_TERMINSERVICE_TVS_TERMINSYNCHRONISATION_Foreign_Languages_For_Diagnostic_Outcome">
        <valueCoding>
            <system value="https://fhir.kbv.de/CodeSystem/KBV_CS_SFHIR_BAR_FREMDSPRACHE" />
            <code value="107" />
            <display value="Schottisch-G&#228;lisch" />
        </valueCoding>
    </extension>
    <extension url="https://fhir.kbv.de/StructureDefinition/KBV_EX_116117_TERMINSERVICE_TVS_TERMINSYNCHRONISATION_Schedule_Slot_Profile_Extension">
        <extension url="termindauer">
            <valueDuration>
                <value value="60" />
                <unit value="minutes" />
                <system value="http://unitsofmeasure.org" />
                <code value="min" />
            </valueDuration>
        </extension>
        <extension url="terminprofiltyp">
            <valueCoding>
                <system value="https://fhir.kbv.de/CodeSystem/KBV_CS_116117_TERMINSERVICE_TVS_TERMINSYNCHRONISATION_Schedule_Slot_Profile_Type" />
                <version value="1.0.0" />
                <code value="AUTOMATISCH" />
                <display value="Vom 116117 Terminservice automatisch angelegtes Terminprofil basierend auf den Leistungsmerkmalen des jeweiligen Arztes" />
            </valueCoding>
        </extension>
    </extension>
    <active value="true" />
    <serviceType>
        <coding>
            <system value="https://fhir.kbv.de/CodeSystem/KBV_CS_SFHIR_BAS_FACHGEBIET_GROB" />
            <code value="09" />
            <display value="Kinderarzt / Kinder&#228;rztin" />
        </coding>
    </serviceType>
    <serviceType>
        <coding>
            <system value="https://fhir.kbv.de/CodeSystem/KBV_CS_SFHIR_BAR2_WBO" />
            <code value="341" />
            <display value="F&#196;/FA Kinder- und Jugendmedizin" />
        </coding>
    </serviceType>
    <actor>
        <reference value="https://fhir.kbv.de/PractitionerRole/123456789-1112223" />
    </actor>
    <comment value="Bitte n&#252;chtern kommen!" />
</Schedule>

<Schedule xmlns="http://hl7.org/fhir">
    <meta>
        <profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_116117_TERMINSERVICE_TVS_TERMINSYNCHRONISATION_Schedule_Slot_Profile|1.0.0" />
    </meta>
    <text>
        <status value="extensions" />
        --- We have skipped the narrative for better readability of the resource ---
    </text>
    <extension url="http://hl7.org/fhir/5.0/StructureDefinition/extension-Schedule.name">
        <valueString value="Sprechstunde M. Mustermensch" />
    </extension>
    <extension url="https://fhir.kbv.de/StructureDefinition/KBV_EX_116117_TERMINSERVICE_TVS_TERMINSYNCHRONISATION_Schedule_Slot_Profile_Extension">
        <extension url="termindauer">
            <valueDuration>
                <value value="15" />
                <unit value="minutes" />
                <system value="http://unitsofmeasure.org" />
                <code value="min" />
            </valueDuration>
        </extension>
    </extension>
    <actor>
        <reference value="https://fhir.kbv.de/PractitionerRole/123456789" />
    </actor>
</Schedule>

<OperationOutcome xmlns="http://hl7.org/fhir">
    <id value="cc8e9f90-31ad-4021-9639-e5b940a88a94" />
    <meta>
        <profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_116117_TERMINSERVICE_TVS_TERMINSYNCHRONISATION_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_TVS_TERMINSYNCHRONISATION_Errors" />
                <code value="TVSTS0000" />
                <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="81758936-362c-411f-9d95-7fac5b19deb6" />
    <meta>
        <profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_116117_TERMINSERVICE_TVS_TERMINSYNCHRONISATION_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_TVS_TERMINSYNCHRONISATION_Errors" />
                <code value="TVSTS0018" />
                <display value="Die Dringlichkeit ist ung&#252;ltig." />
            </coding>
        </details>
    </issue>
</OperationOutcome>