Terminslots löschen (Slot Batch Delete)

Inhalt

Beschreibung und fachlicher Kontext
Request
Response

Beschreibung und fachlicher Kontext

Beim Löschen mehrerer Terminslots handelt es sich um die FHIR-Standardinteraktion batch.

Diese Interaktion ermöglicht das Löschen mehrerer Terminslots im 116117 Terminservice. Nach der Löschung sind die Terminslots nicht mehr für die Buchung durch den 116117 Terminservice verfügbar. Das bedeutet, wenn jemand (bspw. ein TSS-Mitarbeiter oder ein Patient) über den 1116117 Terminservice freie Termine sucht, werden die gelöschten Terminslots nicht mehr angezeigt und können daher auch nicht gebucht werden.

Ein Terminslots darf nur dann gelöscht werden, wenn der Status des Terminslots NICHT gebucht oder reserviert ist. Soll ein Terminslot im Rahmen einer batch interaction gelöscht werden, der einen der genanten Status besitzt, wird nur für die Löschung dieses Terminslots ein Fehler erzeugt. Die Löschung der anderen Terminslots wird dennoch fortgeführt.

Das Löschen eines Terminslots ist zudem versionsabhängig. Das bedeutet, dass das TVS die Version jedes zu löschenden Terminslots in der Anfrage an den 116117 Terminservice übermitteln muss. Soll ein Terminslot im Rahmen einer batch interaction gelöscht werden, für den nicht die gleiche Version angegeben wird, die im 116117 Terminservice gespeichert ist, wird nur für die Löschung dieses Terminslots ein Fehler erzeugt. Die Löschung der anderen Terminslots wird dennoch fortgeführt.

Request

Das Löschen mehrerer Terminslots erfordert einen POST-Request.

Im Request Body muss ein Bundle mit IDs der zu löschenden Terminslots übergeben werden (siehe hierzu Abschnitt Request Body).

HTTP Method	`POST`
URL	`https://terminsynchronisation.eterminservice.kv-safenet.de/tvs/terminsynchronisation/api/Slot/batch`
Request Body	`[bundle]`

Request Header

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

