MEDIAN

Belegungsportal-API: Dokumentation

Einleitung

Die MEDIAN Belegungsportal-API bietet eine Schnittstelle, um Belegungsanfragen an Kliniken zu richten.

Die Belegungsanfrage durchläuft ein zweistufiges Verfahren. Zunächst wird an MEDIAN eine pseudonymisierte Kapazitätsanfrage für ein- oder mehrere MEDIAN-Kliniken gestellt. Bei dieser Kapazitätsanfrage werden nur basale, pseudonymisierte Patientendaten wie Alter und Geschlecht übermittelt. Die Kliniken antworten auf diese Anfrage mit einer Angabe, ob für das angegebene Aufnahmedatum in der MEDIAN-Klinik noch Kapazitäten verfügbar sind. Falls Kapazität vorhanden ist, muss der Anfragende die persönlichen Daten sowie ggfs. Befunde des Patienten übermitteln, damit die Klinik eine Befundprüfung durchführen und eine endgültige Zusage oder Absage erteilen kann. Die Übermittlugn der persönlichen Daten an MEDIAN erfolgt hinsichtlich des Datenschutzes somit aufgrund eines berechtigten Interesses von MEDIAN.

Technische Umsetzung

Die API ist als HTTP-API in Verbindung mit Webhooks implementiert. MEDIAN empfängt neue Anfragen über HTTPS und beantwortet sie nach Prüfung zeitversetzt mit Callbacks in Form von Webhook-Events. Die Webhook-Events werden an eine HTTPS-Adresse gesendet, die vom Anfragenden vorher konfiguriert werden muss (siehe "Subscription" unten). Für jedes Webhook-Event ist eine eigene Adresse erforderlich.

Ablauf einer Belegungsanfrage

