FAQ: Häufig gestellte Fragen zur FHIR-API

Zusammenstellung der häufig gestellten Fragen von Drittanbietern zur T2med FHIR-API (aus dem E-Mail-Verkehr), gegliedert nach technischen, vertraglichen und allgemeinen Fragen. Namen, Firmennamen und persönliche Daten wurden entfernt.

Technische Fragen

Kann ich über die API die eAkte eines anderen Patienten in T2med öffnen (Deep-Link, z. B. per Telefonnummer-Klick)?

Nein, aktuell nicht vorgesehen. Ein Aufruf einer Web-Adresse/Deep-Link soll perspektivisch möglich werden, ist aber Stand jetzt noch nicht umgesetzt – der Device-Flow ist derzeit der bessere Weg. Die API ist so konzipiert, dass der Aufruf per Deep Link von T2med an die Drittanbieter-Anwendung erfolgt und diese mit dem passenden Patienten geöffnet wird. Die umgekehrte Richtung – das Öffnen von T2med mit einer bestimmten Patientenakte aus der Drittanbieter-Anwendung heraus – ist bisher nicht vorgesehen. Über den Device-Flow kann die Drittanbieter-Anwendung Daten zu einem Patienten abrufen und in dessen eAkte schreiben, den T2med-Client aber nicht fernsteuern.

Ist die FHIR-API vom Client-Rechner des Drittanbieters aus erreichbar?

Ja, genauso erreichbar wie der T2med-Client selbst vom Client-Rechner an den T2med-Server kommt; der Pfad ist in der Doku beschrieben.

Was kann man über den Device-Flow konkret tun?

Patienten suchen und anlegen, Arztrollen und Behandlungsorte suchen, daraus per createKontext() (POST /Encounter, ab Version 26.10) einen Kontext erzeugen und mit diesem Kontext in die eAkte schreiben. Dadurch lässt sich innerhalb einer Sitzung auch der Patient wechseln. Details stehen im Leitfaden unter Kontext per API anlegen. Ab Version 26.11 lässt sich zusätzlich die eAkte eines Patienten lesen, siehe eAkte lesen.

Können bestehende eAkten-Einträge/Dokumente über die API geändert werden?

Derzeit nein, es können ausschließlich neue Einträge angelegt werden. Das Aktualisieren bestehender T2med-Einträge ist geplant, ein Termin steht noch nicht fest.

Ist lesender Zugriff (Anamnesen, Befunde, Diagnosen) möglich, z. B. für automatische Dokumenterstellung?

Ja, ab Version 26.11 über die Operation $eakte am Patienten (GET /Patient/{id}/$eakte). Der lesende Zugriff liefert die eAkte des Patienten entsprechend der Ansicht im T2med-Client, einschließlich Referenzen auf Anhänge. Den Zeitraum können Sie mit start und end eingrenzen. Details und ein Beispiel stehen im Leitfaden unter eAkte lesen und in der API-Referenz.

Gibt es Filtermöglichkeiten / werden Benutzer-Sichtbarkeiten beachtet?

Beim lesenden Zugriff lässt sich derzeit der Zeitraum eingrenzen (start, end). Weitere Filter, etwa nach Eintragstyp, sind geplant. Dabei werden immer die Sichtbarkeiten des aktuellen T2med-Benutzers beachtet.

Werden bestehende API-Anbindungen durch T2med-Updates beeinträchtigt?

Nein. Die FHIR-API wird abwärtskompatibel weiterentwickelt, bestehende Anbindungen bleiben bei T2med-Updates funktionsfähig.

Wie lange sind Deep-Link-Token, Access-Token und Refresh-Token gültig?

Der Deep-Link-Token (oAuthToken) ist technisch ein normaler Access-Token und gilt wie dieser 4 Stunden (240 Minuten). Der Refresh-Token gilt 30 Tage; das ist zugleich das technische Maximum des T2med-OAuth-Servers. Bei jedem Refresh wird ein neuer Refresh-Token ausgegeben, der wieder 30 Tage gilt. Der bisherige Refresh-Token ist danach ungültig (erneute Verwendung liefert HTTP 400). Drittanbieter müssen daher nach jedem Refresh den neuen Refresh-Token speichern. Wer mindestens alle 30 Tage einen Refresh durchführt, bleibt dauerhaft angemeldet.

Zu beachten:

