Terminslots anlegen (Slot Batch Create)

Inhalt

1. Beschreibung und fachlicher Kontext
2. Request
   • Request Header
   • Request Body
   • Beispiel
3. Response
   • Response Header
   • Response Body
   • Beispiele

Beschreibung und fachlicher Kontext

Beim Anlegen mehrerer Terminslots handelt es sich um die FHIR-Standardinteraktion batch.

Diese Interaktion ermöglicht die Übermittlung mehrerer neu angelegter Terminslots an die Systeme des 116117 Terminservices. Dadurch sind die neuen Terminslots 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 neu angelegten Terminslots angezeigt und können gebucht werden.

Bei der Erstellung neuer Terminslots kann deren Verfügbarkeit auf anderen Systemen über das Feld Slot.extension.buchbarDurch gesteuert werden. Eine Erstellung ohne Verfügbarkeit ist nicht vorgesehen. Daher wird vom System des 116117 Terminservices mindestens ein Wert für buchbarDurch erwartet. Wird kein Wert übermittelt, antwortet das System mit einem Fehler.

Ein neuer Terminslot wird immer auf Grundlage eines Terminprofils erstellt. Im neu zu erstellenden Terminslot ist das zugrundeliegende Terminprofil über die Terminprofil-ID referenziert. Diese ID wird ausschließlich von den Systemen des 116117 Terminservices festgelegt. Es ist daher notwendig, dass ein TVS die korrekte Terminprofil-ID kennt, um einen Terminslot anlegen zu können. Die Terminprofil-ID kann mithilfe der Interaktion Terminprofile abrufen (Schedule Search) ermittelt werden.

Request

Das Anlegen mehrerer Terminslots erfordert einen POST-Request.

Im Request Body muss ein Bundle mit den neu anzulegenden Terminslots übergeben werden (siehe hierzu Abschnitt Request Body).

Request Header

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

Request Body

Der Request Body muss ein Batch Request Bundle enthalten. Dieses Bundle muss alle Terminslots enthalten, die im 116117 Terminservice erstellt werden sollen. Pro neu zu erstellendem Terminslot muss es daher ein Bundle.entry mit folgenden Informationen geben:

• Request-ID: im Feld Bundle.entry.id

• Angabe, dass es sich um einen POST-Request handelt: im Feld Bundle.entry.request.method

• Angabe, dass es sich um eine Slot-Ressource handelt: im Feld Bundle.entry.request.url

• Zu erstellender Terminslot: im Feld Bundle.entry.resource

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

Bitte beachten: Für neu zu erstellende Terminslots gilt:

• Die ID eines Terminslots (zu finden im Feld Slot.id) wird ausschließlich durch die Systeme des 116117 Terminservices festgelegt. Wird in dem Batch Request Bundle ein Terminslot mit ID übergeben, so wird diese ID von den Systemen des 116117 Terminservices NICHT verarbeitet.

• Der Status eines Terminslots (zu finden im Feld Slot.status) muss beim Erstellen immer den Wert free haben. Ist dies nicht der Fall, kommt ein Fehler mit dem HTTP-Statuscode 412 Precondition Failed zurück.

• Das zugrundeliegende Terminprofil (referenziert im Feld Slot.schedule) muss anhand der Terminprofil-ID referenziert werden. Diese kann mithilfe der Interaktion Terminprofile abrufen (Schedule Search) ermittelt werden.

• Der Slot muss durch mindestens ein System buchbar sein. Daher wird im Feld Slot.extension.buchbarDurch mindestens ein Wert erwartet.

Beispiel

# Erstelle mehrere Terminslots
POST https://terminsynchronisation.eterminservice.kv-safenet.de/pvs​/terminsynchronisation/api/Slot/batch
Content-Type: application/application/fhir+xml
If-Match: 1

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

Response

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

Wurde ein Terminslot erfolgreich angelegt, so wird für den Einzel-Request zum Anlegen dieses Terminslot der HTTP-Statuscode 201 Created im Batch Response Bundle gespeichert. Der neu erstellte Terminslot ist zudem IMMER im Batch Response Bundle enthalten.

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 entweder den neu angelegten Terminslot oder ein OperationOutcome mit Details zum aufgetretenen Fehler. So kann das TVS prüfen, welche Terminslots erfolgreich angelegt wurden und welche nicht.

Beispielhaft veranschaulicht bedeutet das Folgendes:

1. Ein TVS schickt ein Batch Request Bundle mit vier Terminslots an die Systeme des 116117 Terminservices.

2. Die Systeme des 116117 Terminservices validieren den Request und stellen fest, dass URL, Request Header, Request Body usw. valide sind.

3. Die Systeme des 116117 Terminservices beginnen mit der Verarbeitung der Einzel-Requests:

   1. Terminslot 1 kann ohne Probleme erstellt werden. Die Systeme des 116117 Terminservices erstellen ein Batch Response Bundle und speichern darin die Response zu Einzel-Request 1 (Erstellung von Terminslot 1): HTTP-Statuscode 201 Created und der neu erstellte Terminslot

   2. Beim Erstellen von Terminslot 2 tritt ein Fehler auf, da der Terminslot in der Vergangenheit liegt. Die Systeme des 116117 Terminservices fügen dem Batch Response Bundle die Response zu Terminslot 2 hinzu: HTTP-Statuscode 400 Bad Request und die Details zum Fehler TVSTS0086: Der Slot liegt in der Vergangenheit.

   3. Beim Erstellen 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 erstellt werden. Die Systeme des 116117 Terminservices fügen dem Batch Response Bundle die Response zu Terminslot 4 hinzu: HTTP-Statuscode 201 Created und der neu erstellte Terminslot

4. Die Systeme des 116117 Terminservices schicken den HTTP-Statuscode 200 OK sowie das vollständige Batch Response Bundle (im Response 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:

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.

Beim Erstellen eines Terminslots im 116117 Terminservice wird dem Terminslot automatisch eine ID (im Feld Slot.id) und eine Version (im Feld Slot.meta.versionId) zugewiesen. Beide Felder sind in den Terminslots, die im Batch Response Bundle im Feld Bundle.entry.resource enthalten sind, befüllt. Die Version des neu erstellten Terminslots ist darüber hinaus auch in der zugehörigen Response des Batch Response Bundles im Feld Bundle.entry.response.etag hinterlegt. Weitere Details zum Terminslot-Profil sind unter Profil: Terminslot (Slot) 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.