Terminprofil anlegen (Schedule Create)

Inhalt

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

Beschreibung und fachlicher Kontext

Beim Anlegen eines Terminprofils handelt es sich um die FHIR-Standardinteraktion create.

Diese Interaktion ermöglicht die Übermittlung eines neu angelegten Terminprofils an die Systeme des 116117 Terminservices. Dadurch kann eine Praxis / medizinische Einrichtung individuelle Terminprofile definieren und diese zum Erstellen neuer Terminslots im 116117 Terminservice nutzen. Solche Terminprofile haben immer den Typ EXTERN. Es gibt auch andere Arten von Terminprofilen, die ebenfalls für die Erstellung neuer Terminslots genutzt werden können. (Details hierzu sind auf der Seite Profil: Terminprofil (Schedule) im Abschnitt Fachlicher Kontext zu finden.) Übermittelt ein TVS einen neu erstellten Terminslot mit einem unbekannten Terminprofil an den 116117 Terminservice, geben die Systeme des 116117 Terminservices einen Fehler zurück.

Ein Terminprofil muss immer einer Praxis / medizinischen Einrichtung zugeordnet sein. Darüber hinaus kann ein Terminprofil optional auch einem konkreten Arzt, der in dieser Praxis / medizinischen Einrichtung tätig ist, zugeordnet werden. Die Zuordnung zu einer Praxis / medizinischen Einrichtung oder einem konkreten Arzt hat folgende Auswirkungen:

Ist ein Terminprofil einem konkreten Arzt zugeordnet...

  • ... können beim Erstellen dieses Terminprofils nur Leistungsmerkmale und Diagnosefremdsprachen ausgewählt werden, die dieser Arzt besitzt bzw. anbietet.

  • ... sind auch die Terminslots, die auf Basis dieses Terminprofils erstellt werden, diesem Arzt zugeordnet.

Ist ein Terminprofil nur einer Praxis / medizinischen Einrichtung zugeordnet...

  • ... können beim Erstellen dieses Terminprofils alle Leistungsmerkmale und Diagnosefremdsprachen ausgewählt werden, die die dort tätigen Ärzte besitzen bzw. anbieten.

  • ... sind auch die Terminslots, die auf Basis dieses Terminprofils erstellt werden, KEINEM konkreten Arzt zugeordnet.


Die Zuordnung zu einer Praxis / medizinischen Einrichtung und ggf. einem Arzt erfolgt über eine PractitionerRole. Dadurch wird ersichtlich, welche Praxis / medizinische Einrichtung das Terminprofil angelegt hat und (wenn angegeben) auch, welchem dort tätigen Arzt das Terminprofil zugeordnet ist. Im neu zu erstellenden Terminprofil ist die zugehörige PractitionerRole über eine absolute URL referenziert, die wie folgt aufgebaut ist: https://fhir.kbv.de/PractitionerRole/[PractitionerRoleID]

Bitte beachten: Die URL der PractitionerRole-Referenz beginnt somit NICHT wie die Request-URLs! Stattdessen leitet sich der erste Teil der URL für eine PractitionerRole-Referenz aus der canonical URL des PractitionerRole-Profils ab: https://fhir.kbv.de/. Dahinter wird der Ressourcentyp (also PractitionerRole) und anschließend die ID der PractitionerRole angegeben.

Die PractitionerRole-ID wird ausschließlich von den Systemen des 116117 Terminservices festgelegt. Es ist daher notwendig, dass ein TVS die korrekte PractitionerRole-ID kennt, um ein neues Terminprofil anlegen zu können. Details zum Aufbau der PractitionerRole-ID sind unter Profil: PractitionerRole im Abschnitt Fachlicher Kontext zu finden. Die PractitionerRole-ID kann mithilfe der Interaktion PractitionerRole abrufen (PractitionerRole Search) ermittelt werden.


Request

Das Anlegen eines Terminprofils erfordert einen POST-Request.

Das neu anzulegende Terminprofil muss im Request Body übergeben werden (siehe hierzu Abschnitt Request Body).

HTTP Method POST
URL https://terminsynchronisation.eterminservice.kv-safenet.de/tvs​/terminsynchronisation/api/Schedule
Request Body [schedule]

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 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 neu angelegte Ressource im Response Body enthalten sein soll. Die Systeme des 116117 Terminservices werten diesen Header NICHT aus. Das im 116117 Terminservice neu erstellte Terminprofil wird in der Antwort (Response) auf einen create-Request IMMER mit zurückgegeben.


Request Body

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

Bitte beachten:

  • Die ID eines Terminprofils (zu finden im Feld Schedule.id) wird ausschließlich durch die Systeme des 116117 Terminservices festgelegt. Wird in einem create-Request ein Terminprofil mit ID übergeben, so wird diese ID von den Systemen des 116117 Terminservices NICHT verarbeitet.

  • Der Terminprofil-Typ (zu finden im Feld Schedule.extension:weitereParameter.extension:terminprofiltyp) wird ausschließlich durch die Systeme des 116117 Terminservices festgelegt. Wird in einem create-Request ein Terminprofil mit Terminprofiltyp übergeben, so wird dieser Wert von den Systemen des 116117 Terminservices NICHT verarbeitet.

  • Ein Terminprofil muss immer einer PractitionerRole zugeordnet sein. Die PractitionerRole wird im Feld Schedule.actor über eine absolute URL referenziert (siehe hierzu Abschnitt Beschreibung und fachlicher Kontext auf dieser Seite). Die dafür notwendige PractitionerRole-ID kann mithilfe der Interaktion PractitionerRole abrufen (PractitionerRole Search) ermittelt werden.


Beispiele

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 Anlegen von Terminprofilen wird im Erfolgsfall der HTTP-Statuscode 201 Created sowie das neu erstellte Terminprofil im Response Body 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
Content-Type Gibt den ursprünglichen Medien- bzw. Dateitypen der Ressource an. application/fhir+xml
Location Gibt die URL zur neu erstellten Ressource an. https://terminsynchronisation.eterminservice.kv-safenet.de/tvs​/terminsynchronisation/api/Schedule/c98db2da-9cf5-4370-b54b-ef981c53abxx
ETag Gibt die Version der neu erstellten Ressource an. 1

Response Body

Im Erfolgsfall ist im Response Body das neu erstellte Terminprofil enthalten. Beim Erstellen des Terminprofils im 116117 Terminservice wird dem Terminprofil automatisch eine ID (im Feld Schedule.id) und eine Version (im Feld Schedule.meta.versionId) zugewiesen. Beide Felder sind im Terminprofil, das im Response Body enthalten ist, befüllt. Weitere Details zum Terminprofil-Profil sind unter Profil: Terminprofil (Schedule) zu finden.

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


Beispiele

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

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>