Anlage 2: Den Anwendungsbereich Ihres Produkts beschreiben

Bevor Sie Ihren API-Key erhalten, schließen wir einen API-Nutzungsvertrag. Teil des Vertrags ist die Anlage 2 (Anwendungsbereich). Dort beschreiben Sie, wofür Ihr Produkt die T2med FHIR-API nutzt. Diese Seite zeigt, was in Anlage 2 stehen sollte und wie detailliert die Angaben sein müssen, damit wir Ihren Entwurf zügig freigeben können.

Warum es Anlage 2 gibt

Anlage 1 beschreibt, was die API grundsätzlich kann. Das ist keine Freigabe. Genutzt werden dürfen nur die Funktionen, die in Anlage 2 stehen und von uns freigegeben wurden. Wollen Sie später weitere Aufrufe nutzen, schreiben Sie Anlage 2 fort (neue Version, neues Datum) und warten die Freigabe in Textform ab.

Für Sie bedeutet das: Eine genaue Anlage 2 schützt Ihre Anbindung. Alles, was dort sauber steht, dürfen Sie ohne weitere Rückfrage produktiv nutzen.

Wann Sie Anlage 2 erstellen

Anlage 2 beschreibt Ihr fertiges Produkt. Sinnvoll ist sie deshalb erst, wenn

die Tests der Go-live-Checkliste in der Referenzumgebung erfolgreich durchlaufen sind,
Ihre offenen Fragen geklärt sind und
Ihr Produkt fachlich feststeht.

Die Aufrufe, die Sie in der Referenzumgebung getestet haben, sind die Grundlage für Ihre Anlage 2.

Was in Anlage 2 stehen sollte

#	Abschnitt	Inhalt	Pflicht
1	Kopfdaten	Produkt, Anbieter, Versionsnummer und Datum der Beschreibung, Bezug auf Anlage 1 (Git-Tag und Profilversionen)	ja
2	Produkt und Zweck	Was macht das Produkt, wofür brauchen Sie die T2med-Anbindung, wer löst die Übertragung aus	ja
3	Einstieg, Authentifizierung und Kontext	Deep Link und/oder OAuth Device Flow, Umgang mit Kontext, Token, API-Key und Zertifikat	ja
4	Genutzte Aufrufe	Jeder lesende und schreibende Aufruf mit Ressource, Methode, Zweck und Häufigkeit	ja
5	Geschriebene Daten	Welcher Inhalt Ihres Produkts wird in welche Ressource und welches Profil abgebildet	ja, wenn Sie schreiben
6	Nicht genutzte Funktionen	Funktionen, die man bei Ihrem Produkt erwarten könnte, die Sie aber bewusst nicht nutzen	empfohlen
7	Betrieb und Fehlerbehandlung	Aufrufvolumen, Umgang mit Fehlern und Wiederholungen, Transaktion oder Einzelaufrufe	ja
8	Datenverarbeitung und Sicherheit	Wo laufen die Daten, was wird gespeichert oder protokolliert	ja
9	Geplante Erweiterungen	Funktionen, die Sie später nutzen möchten, klar getrennt vom aktuellen Umfang	optional
10	Änderungshistorie	Versionen Ihrer Anlage 2 mit Datum und Änderung	empfohlen

1. Kopfdaten

Nennen Sie Produktname, Anbieter, Versionsnummer und Datum Ihrer Beschreibung. Beziehen Sie sich auf den Stand der API aus Anlage 1. Bei jeder späteren Änderung erhöhen Sie die Versionsnummer.

2. Produkt und Zweck

Beschreiben Sie in wenigen Sätzen,

was Ihr Produkt tut und für wen,
warum Sie dafür die T2med-API brauchen (zum Beispiel Patientenzuordnung, Dokumentation, Dokumentenablage),
wie Ihr Produkt betrieben wird: lokal in der Praxis, in der Cloud oder als Cloud-Dienst mit lokaler Komponente im Praxisnetz,
ob Inhalte erst nach Freigabe durch die Ärztin oder den Arzt übertragen werden oder automatisch.

Das Betriebsmodell ist wichtig. Die FHIR-API ist im Praxisnetz erreichbar, ein direkter Zugriff aus der Cloud ist nicht vorgesehen (siehe Funktionsumfang).

3. Einstieg, Authentifizierung und Kontext

Beschreiben Sie, wie Ihre Anwendung gestartet wird und wie sie an Token und Kontext kommt:

Deep Link aus dem T2med-Client, OAuth Device Flow oder beides. Wenn Sie einen der beiden Wege nicht nutzen, schreiben Sie das dazu.
Wie Sie mit dem Kontext umgehen. Beim Device Flow gehört dazu, ob Sie den Kontext per createKontext() selbst anlegen (ab Version 26.10).
Welche Informationen Sie bei jedem Aufruf mitsenden (API-Key, Bearer-Token).
Wo API-Key, Client-Secret und Tokens gespeichert werden und dass sie nicht im Klartext in Protokollen oder im Quellcode stehen.
Wie Sie mit dem installationsspezifischen Serverzertifikat umgehen, ohne die Zertifikatsprüfung allgemein abzuschalten.