Beim Aufruf per Deep Link wird kein Refresh-Token ausgegeben, sondern nur der Access-Token.
Refresh-Token gibt es nur bei den Starttypen AUTARK (Device-Flow) und KOMBINIERT (Deep Link und Device-Flow), nicht bei DIREKT (Aufruf aus dem T2med-Client).
Nach Ablauf muss der Device-Flow erneut durchlaufen werden.

Wo erhalte ich das Client-Secret für den Device-Flow, und was tun, wenn es verloren gegangen ist?

Das Client-Secret wird in T2med nur einmalig angezeigt, und zwar bei der Aktivierung des Drittanbieters unter „Drittanbieter-Zugriffe verwalten“ (dafür ist das Benutzerrecht Administration|Externe API Drittanbieter-Zugriffe verwalten erforderlich). Es ist individuell pro Praxis-Installation und wird, außer beim Starttyp DIREKT, für die weitere Einrichtung benötigt. Die Client-ID entspricht in der Regel dem URI-Schema des Drittanbieters.

Ein verlorenes Client-Secret lässt sich nicht erneut anzeigen. Ein neues Secret erhalten Sie, indem Sie den Drittanbieter deaktivieren und erneut aktivieren. Den Ablauf mit Screenshots zeigt die Demo-Anwendung.

Wie komme ich an eine `kontextId`? Entsteht ein Kontext nur beim Start aus der eAkte?

Beim Deep-Link-Start wird der Kontext von T2med angelegt und mit dem Aufruf übergeben; eine reine Patientensuche per API erzeugt keinen Kontext. Kontextgebundene Aufrufe, insbesondere alle schreibenden, benötigen jedoch einen gültigen Kontext und werden ohne ihn abgelehnt (z. B. mit HTTP 422). Für den Device-Flow steht ab Version 26.10 die Methode createKontext() (POST /Encounter) zur Verfügung. Dabei werden Patient, Arztrolle und Behandlungsort angegeben, optional der Behandlungsfall. Details stehen im Leitfaden unter Kontext per API anlegen.

Wo finde ich in T2med die Drittanbieter-Anbindung? Hat das mit der Geräteliste bzw. GDT zu tun?

Nein. Die FHIR-API und die Demo-Anwendung haben keine Berührungspunkte mit der GDT-Schnittstelle oder der Geräteanbindung; der Begriff „Gerät“ ist in diesem Zusammenhang nicht zutreffend. Freigeschaltet wird die Anbindung über den Vorgang „Drittanbieter-Zugriffe verwalten“. Aufgerufen wird die Drittanbieter-Anwendung anschließend aus der eAkte des Patienten über den Tab „Drittanbieter-Programme“ der Button-Leiste. Wird sie dort nicht an der erwarteten Stelle angezeigt, lässt sich das über die Konfiguration der Funktionsleiste anpassen.

Unter welchen Adressen ist die Referenzumgebung erreichbar?

Die Referenzumgebung fhir-referenz.t2med.eu stellt ihre Dienste auf eigenen Ports bereit, die Teil der URL sind:

FHIR-API: https://fhir-referenz.t2med.eu:16567/aps/fhir/api/r4
OAuth-Server: https://fhir-referenz.t2med.eu:16596

Statt /metadata kann zum Testen z. B. GET …/r4/Organization verwendet werden. Die Referenzumgebung wird täglich um 03:00 Uhr neu gestartet; dadurch wird auch der Zähler für das Limit des Demo-API-Keys zurückgesetzt (siehe 403-Frage unten).

Kann die Demo-Anwendung gegen verschiedene T2med-Server betrieben werden?

Bisher nicht vorgesehen. Die Demo-Anwendung ist für den Betrieb gegen einen T2med-Server und damit gegen einen T2med-Auth-Dienst ausgelegt.

Gibt es eine Testumgebung / Demo-Zugang?

Ja: Referenzumgebung fhir-referenz.t2med.eu (i. d. R. aktueller develop-Stand) sowie eine öffentliche Demo-Anwendung im T2med-GitHub-Repository mit Demo-API-Key ("T2Demo", Client-ID der Demo-App: t2test). Der vollständige Integrationsleitfaden liegt im selben Repository, ebenso eine Hilfeseite zur FHIR-Schnittstelle.

clientId/clientSecret für eigene Tests des OAuth Device Flow gegen den Referenzserver?

Es gibt keinen generischen Test-Client; der Demo-API-Key aus der Demo-App führt bei Fremdanwendungen zu invalid_client. Hinweis: Beim ersten Start der Demo-App wird der DeepLink ggf. noch nicht eingerichtet – ein zweiter Aufruf hilft meist. Die Einrichtung des Device-Flows beschreibt die Demo-Anwendung.