Die Belegungsanfrage folgt einem klar definierten Ablauf:

  1. Kapazitätsanfrage an eine oder mehrere Kliniken: Der Anfragende sendet eine Kapazitätsanfrage an ein oder mehrere MEDIAN-Kliniken inkl. der zugehörigen Fachrichtung (z.B. Orthopädie) sowie einer Angabe zur Präferenz des Patienten, welche Klinik bevorzugt wird. Diese Anfrage wird vom Anfragenden über den entsprechenden Endpunkt der API gesendet (/api/v1/anfragen)

  2. Kapazität vorhanden / nicht vorhanden: Die Kliniken antworten daraufhin, ob Kapazität vorhanden ist oder nicht. Diese Antwort wird als Webhook-Event an die vom Anfragenden konfigurierte Adresse gesendet (KapazitaetVorhandenEvent bzw. KeineKapazitaetEvent).

  3. Berechtigtes Interesse der Klinik: Wenn eine Klinik Kapazität für einen Patienten hat, hat sie ein "berechtigtes Interesse", die persönlichen Daten des Patienten sowie ggfs. Befunde (z.B. OP-Berichte) zu erhalten, um eine Befundprüfung durchführen zu können. Der Anfragende übermittelt daher die erforderlichen Daten des Patienten inklusive relevanter Befunde an die Klinik unter Verwendung der entsprechenden Endpunkte der API (/api/v1/anfragen/{anfrageId}/persoenliche-daten sowie (/api/v1/anfragen/{anfrageId}/upload).

  4. Befundprüfung durch Ärzte: Nach Erhalt der persönlichen Daten und Dateien führen die Ärzte in der Klinik eine Befundprüfung durch. Diese Prüfung beinhaltet die Überprüfung der vorgelegten Befunde und Angaben (z.B. Barthel-Index, Alter, Geschlecht, Gewicht usw.).

  5. Endgültige Zusage oder Absage: Nach Abschluss der Befundprüfung erhält der Zuweiser eine endgültige Zusage für eine der angefragten Kliniken oder Absage bezüglich der Belegungsanfrage. Diese Entscheidung wird an den Anfragenden in Form von Webhook-Events kommuniziert (ZusageEvent bzw. AbsageEvent) und bildet den Abschluss des Belegungsprozesses.

Sollte der Anfragende eine Anfrage an MEDIAN stornieren wollen, etwa weil eine andere Klinik bereits die Zusage zu einer Aufnahme des Patienten erteilt hat oder der Patient doch nicht mehr verlegungsfähig ist, so kann das Storno ebenfalls über die API übermittelt werden (Endpunkt DELETE /api/v1/anfragen/{anfrageId}).

OpenAPI-Format

Die API ist im OpenAPI-Format dokumentiert. Dies ermöglicht u.a. die automatische Generierung von Client-Bibliotheken für verschiedene Programmiersprachen, mit denen die MEDIAN Belegungsportal-API genutzt werden kann. Dies kann beispielsweise mit dem OpenAPI Generator erfolgen.

Übersicht Endpunkte

Diese API bietet Endpunkte für die folgenden Funktionen an:

  • Token: Wird verwendet für die Authentifizierung (siehe unten)
  • Kliniken: Listet die an der Schnittstelle teilnehmenden MEDIAN-Kliniken sowie die verfügbaren Fachrichtungen auf.
  • Subscription: Dient der Verwaltung der URLs, an die MEDIAN Webhook-Events mit Ergebnissen sendet.
  • Belegungsanfragen> Dient der Übermittlung von Kapazitätsanfragen, der persönlichen Daten des Patienten sowie Dateien (z.B. PDF-Dateien mit Befunden) und der Stornierung von Anfragen seitens des Anfragenden.

Webhooks

Antworten auf Anfragen werden als Webhook-Nachrichten (Events) gesendet. Die Adresse, an die die Webhook-Nachrichten gesendet werden sollen, muss vom Anfragenden vorher konfiguriert werden. Die Adresse wird als "Subscription" festgelegt. Für jedes Webhook-Event muss eine separate Subscription-Adresse konfiguriert werden.

Authentifizierung mit einem Token

Die Belegungsportal-API erfordert eine Authentifizierung, um sicherzustellen, dass nur autorisierte Benutzer auf die Funktionen zugreifen können. Aus Sicherheitsgründen wird dabei auf eine Authentifierung mittels Authentifizierungstokens gesetzt. Die Authentifizierungstokens sind nur für einen begrenzten Zeitraum (1h) gültig und helfen bei der Vermeidung von sog. "Replay-Attacken".

Benutzer müssen sich anmelden, um einen Token zu erhalten, der für den Zugriff auf die API-Endpunkte benötigt wird. Die Anmeldung erfolgt über einen speziellen Endpunkt, der die Bereitstellung von Anmeldeinformationen erwartet und einen Token zurückgibt, der bei nachfolgenden Anfragen verwendet wird.

Ablauf der Authentifizierung

  1. Benutzer erhält Benutzername und Passwort von MEDIAN.

  2. Benutzer ruft den Token-Endpunkt (/api/v1/token/login) auf und authentifiziert sich mit Benutzername und Passwort, um sowohl ein sog. Access-Token als auch ein Refresh-Token zu erhalten. Beide Tokens haben nur eine begrenzte Gültigkeitsdauer.

  3. Das Access-Token wird in nachfolgenden Requests zur Authentifizierung mittels Bearer-Authentication verwendet.

  4. Ein Refresh des Access-Tokens kann mittels des Refresh-Tokens durchgeführt werden (/api/v1/token/refresh), um die Gültigkeit der Tokens zu verlängern.

Nachdem ein Benutzer erfolgreich angemeldet ist und einen Token erhalten hat, kann er die eigentlichen API-Endpunkte nutzen.

Dokumentation der API-Endpunkte (OpenAPI-Format / Swagger UI)

Im Folgenden erfolgt eine detaillierte Auflistung der Endpunkte sowie der verwendeten Datenobjekte und Webhooks-Events. Außerdem kann die API direkt hier über diese Oberfläche getestet werden. Für die Tests muss ein Access-Token unter dem grünen Button "Authorize" hinterlegt werden.

Jeder Endpunkt ist genau beschrieben. Mit einem Klick auf "Example Value", kann man sich Beispiel-JSONs anzeigen lassen, die für die Anfrage an den Endpunkt benötigt werden. Das Schema sowie die Beschreibung der JSON-Objekte sind ebenfalls hinterlegt und können unter dem jeweiligem Reiter "Schema" auch eingesehen werden.