Header	Verpflichtend?	Beschreibung	Wert
`Authorization`	ja	Im Authentisierungsverfahren erhaltene 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`

Request Body

Der Request Body muss ein Batch Request Bundle enthalten. Dieses Bundle muss die IDs und die aktuelle Version aller Terminslots enthalten, die im 116117 Terminservice gelöscht werden sollen. Pro zu löschendem Terminslot muss es daher ein Bundle.entry mit folgenden Informationen geben:

Request-ID: im Feld Bundle.entry.id
Angabe, dass es sich um einen DELETE-Request handelt: im Feld Bundle.entry.request.method
ID des zu löschenden Terminslots: im Feld Bundle.entry.request.url
Aktuelle Version des zu löschenden Terminslots: im Feld Bundle.entry.request.ifMatch

Eine ausführliche Beschreibung des Batch Request Bundles sowie Beispiele sind unter Profil: Batch Request (Bundle) zu finden.

Beispiele

# Lösche mehrere Terminslots
POST https://terminsynchronisation.eterminservice.kv-safenet.de/tvs/terminsynchronisation/api/Slot/batch
Content-Type: application/application/fhir+xml

WICHTIG: Der Request Body mit dem Batch Request Bundle ist in diesem Beispiel NICHT enthalten. Alle Beispiele für Batch Request Bundles zum Löschen mehrerer Terminslots sind hier im vorliegenden Projekt zu finden und auch noch einmal am Ende dieser Seite dargestellt.

Response

Für das Löschen mehrerer Terminslots wird im Erfolgsfall der HTTP-Statuscode 200 OK sowie ein Batch Response Bundle im Response Body zurückgegeben.

Wurde ein Terminslot erfolgreich gelöscht, so wird für den Einzel-Request zur Löschung dieses Terminslot der HTTP-Statuscode 204 No Content im Batch Response Bundle gespeichert. Wurde der Terminslot bereits zu einem früheren Zeitpunkt gelöscht, wird ebenfalls der HTTP-Statuscode 204 No Content gespeichert.

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.

Bitte beachten: Ein Batch Request gilt auch dann als erfolgreich verarbeitet, wenn ein oder mehrere darin enthaltene Einzel-Requests einen Fehler verursachen. Daher enthält das Batch Response Bundle für jeden Einzel-Request aus dem Batch Request Bundle des Anfragenden eine Response. Jede dieser Responses enthält einen HTTP-Statuscode und für den Fall, dass die Löschung des Terminslots nicht erfolgreich war, ein OperationOutcome mit Details zum aufgetretenen Fehler. So kann das TVS prüfen, welche Terminslots erfolgreich gelöscht wurden und welche nicht.

Beispielhaft veranschaulicht bedeutet das Foglendes:

Ein TVS schickt ein Batch Request Bundle mit den IDs und Versionen von vier Terminslots an die Systeme des 116117 Terminservices.
Die Systeme des 116117 Terminservices validieren den Request und stellen fest, dass URL, Request Header, Request Body usw. valide sind.
Die Systeme des 116117 Terminservices beginngen mit der Verarbeitung der Einzel-Requests:
1. Terminslot 1 kann ohne Probleme gelöscht werden. Die Systeme des 116117 Terminservices erstellen ein Batch Response Bundle und speichern darin die Response zu Einzel-Request 1 (Löschung von Terminslot 1): HTTP-Statuscode 204 No Content
2. Beim Löschen von Terminslot 2 tritt ein Fehler auf, da der Terminslot im 116117 Terminservice nicht existiert. Die Systeme des 116117 Terminservices fügen dem Batch Response Bundle die Response zu Terminslot 2 hinzu: HTTP-Statuscode 404 Not Found und die Details zum Fehler TVSTS0058: Der gesuchte Slot existiert nicht.
3. Beim Löschen von Terminslot 3 tritt ein Serverproblem auf. Die Systeme des 116117 Terminservices fügen dem Batch Response Bundle die Response zu Terminslot 3 hinzu: HTTP-Statuscode 500 Internal Server Error und die Details zum Fehler TVSTS0001: Allgemeiner Fehler
4. Terminslot 4 kann ohne Probleme gelöscht werden. Die Systeme des 116117 Terminservices fügen dem Batch Response Bundle die Response zu Terminslot 4 hinzu: HTTP-Statuscode 204 No Content
Die Systeme des 116117 Terminservices schicken den HTTP-Statuscode 200 OK sowie das vollständige Batch Response Bundle (im Reseponse Body) an das TVS zurück.

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 das Batch Response Bundle enthalten. Dieses Bundle enthält zu jedem Einzel-Request aus dem Batch Request Bundle exakt eine Response. Die Zuordnung der Responses zu den jeweiligen Einzel-Requests kann anhand der Request-ID oder der Reihenfolge erfolgen. Eine ausführliche Beschreibung des Batch Response Bundles sowie Beispiele sind unter Profil: Batch Response (Bundle) 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.

<Bundle xmlns="http://hl7.org/fhir">
    <meta>
        <profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_116117_TERMINSERVICE_TVS_TERMINSYNCHRONISATION_Bundle_Batch_Request|1.0.0" />
    </meta>
    <type value="batch" />
    <timestamp value="2024-05-20T12:54:06+02:00" />
    <entry id="8f41841c-c21a-45a3-a031-6d85d0a016de">
        <request>
            <method value="DELETE" />
            <url value="Slot/66f913bd-14e7-4114-b515-165374d3f963" />
            <ifMatch value="2" />
        </request>
    </entry>
    <entry id="34adedea-b115-4a7f-bd40-e178fa4e269a">
        <request>
            <method value="DELETE" />
            <url value="Slot/182233cb-c232-441d-a0ee-d4c9d234fd38" />
            <ifMatch value="1" />
        </request>
    </entry>
    <entry id="170dd05b-ee67-4a94-b561-28cd4b4f5c5d">
        <request>
            <method value="DELETE" />
            <url value="Slot/e448d2a1-12b2-4a26-85e2-289f7b9d15d4" />
            <ifMatch value="5" />
        </request>
    </entry>
    <entry id="e18e8628-b0dc-484d-9dae-288e347130f2">
        <request>
            <method value="DELETE" />
            <url value="Slot/b0481afd-281b-4f62-8255-da0af950876f" />
            <ifMatch value="2" />
        </request>
    </entry>
</Bundle>

<Bundle xmlns="http://hl7.org/fhir">
    <meta>
        <profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_116117_TERMINSERVICE_TVS_TERMINSYNCHRONISATION_Bundle_Batch_Response|1.0.0" />
    </meta>
    <type value="batch-response" />
    <timestamp value="2024-05-20T12:54:09+02:00" />
    <entry id="8f41841c-c21a-45a3-a031-6d85d0a016de">
        <fullUrl value="urn:uuid:66f913bd-14e7-4114-b515-165374d3f963" />
        <response>
            <status value="400" />
            <outcome>
                <OperationOutcome>
                    <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" />
                        <div xmlns="http://www.w3.org/1999/xhtml">Diese OperationOutcome-Instanz enthält den Fehlercode TVSTS0000</div>
                    </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="Ein Terminslot kann nur gel&#246;scht werden, wenn keine Buchung dazu vorliegt." />
                    </issue>
                </OperationOutcome>
            </outcome>
        </response>
    </entry>
    <entry id="34adedea-b115-4a7f-bd40-e178fa4e269a">
        <fullUrl value="urn:uuid:182233cb-c232-441d-a0ee-d4c9d234fd38" />
        <response>
            <status value="204" />
        </response>
    </entry>
    <entry id="170dd05b-ee67-4a94-b561-28cd4b4f5c5d">
        <fullUrl value="urn:uuid:e448d2a1-12b2-4a26-85e2-289f7b9d15d4" />
        <response>
            <status value="500" />
            <outcome>
                <OperationOutcome>
                    <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" />
                        <div xmlns="http://www.w3.org/1999/xhtml">Diese OperationOutcome-Instanz enthält den Fehlercode TVSTS0001</div>
                    </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="TVSTS0001" />
                                <display value="Allgemeiner Fehler" />
                            </coding>
                        </details>
                    </issue>
                </OperationOutcome>
            </outcome>
        </response>
    </entry>
    <entry id="e18e8628-b0dc-484d-9dae-288e347130f2">
        <fullUrl value="urn:uuid:b0481afd-281b-4f62-8255-da0af950876f" />
        <response>
            <status value="204" />
        </response>
    </entry>
</Bundle>

<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>