Implementation Guide
ePA Medication Service
Version 1.2.0-ballot.2 - draft

## Generelle Prinzipien

Dieser Implementation Guide verwendet die Schlüsselwörter MUSS, DARF NICHT, SOLL NICHT und KANN als deutsche Pendants des [RFC 2119], um Anforderungen als Ausdruck normativer Festlegungen zu kennzeichnen. Anforderungen werden im Implementation Guide wie folgt dargestellt:

<IG-ID-Version> - <Titel der Anforderung>
Text / Beschreibung
[<=]

### Übergeordnete Anforderungen

Der Medication Service MUSS als Ausprägung eines FHIR Data Service sämtliche Anforderungen aus [IG_TICommon#Medication] berücksichtigen. Der Medication Service MUSS als FHIR Data Service der ePA sämtliche Anforderungen aus [IG_EPABasic#Medication] berücksichtigen.

### Schnittstellenadressierung

Der Medication Service MUSS sämtliche FHIR-Schnittstellen unter den folgenden Pfaden verfügbar machen:

- `[base]/epa/medication/api/v1/fhir/`
- `[base]/epa/medication/render/`

wobei `[base]` einem gültigen Pfadnamen eines VAU-Kanals nach folgendem Schema entsprechen muss: `http://epa4all`

### Schnittstellenimplementierung

Der Medication Service MUSS zusätzlich folgende HTTP Status Codes unterstützen:

Code | Beschreibung | Error Code | Anmerkung
--- | --- | --- | ---
423 | If the insurant objected to the medication process or objected to the submission of prescription and dispensation data into the ePA system, the Medication Service is locked. | locked |

Tabelle: HTTP Status Codes für die Medication-Service-Antwortnachrichten
Falls der Versicherte der Teilnahme am digital gestützten Medikationsprozess widersprochen hat (d.h. "medication = deny") und dem Einstellen von Verordnungsdaten und Dispensierinformation durch den E-Rezept-Fachdienst nicht widersprochen hat (d.h. "erp-submission = permit") MUSS das ePA-FdV dem Versicherten beim Aufruf der elektronischen Medikationsliste (eML) oder des elektronischen Medikationsplans (eMP) erkenntlich machen, dass die eML oder der eMP aufgrund des derzeitigen Widerspruchs durch Leistungserbringer nicht eingesehen und zur Behandlung des Versicherten genutzt werden kann. Das ePA-FdV KANN es dem Nutzer ermöglichen für sein Aktenkonto oder für das Aktenkonto des zu Vertretenden unter Verwendung von der Operation API: Medikationsliste abrufen (eML), Operation API: Medikationsplan abrufen (eMP) oder der Query APIs die Medikationsliste oder den Medikationsplan oder deren Details anzuzeigen bzw. nach Details zu suchen. Das ePA-FdV MUSS es dem Nutzer ermöglichen, die Medikationsliste für sein Aktenkonto oder für das Aktenkonto des zu Vertretenden unter Verwendung von Render API: Medikationsliste abrufen (eML) anzuzeigen. Das ePA-FdV MUSS es dem Nutzer ermöglichen, den Medikationsplan für sein Aktenkonto oder für das Aktenkonto des zu Vertretenden unter Verwendung von Render API: Medikationsplan abrufen (eMP) anzuzeigen. Das Primärsystem MUSS die Operation API: Medikationsliste abrufen (eML) oder Query APIs implementieren, um die Medikationsliste oder deren Details anzuzeigen bzw. nach Details zu suchen. Das Primärsystem KANN die Render API: Medikationsliste abrufen (eML) implementieren, um die Medikationsliste anzuzeigen. Das Primärsystem MUSS die Operation API: Medikationsplan abrufen (eMP) oder Query APIs implementieren, um den Medikationsplan oder deren Details anzuzeigen bzw. nach Details zu suchen. Das Primärsystem MUSS die Render API: Medikationsplan abrufen (eMP) implementieren, um den Medikationsplan anzuzeigen.

### FHIR-spezifische Anforderungen

#### Server-spezifische Festlegungen

Die folgenden Rahmenbedingungen hinsichtlich der FHIR-Spezifikation sind für den Medication Service festgelegt.

- Der E-Rezept-Fachdienst muss sich bei jeder Übertragung von Daten in den Medication Service auf einen bestimmten Versicherten beziehen. Dazu böte es sich an, eine im Medication Service hinterlegte FHIR Patient-Ressourceninstanz direkt zu referenzieren. Aufgrund der gesetzlich intendierten, fehlenden Leseberechtigung des E-Rezept-Fachdienstes ist das jedoch nicht möglich, sodass stattdessen lediglich ein KVNR-Identifier für die Zuordnung zu einem bestimmten Versicherten übertragen wird. Konkret MÜSSEN E-Rezept-Fachdienst sowie Medication Service deshalb sicherstellen, dass die FHIR-Elemente MedicationRequest.subject.identifier sowie MedicationDispense.subject.identifier an den von HL7 Deutschland e.V. definierten Datentyp Identifier für Patient gebunden sind.
- Das Löschen von Verschreibungsdaten oder Dispensierinformationen innerhalb des E-Rezept-Fachdienstes wird im Medication Service über ein Ändern des Status (d.h. Status = “cancelled”) der jeweiligen Ressourceninstanz umgesetzt.
- Für die FHIR Operations ist es erforderlich, dass eine Referenzierung der Ressourcen innerhalb der Parameter-Instanz möglich ist.

Der Medication Service MUSS alle FHIR-Instanzen mit dem Status entered-in-error nach Zustandswechsel nach 5 Minuten löschen und dabei die Versionierungsrichtlinien beachten.

Wichtig: Gelöschte Instanzen bleiben über die FHIR-Versionshistorie weiterhin abrufbar, da keine physikalische Löschung erfolgt.

Der Medication Service MUSS sicherstellen, dass bei der Verarbeitung übermittelter Ressourcen im Rahmen einer Operation keine enthaltenen Referenzen wie subject, medicationReference, basedOn oder derivedFrom übernommen werden. Die Referenzierung innerhalb der resultierenden Ressource erfolgt ausschließlich durch die Geschäftslogik des Medication Service. Der Medication Service MUSS übermittelte id-Werte von Ressourcen im Rahmen einer Operation verwerfen und stattdessen eine neue ID vergeben, die im weiteren Verlauf der Operation verwendet wird.

#### De-Duplizierung

Die zentrale De-Duplizierung bei inhaltlich identischen Ressourcen im Medication Service ist von entscheidender Bedeutung, um sowohl den Nutzen als auch die Qualität der Daten im Medication Service zu gewährleisten. Durch den nachstehenden Ansatz wird vermieden, dass ePA-Clients eigene, möglicherweise unterschiedliche Aggregierungsalgorithmen dezentral implementieren, was zu Inkonsistenzen in den Daten des Medication Service führen könnte. Zusätzlich verbessert eine zentrale De-Duplizierung die Verknüpfbarkeit und Integration der vorhandenen FHIR-Ressourcen.

Zur eindeutigen Identifizierung werden im Rahmen einer Verschreibung und ihr zugeordnete Dispensierinformationen die folgenden Identifier erzeugt und den notwendigen FHIR-Ressourcen hinzugefügt:

Der Medication Service MUSS für jede MedicationRequest-, MedicationDispense- und Medication-Ressource einen RxPrescriptionProcessIdentifier erzeugen und dieser hinzufügen. Der RxPrescriptionProcessIdentifier MUSS nach dem Schema (E-Prescription-ID + "_" + authoredOn[YYYYMMDD]) generiert werden. Die Erzeugung dieses Identifiers MUSS durch den Medication Service erfolgen.

Beispiel-Extension für die Ressourcen Medication und MedicationDispense

      "extension" : [
        {
          "url" : "https://gematik.de/fhir/epa-medication/StructureDefinition/rx-prescription-process-identifier-extension",
          "valueIdentifier" : {
            "system" : "https://gematik.de/fhir/epa-medication/sid/rx-prescription-process-identifier",
            "value" : "160.153.303.257.459_20250122"
          }
        }
      ],

Beispiel-Identifier für die Ressource MedicationRequest

      "identifier" : [
        {
          "system" : "https://gematik.de/fhir/epa-medication/sid/rx-prescription-process-identifier",
          "value" : "160.153.303.257.459_20250122"
        }
      ],

Der Medication Service MUSS für jede MedicationRequest-, MedicationDispense- und Medication-Ressource einen RxOriginatorProcessIdentifier erzeugen und dieser hinzufügen. Der RxOriginatorProcessIdentifier MUSS nach dem Schema (Resource-ID + "_" + Prescription-ID) generiert werden. Dieser Identifier MUSS jede Prescription-ID mit der ursprünglichen Resource-ID des Erstellungssystems verknüpfen, um eine präzise Nachverfolgung und Koordination der Arzneimitteldaten zu gewährleisten. Die Erzeugung dieses Identifier MUSS durch den Medication Service erfolgen.

Beispiel

      "identifier" : [
        {
          "system" : "https://gematik.de/fhir/epa-medication/sid/rx-originator-process-identifier",
          "value" : "dc810e53-c26b-47bc-8c78-c7f79ea5f7ae_160.153.303.257.459"
        }
      ],

##### Anforderungen an den EPAMedicationUniqueIdentifier

Dieser im Medication Service erzeugte Identifier an Medication-Ressourcen stellt die Eindeutigkeit anhand von Hashwerten über Pharmazentralnummer (PZN), Wirkstoff oder Freitext sicher. Von der Hashwertbildung ausgenommen sind die FHIR-Elemente id, identifier, meta, amount, batch sowie status.

Die Erzeugung des EPAMedicationUniqueIdentifier MUSS für jede Medication beim Einstellen in den Medication Service durch die Geschäftslogik der entsprechenden FHIR-Operation generiert und der entsprechenden Medication hinzugefügt werden. Falls beim Hinzufügen einer Medication in den Medication Service ein Wert für den EPAMedicationUniqueIdentifier vorhanden ist, MUSS dieser durch den Medication Service ersetzt werden. Der Medication Service MUSS vermeiden, contained Medication-Elemente einer Medication-Instanz einen EPAMedicationUniqueIdentifier hinzuzufügen. Die contained Medication-Ressourcen müssen jedoch bei der Generierung des EPAMedicationUniqueIdentifier der übergeordneten Medication-Instanz berücksichtigt werden. Die enthaltene Medication bleibt innerhalb der Hauptinstanz ohne eigenständige Identifizierung. Der Medication Service MUSS die einzelnen Bestandteile in folgender Reihenfolge in die Hash-Berechnung einfließen lassen:

1. Medication.code – Alle Kodierungen in der Reihenfolge ihrer Angabe in der Medication-Instanz.
2. Medication.code.text – Nach Entfernung von Leerzeichen und Umwandlung in Kleinbuchstaben.
3. Medication.form – Alle Kodierungen in der Reihenfolge ihrer Angabe in der Medication-Instanz.
4. Medication.ingredient[x] – Alphabetisch sortierte Kombination aus:
   - Falls ein ingredient.itemCodeableConcept vorhanden ist, werden die Kodierungen und der Text extrahiert.
   - Falls eine ingredient.strength vorhanden ist, werden die numerischen Werte und Einheiten verarbeitet.
   - Falls ingredient.itemReference vorhanden ist, wird die Referenz gespeichert und erst nach der Verarbeitung von ingredient.itemCodeableConcept behandelt.
5. Alphabetische Sortierung der Ingredients – Nach der Kombination der Werte müssen alle Ingredients alphabetisch sortiert werden.
6. Enthaltene Medications (contained) – Falls eine über ingredient.itemReference referenzierte contained Medication existiert, wird sie rekursiv verarbeitet und alphabetisch sortiert.
7. Extensions – Berücksichtigung spezifischer Extensions mit der entsprechenden URL, wobei die Werte in Kleinbuchstaben umgewandelt, Leerzeichen entfernt und alphabetisch sortiert werden.

Der daraus resultierende Hashwert wird in Großbuchstaben dargestellt und stellt den eindeutigen EPAMedicationUniqueIdentifier dar. Der Begriff "Kodierung" in dieser Anforderung bedeutet die ausschließliche Berücksichtigung der FHIR-Elementwerte Coding.code und Coding.system des Datentyps Coding. Der Medication Service MUSS den EPAMedicationUniqueIdentifier mittels des SHA-256-Algorithmus generieren.

Beispiel:

      "identifier" : [
        {
          "system" : "https://gematik.de/fhir/epa-medication/sid/epa-medication-unique-identifier",
          "value" : "A632B2AB4232C9787E0731E3824942350070FB492EB1005A4AFA00F4BACD8AA1"
        }
      ],

###### Beispielimplementierung

Eine Beispielimplementierung für die Generierung eines SHA-256-basierten Hash-Werts ist auf [Medication_Unique_Identifier_Tool] veröffentlicht und steht als Referenz zur Verfügung.

#### Datenherausgabe

Der Medication Service MUSS die Funktion `GET [base]/epa/medication/api/v1/fhir/metadata` implementieren. Diese Funktionalität stellt sicher, dass bei einem Aufruf von `/metadata` das FHIR CapabilityStatement des Servers mit dem Namen EPAMedicationServiceServer zurückgegeben wird. Dieses Capability Statement bietet eine detaillierte Beschreibung der Fähigkeiten des Medication Service und ist entscheidend für das Verständnis der unterstützten FHIR-Funktionalitäten. Der Medication Service MUSS bei der Verarbeitung von FHIR-Operationen spezifische Statusmeldungen im Format EPA Medication Service Operation Outcome bereitstellen. Diese Statusmeldungen MÜSSEN dem Value Set EPAMSOperationOutcomeDetailsVS entsprechen und in den folgenden Fällen ausgegeben werden:

- SVC_IDENTITY_MISMATCH – Die Telematik-ID im ID-Token oder die KVNR im x-insurantid HTTP-Header stimmt nicht mit den FHIR-Daten überein.
- MEDICATIONSVC_NO_VALID_STRUCTURE – Ungültige Datenstruktur im Medication Service
- MEDICATIONSVC_PRESCRIPTION_NO_EXIST – Verschreibung nicht im Medication Service vorhanden.
- MEDICATIONSVC_PRESCRIPTION_DUPLICATE – Doppelte Verschreibung im Medication Service erkannt.
- MEDICATIONSVC_PRESCRIPTION_STATUS – Operation für den aktuellen Verschreibungsstatus nicht zulässig.
- MEDICATIONSVC_DISPENSATION_NO_EXIST – Dispensierung nicht im Medication Service vorhanden.
- MEDICATIONSVC_DISPENSATION_STATUS – Operation für den aktuellen Dispensierungsstatus nicht zulässig.
- MEDICATIONSVC_OPERATION_SUCCESS – Operation erfolgreich im Medication Service abgeschlossen.
- MEDICATIONSVC_PARAMETERS_REFERENCE_NO_EXIST – Nicht auflösbare Referenz in den übergebenen Parametern.
- MSG_NO_MATCH – Listenoperation würde in leerem Bundle resultieren.

Der Medication Service MUSS sicherstellen, dass diese Statusmeldungen in einer konsistenten und maschinenlesbaren Form ausgegeben werden, um eine eindeutige Fehlerbehandlung zu ermöglichen. Der Medication Service SOLL Diagnosedaten bei auftretenden Fehlern beim Speichern von empfangenen Daten des E-Rezept-Fachdienstes in das Element OperationOutcome.issue.diagnostics zurückgeben. Dieses gilt für folgende FHIR-Operationen:

Operation API | OperationId
--- | ---
Operation API: Verschreibungsdaten einstellen | providePrescription_MedicationSvc
Operation API: Verschreibungsdaten stornieren | cancelPrescription_MedicationSvc
Operation API: Dispensierinformationen einstellen | provideDispensation_MedicationSvc
Operation API: Dispensierinformationen stornieren | cancelDispensation_MedicationSvc

Tabelle: Rückgabe von Diagnosedaten beim Einstellen von Daten durch E-Rezept-Fachdienst

Beispiel

Ein Beispiel für die Nutzung von OperationOutcome.issue.diagnostics zur Beschreibung Validierungsfehler

    {
      "resourceType" : "OperationOutcome",
      "id" : "0a30eb5d-289f-44cf-a0bd-ec4ec38edaa8",
      "meta" : {
        "profile" : [
          🔗 "https://gematik.de/fhir/epa-medication/StructureDefinition/epa-ms-operation-outcome"
        ]
      },
      "issue" : [
        {
          "severity" : "error",
          "code" : "structure",
          "details" : {
            "coding" : [
              {
                "system" : "https://gematik.de/fhir/epa-medication/CodeSystem/epa-ms-operation-outcome-details",
                "code" : "MEDICATIONSVC_NO_VALID_STRUCTURE",
                "display" : "Invalid Data Structure in Medication Service"
              }
            ]
          },
          "diagnostics" : "Parameters.parameter[0] | Slice 'Parameters.parameter:rxPrescription.part:authoredOn': minimum required = 1, but only found 0 (from https://gematik.de/fhir/epa-medication/StructureDefinition/epa-op-provide-prescription-erp-input-parameters|1.1.5);\nParameters.parameter[0] | Parameters.parameter:rxPrescription.part: minimum required = 6, but only found 5 (from https://gematik.de/fhir/epa-medication/StructureDefinition/epa-op-provide-prescription-erp-input-parameters|1.1.5);"
        }
      ]
    }

    <OperationOutcome xmlns="http://hl7.org/fhir">
      <id value="0a30eb5d-289f-44cf-a0bd-ec4ec38edaa8"/>
      <meta>
        <profile
                 value="https://gematik.de/fhir/epa-medication/StructureDefinition/epa-ms-operation-outcome"/>
      </meta>
      <issue>
        <severity value="error"/>
        <code value="structure"/>
        <details>
          <coding>
            <system
                    value="https://gematik.de/fhir/epa-medication/CodeSystem/epa-ms-operation-outcome-details"/>
            <code value="MEDICATIONSVC_NO_VALID_STRUCTURE"/>
            <display value="Invalid Data Structure in Medication Service"/>
          </coding>
        </details>
        <diagnostics
                     value="Parameters.parameter[0] | Slice 'Parameters.parameter:rxPrescription.part:authoredOn': minimum required = 1, but only found 0 (from https://gematik.de/fhir/epa-medication/StructureDefinition/epa-op-provide-prescription-erp-input-parameters|1.1.5);
    Parameters.parameter[0] | Parameters.parameter:rxPrescription.part: minimum required = 6, but only found 5 (from https://gematik.de/fhir/epa-medication/StructureDefinition/epa-op-provide-prescription-erp-input-parameters|1.1.5);"/>
      </issue>
    </OperationOutcome>

#### Validierung

Der Medication Service MUSS bei der Validierung der FHIR-Schema- und Strukturvorgaben für FHIR-Operationen, die ausschließlich vom E-Rezept-Fachdienst genutzt werden, auf die Validierung der KBV-Schlüsseltabellen verzichten.

- Die strukturelle FHIR-Validierung der Eingabedaten muss sich auf das FHIR-Schema und die korrekte Verwendung der Ressourcen und Datentypen beschränken.
- Eine Prüfung auf zulässige Werte innerhalb der KBV-Schlüsseltabellen (z. B. für Darreichungsformen) darf nicht erfolgen.
- Der E-Rezept-Fachdienst gilt als vertrauenswürdiger Fachdienst und verwaltet die KBV-Schlüsseltabellen über einen eigenen Aktualisierungsmechanismus.

Dieses gilt für folgende FHIR-Operationen:

Operation API | OperationId
--- | ---
Operation API: Verschreibungsdaten einstellen | providePrescription_MedicationSvc
Operation API: Verschreibungsdaten stornieren | cancelPrescription_MedicationSvc
Operation API: Dispensierinformationen einstellen | provideDispensation_MedicationSvc
Operation API: Dispensierinformationen stornieren | cancelDispensation_MedicationSvc

Tabelle: OperationIds für Operation APIs
Der Medication Service MUSS sicherstellen, dass beim Erzeugen von FHIR-Ressourcen in seinen Geschäftslogiken keine FHIR-Elemente und FHIR Extensions aus den FHIR-Eingabedaten übernommen werden, welche nicht in den serviceeigenen FHIR-Profilen mittels Must Support gelistet sind. Der Medication Service MUSS bei Schreibzugriffen Angaben einer FHIR-Instanz zur FHIR-Profilkonformität im FHIR-Element meta.profile ignorieren und darf sie nicht dauerhaft in serviceeigenen FHIR-Profilen speichern.

Hinweis: Gemäß der Anforderung [IG_TICommon#IG-TI90315JPK] schreibt der Medication Service nach Validierung und Ausführung der entsprechenden Geschäftslogik das FHIR-Element meta.profile selbst.

Der Medication Service MUSS sicherstellen, dass der Text in der Extension http://ig.fhir.de/igs/medication/StructureDefinition/GeneratedDosageInstructions der übergebenen MedicationStatement-Ressource entweder gemäß den Vorgaben des DosageDgMP-Profils von HL7 Deutschland generiert wurde oder eine zulässige Freitext-Dosierungsanweisung darstellt. Bei fehlschlagender Validierung ist die Operation mit HTTP-Status 400 Bad Request und einem OperationOutcome mit dem Fehlercode MEDSVC_DOSAGE_INVALID abzulehnen.

Beispiel: OperationOutcome bei Verstoß gegen DosageDgMP-Textregeln gemäß HL7 Deutschland

    {
      "resourceType" : "OperationOutcome",
      "id" : "1a5a1db0-7bab-4d25-a43d-3ad1efb29cb5",
      "meta" : {
        "profile" : [
          🔗 "https://gematik.de/fhir/epa-medication/StructureDefinition/epa-ms-operation-outcome"
        ]
      },
      "issue" : [
        {
          "severity" : "error",
          "code" : "structure",
          "details" : {
            "coding" : [
              {
                "system" : "https://gematik.de/fhir/epa-medication/CodeSystem/epa-ms-operation-outcome-details",
                "code" : "MEDSVC_DOSAGE_INVALID",
                "display" : "Invalid dosage structure or content"
              }
            ]
          }
        }
      ]
    }

    <OperationOutcome xmlns="http://hl7.org/fhir">
      <id value="1a5a1db0-7bab-4d25-a43d-3ad1efb29cb5"/>
      <meta>
        <profile
                 value="https://gematik.de/fhir/epa-medication/StructureDefinition/epa-ms-operation-outcome"/>
      </meta>
      <issue>
        <severity value="error"/>
        <code value="structure"/>
        <details>
          <coding>
            <system
                    value="https://gematik.de/fhir/epa-medication/CodeSystem/epa-ms-operation-outcome-details"/>
            <code value="MEDSVC_DOSAGE_INVALID"/>
            <display value="Invalid dosage structure or content"/>
          </coding>
        </details>
      </issue>
    </OperationOutcome>