4. Genutzte Aufrufe

Das ist der wichtigste Abschnitt. Hier entscheidet sich, was wir freigeben können. Listen Sie jeden Aufruf einzeln auf, getrennt nach lesend und schreibend. Pro Aufruf gehören dazu:

Angabe	Beispiel
Ressource und Profil	`Patient`, `FhirApiPatient`
Methode und Pfad	`GET /Patient`
Suchparameter oder Operation	`identifier` (Kontext-Identifier)
Zweck und Auslöser	Zuordnung des aktiven Patienten beim Start der Sitzung
Häufigkeit	einmal je Sitzung

Die Ressourcen, Profile und Pfade finden Sie im Leitfaden und in der API-Referenz. Achten Sie darauf, nur Aufrufe zu nennen, die zur genutzten Version passen. Der lesende Zugriff auf die eAkte ($eakte) steht zum Beispiel erst ab Version 26.11 zur Verfügung.

5. Geschriebene Daten

Wenn Ihr Produkt in die Patientenakte schreibt, zeigen Sie, was wohin geschrieben wird. Am besten als Zuordnung von Produktinhalt zu Ressource und Profil:

Inhalt im Produkt	Ressource	Profil
Anamnese	`Observation`	`FhirApiObservationAnamnese`
Diagnose (ICD-10-GM)	`Condition`	`FhirApiConditionDiagnose`
Arztbrief als PDF	`DocumentReference`	`FhirApiDocumentReferenceAnhang`

Ergänzen Sie, was für die Praxis sichtbar relevant ist:

Welche Diagnoseangaben Sie setzen (Diagnosesicherheit, Seitenlokalisation, Relevanz) und mit welchen Vorgabewerten.
Wie Sie Überschriften oder Kürzel bei Freitext und Anhang bilden.
Welche Dateitypen Sie als Anhang übertragen.

6. Nicht genutzte Funktionen

Nennen Sie, was Ihr Produkt nicht tut, wenn man es erwarten könnte. Zum Beispiel: „Die Patientenakte wird nicht gelesen“, „Keine Patientensuche über Name und Geburtsdatum“ oder „Es werden keine Diagnosen als Condition geschrieben“. Das verhindert Rückfragen und grenzt den Umfang sauber ab.

7. Betrieb und Fehlerbehandlung

Aufrufvolumen: Wie viele Aufrufe fallen etwa je Nutzung an? Gibt es Polling oder geplante Jobs?
Transaktion oder Einzelaufrufe: Schreiben Sie als Transaction-Bundle oder einzeln?
Fehler: Wie reagiert Ihr Produkt auf die HTTP-Statuscodes und das OperationOutcome? Welche Fehler wiederholen Sie, welche nie?
Doppelte Einträge: Schreibzugriffe legen immer neue Einträge an. Beschreiben Sie, wie Sie vermeiden, dass eine Wiederholung zu doppelten Einträgen in der Akte führt.

8. Datenverarbeitung und Sicherheit

Wo werden die Daten aus der API verarbeitet (nur lokal, in Ihrer Cloud)?
Werden Request- und Response-Inhalte gespeichert oder protokolliert? Falls ja, was und wie lange?
Werden Daten an Dritte weitergegeben?

Wenn die Daten das Praxisnetz verlassen, beschreiben Sie den Weg und die Komponente, die das übernimmt.

9. Geplante Erweiterungen

Wenn Sie schon wissen, dass Sie später weitere Funktionen nutzen wollen, listen Sie diese getrennt vom aktuellen Umfang auf. Wichtig:

Der aktuelle Umfang und die Planung dürfen sich nicht vermischen. Nur der aktuelle Umfang wird freigegeben.
Die Nennung in Anlage 2 ersetzt nicht die Freigabe. Neue Funktionen nutzen Sie erst nach ausdrücklicher Freigabe in Textform.
Funktionen, die die API (noch) nicht anbietet, gehören ausschließlich hierher. Was in Planung ist, zeigt die Roadmap.

10. Änderungshistorie

Halten Sie jede Version Ihrer Anlage 2 mit Datum und Änderung fest. So lässt sich nachvollziehen, wann welcher Umfang freigegeben wurde.

Wie detailliert müssen die Angaben sein?

Die Detailtiefe richtet sich nach der Faustregel: Wir müssen jeden Aufruf Ihres Produkts anhand Ihrer Anlage 2 nachvollziehen können.