API-Key wird plötzlich mit 403 abgelehnt ("Der FHIR-API-Key ...")

Bitte prüfen Sie zunächst, ob zusätzlich zum API-Key ein gültiges Bearer-Token (OAuth) mitgesendet wird – dies ist Pflicht. Bei Verwendung des Demo-API-Keys gilt zudem ein Limit von 100 Aufrufen pro Serverprozess (siehe Leitfaden). Besteht der Fehler weiterhin, ist ein Einzelfall-Debugging nötig.

Was passiert, wenn ein API-Key missbräuchlich verwendet wird oder in falsche Hände gerät? Kann T2med ihn austauschen, und ist dafür in den Praxen ein T2med-Update nötig?

API-Keys werden zusammen mit einer T2med-Version ausgeliefert. Ein Austausch muss bei T2med in der Entwicklung beauftragt werden. Der neue Key gelangt anschließend mit dem nächsten T2med-Update automatisch zu allen T2med-Anwendern.

Lässt sich der Zugriff auf die FHIR-API auf bestimmte Rechner beschränken, z. B. per IP-Adresse oder Hostname? Ist eine solche Funktion geplant?

Das aktuelle Konzept sieht vor, dass die FHIR-API im gesamten Praxisnetzwerk erreichbar ist. Einschränkungen sind derzeit nicht vorgesehen. Über die Konfiguration der Funktionsleiste kann jedoch festgelegt werden, an welchen Stationen der Aufruf des Drittanbieter-Clients zur Verfügung steht.

Können Dokumente (z. B. Briefe oder Berichte als PDF) über die FHIR-API in die Patientenakte geschrieben werden? Ist dafür `DocumentReference` mit dem Profil `FhirApiDocumentReferenceAnhang` vorgesehen? Wo erscheint das Dokument in der Akte (Dokumentenablage oder Karteieintrag), und lassen sich Titel bzw. Dokumententyp mitgeben?

Ja, Dokumente (z. B. PDF) werden als DocumentReference mit dem Profil FhirApiDocumentReferenceAnhang geschrieben. Pflichtangaben sind description, attachment.data und attachment.contentType; ein Titel lässt sich über attachment.title mitgeben. Das Dokument erscheint in der Kartei als Eintrag vom Typ „Dokument“ (Bilder als „Bild“). Eine Steuerung des Karteityps über ein Kürzel ist noch nicht möglich, aber geplant. T2med unterscheidet dabei nur zwischen Dokumenten (Briefen) und Bildern, nicht zwischen Arzt- und Patientenbrief. Aktuell können ausschließlich neue Einträge geschrieben werden; das Aktualisieren bestehender T2med-Einträge ist geplant.

Vertragliche Fragen

Wir sind Dienstleister im Auftrag einer Praxis, kein "Drittanbieter" – braucht man trotzdem einen Vertrag?

Ja. Der Vertrag ist Grundlage für die Erstellung eines API-Keys und regelt auch für Community-Fälle die wesentlichen Punkte. Er bezieht sich grundsätzlich auf den Drittanbieter (nicht auf die Arztpraxis).

Bleibt GDT erhalten oder wird es durch die FHIR-API abgelöst?

GDT ist etwas völlig anderes und wird nicht abgeschaltet.

Wie läuft das Onboarding ab und wie lange dauert es?

Kein langwieriger Prozess: Nach abgeschlossenen technischen Tests (Referenzumgebung/Demo-App) wird direkt ein Vertragsentwurf geschickt. Nach Vertragsabschluss folgt der produktive API-Key.

Wird der API-Key pro Praxis oder pro Drittanbieter ausgestellt?

Pro Drittanbieter (nicht pro Praxis), zentral von T2med ausgestellt und in der jeweiligen T2med-Version hinterlegt. Freischaltung erfolgt je Installation/T2med-Server – keine zentrale/gebündelte Freischaltung für mehrere Praxen auf einmal.

Wir sind kommerzieller Drittanbieter und möchten mit T2med eine exklusive Partnerschaft über die FHIR-API anstreben, wie ist das möglich?

T2med bietet allen Drittanbietern eine gleichberechtigte Partnerschaft an und bietet im Rahmen der externen FHIR-API keine exklusiven Partnerschaften oder Vertriebskooperationen an.