Implementation Guide
ePA Medication Service
Version 1.0.5-1 - release

## Operation API: Medikationsliste abrufen (eML)

Die Query-Operation Medikationsliste abrufen (eML) liefert die elektronische Medikationsliste (eML) in Form eines FHIR searchSet-Bundles. In der eML werden ausschließlich nicht stornierte Instanzen von Verschreibungsdaten (MedicationRequest) und Dispensierdaten (MedicationDispense) angezeigt.

Für eine vollständige historische Einsicht, einschließlich stornierter Einträge, können die entsprechenden Query APIs genutzt werden. Zusätzlich ermöglicht die optionale Eingabe eines Datumsbereichs eine verlaufsbasierte Ansicht auf relevante Medikationen.

### Nachricht

Die Nachricht zum Abruf der FHIR-Instanzen der elektronischen Medikationsliste (eML) wird als HTTP GET-Anfrage an den Medication Service gesendet.

#### Auslösung

Wenn das ePA-Client-System die elektronische Medikationsliste (eML) als strukturierte FHIR-Daten abrufen möchte, sendet es eine Operation API: Medikationsliste abrufen (eML)-Anfrage an den Medication Service. Der Medication Service verarbeitet die Anfrage und stellt die Medikationsliste zur Verfügung, damit sie im ePA-Client-System angezeigt werden kann.

#### FHIR Query Operation API

Der Medication Service MUSS die Operation API: Medikationsliste abrufen (eML) gemäß der FHIR OperationDefinition Get Medication List ausführen. contentTypes: - "application/fhir+json" headerParams: - name: "x-insurantid" expectation: "MUSS" type: "string" description: "Health Record Identifier" - name: "x-useragent" expectation: "MUSS" type: "string" description: "User Agent Information" - name: "X-Request-ID" expectation: "MUSS" type: "string" description: "UUID der Nachricht" base: "[base]" paths: /epa/medication/api/v1/fhir/$medication-list: get: include: - "#default-api" operationId: "getMedicationList_MedicationSvc" fhir: searchParams: - name: "date" definition: "-" type: "date" expectation: "MUSS" documentation: "Begrenzt die Suche auf ein bestimmtes Datum oder einen Zeitraum durch Angabe einer oberen und/oder unteren Grenze" - name: "_count" definition: "-" type: "integer" expectation: "MUSS" documentation: "Bestimmt die Anzahl der Einträge pro Seite (page)" - name: "_offset" definition: "-" type: "integer" expectation: "MUSS" documentation: "Bestimmt das Startelement der Seite (page)" responses: - statusCode: '200' description: "Successful operation" errorCode: "-" note: "-" - statusCode: '400' description: "Unknown search parameter" errorCode: "-" note: "EPAOperationOutcome" - statusCode: '400' description: "Invalid query parameter(s)" errorCode: "-" note: "EPAOperationOutcome" - statusCode: '400' description: "Invalid request" errorCode: "-" note: "EPAOperationOutcome" responseExamples: - name: "application/fhir+json" type: JSON url: './Bundle-example-get-medication-list-bundle1.json'

Zusätzlich ermöglicht der Parameter date die Eingrenzung eines Datumsbereichs, indem obere und untere Grenzen definiert werden. So können gezielt Medikations-, Verschreibungs- und Dispensierdaten innerhalb eines bestimmten Zeitraums abgerufen werden

Beispiel für eine Datumsfilterung:

    GET [base]/epa/medication/api/v1/fhir$medication-list&amp;date=le2025-12-24&amp;date=ge2025-01-01

Der Medication Service MUSS sicherstellen, dass das Suchergebnis der Operation Medikationsliste abrufen (eML) ausschließlich relevante Instanzen enthält.
Das zurückgegebene FHIR Search Set Bundle MUSS folgende Instanzen enthalten:

- Alle Medication-Instanzen, die von einer MedicationRequest oder MedicationDispense referenziert werden.
- Alle relevanten MedicationRequest-Instanzen.
- Alle relevanten MedicationDispense-Instanzen.
- Alle PractitionerRole- und Organization-Instanzen, die in den MedicationRequest- und MedicationDispense-Instanzen referenziert werden.
- Alle Practitioner-Instanzen und Organization-Instanzen, die von einer PractitionerRole referenziert werden.

Der Medication Service MUSS in der Operation Medikationsliste abrufen (eML) sicherstellen, dass stornierte Instanzen nicht in das Suchergebnis aufgenommen werden. Dabei gelten folgende Ausschlusskriterien:

- Eine MedicationRequest-Instanz MUSS ausgeschlossen werden, wenn ihr status auf cancelled gesetzt ist.
- Eine MedicationDispense-Instanz MUSS ausgeschlossen werden, wenn ihr status entweder auf cancelled oder declined gesetzt ist.
- Eine Medication-Instanz MUSS ausgeschlossen werden, wenn sie ausschließlich von stornierten MedicationRequest- oder MedicationDispense-Instanzen referenziert wird. Falls eine Medication-Instanz sowohl von einer stornierten als auch von einer nicht stornierten Instanz referenziert wird, MUSS sie im Suchergebnis enthalten bleiben.

Der Medication Service MUSS das Suchergebnis der Operation Medikationsliste abrufen (eML) nach dem Verordnungsdatum sortieren.

- Die Sortierung MUSS anhand des Attributs MedicationRequest.authoredOn erfolgen.
- Die Reihenfolge MUSS in absteigender Sortierung (desc) sein, sodass die neuesten Verordnungen zuerst angezeigt werden.

Der Medication Service MUSS in der Operation Medikationsliste abrufen (eML) die Paginierung unterstützen, um eine Verarbeitung und Navigation großer Datenmengen zu ermöglichen. Die Implementierung der Paginierung erfolgt gemäß den allgemeinen Paginierungsanforderungen des FHIR Data Service.

In der Operation Medikationsliste abrufen (eML) können neben den Standardpaginierungsparametern wie _count und _offset weitere Parameter enthalten sein, die die Paginierung erleichtern. Ein Beispiel hierfür ist der Parameter stateid, der den aktuellen Zustand der Ergebnisliste repräsentiert. Dies ermöglicht es dem Medication Service, die Navigation durch die Ergebnisse effizient zu verwalten, indem der Kontext oder Zustand der Suche erhalten bleibt.

Der Medication Service MUSS sicherstellen, dass alle referenzierten Instanzen innerhalb einer einzelnen Ergebnisseite der Paginierung enthalten sind. Eine referenzierte Instanz MUSS in derselben Seite wie die Instanz enthalten sein, die auf sie verweist. Dies gilt für die folgenden Ressourcen: Medication, MedicationRequest, MedicationDispense, PractitionerRole, Practitioner und Organization. Der Medication Service MUSS bei Angabe eines Datum-Parameters (date)

- Alle Medication-Instanzen abrufen, die von MedicationRequest-Instanzen mit authoredOn innerhalb des angegebenen Datumsbereichs referenziert werden, unter Ausschluss stornierter Instanzen
- Alle Medication-Instanzen abrufen, die von MedicationDispense-Instanzen mit whenHandedOver innerhalb des angegebenen Datumsbereichs referenziert werden, unter Ausschluss stornierter Instanzen
- Alle MedicationRequest- und MedicationDispense-Instanzen abrufen, unter Ausschluss stornierter Instanzen

Der Medication Service MUSS, wenn kein Datum-Parameter (date) in den Input-Parametern angegeben ist

- Alle Medication-Instanzen abrufen, die von MedicationDispense- und MedicationRequest-Instanzen referenziert werden, unter Ausschluss stornierter Instanzen.
- Alle MedicationRequest- und MedicationDispense-Instanzen abrufen, unter Ausschluss stornierter Instanzen

### Sicherheitsanforderungen

Generelle Sicherheitsanforderungen werden hier festgehalten.