Zu grob	Ausreichend
„Wir schreiben Daten in die Patientenakte.“	„Anamnese, Befund und Diagnose werden nach ärztlicher Freigabe als `Observation` und `Condition` mit den T2med-Profilen angelegt (`POST /Observation`, `POST /Condition`).“
„Patient: lesend“	„`GET /Patient` per Kontext-Identifier zur Zuordnung beim Start. Keine Suche über Name und Geburtsdatum.“
„Dokumente werden übertragen.“	„PDF-Dokumente werden als `DocumentReference` mit dem Profil Anhang angelegt (`POST /DocumentReference`), je Dokument ein Aufruf, ausgelöst durch die Praxis.“
„OAuth wird unterstützt.“	„Einstieg per Deep Link. Der OAuth Device Flow wird nicht genutzt.“

Häufige Lücken

Diese Punkte führen am häufigsten zu Rückfragen:

Nur der Anwendungsfall, keine Aufrufe. Der Produktnutzen ist beschrieben, aber nicht, welche Ressourcen, Methoden und Profile genutzt werden.
Lesen und Schreiben nicht getrennt. Es bleibt offen, ob Ihr Produkt nur schreibt oder auch Daten aus der Akte liest.
Suchparameter fehlen. „Patient lesen“ kann Suche über Kontext-Identifier, über Name und Geburtsdatum oder Lesen per ID bedeuten.
Einstieg und Kontext unklar. Es steht nicht da, ob Deep Link oder Device Flow genutzt wird und wie der Kontext entsteht.
Interne Schnittstellen. Aufrufe unter /aps/rest/... sind nicht Teil der externen Drittanbieter-API. Anlage 2 beschreibt ausschließlich die FHIR-API.
Andere Schnittstellen vermischt. Wenn Ihr Produkt zusätzlich andere T2med-Schnittstellen nutzt (zum Beispiel GDT), kennzeichnen Sie klar, was nicht zur FHIR-API gehört.
Planung als Ist-Zustand. Geplante Funktionen oder Funktionen, die die API nicht bietet, stehen im aktuellen Umfang.
Keine Abgrenzung. Nicht genutzte Funktionen sind nicht genannt.
Fehlerbehandlung fehlt. Es steht nicht da, wie Fehler und Wiederholungen behandelt werden und wie doppelte Akteneinträge vermieden werden.
Keine Versionsangabe. Versionsnummer und Datum der Beschreibung fehlen.

Vorlage

Sie können die folgende Gliederung kopieren und für Ihr Produkt ausfüllen. Das Beispiel nutzt ein erfundenes Produkt.

# Anlage 2 – Anwendungsbereich

Produkt: BeispielAssistent · Anbieter: Beispiel GmbH
Version: 1.0 · Stand: TT.MM.JJJJ
Bezug: Anlage 1 (T2med FHIR API, Git-Tag XX.X, Profilversionen 1.0.0)

## 1. Produkt und Zweck
BeispielAssistent erstellt aus ärztlichen Diktaten strukturierte Dokumentation.
Die Übertragung in T2med erfolgt erst nach Freigabe durch die Ärztin oder den Arzt.
Betrieb: Server in der Praxis.

## 2. Einstieg, Authentifizierung und Kontext
Einstieg per Deep Link mit kontextId, fhirBasisUrl und oAuthToken.
Der OAuth Device Flow wird nicht genutzt.
API-Key und Tokens: ...
Zertifikat: ...

## 3. Genutzte Aufrufe

| Richtung | Methode, Pfad | Profil | Zweck und Auslöser | Häufigkeit |
| --- | --- | --- | --- | --- |
| lesen | GET /Patient?identifier=... | FhirApiPatient | Patientenzuordnung beim Start | 1× je Sitzung |
| schreiben | POST /Observation | FhirApiObservationAnamnese | Anamnese nach Freigabe | 0..1 je Sitzung |
| schreiben | POST /Condition | FhirApiConditionDiagnose | Diagnosen nach Freigabe | 0..n je Sitzung |
| schreiben | POST /DocumentReference | FhirApiDocumentReferenceAnhang | Arztbrief als PDF | 0..n je Sitzung |

## 4. Geschriebene Daten
(Zuordnung Produktinhalt → Ressource, Profil, Besonderheiten)

## 5. Nicht genutzte Funktionen
(zum Beispiel: kein Lesen der Patientenakte, keine Namenssuche)

## 6. Betrieb und Fehlerbehandlung
(Volumen, Transaktion oder Einzelaufrufe, Fehler, Wiederholungen)

## 7. Datenverarbeitung und Sicherheit
(Verarbeitung, Protokollierung, Weitergabe)

## 8. Geplante Erweiterungen
(getrennt vom aktuellen Umfang, ohne Freigabewirkung)

## 9. Änderungshistorie
- Version 1.0 (TT.MM.JJJJ): Erstfassung

Community-Projekte

Auch für Community-Projekte gehört eine Anlage 2 zum Vertrag. Die Gliederung ist dieselbe, die Angaben dürfen aber knapper sein. Entscheidend ist, dass die genutzten Aufrufe nachvollziehbar sind.