Operation API: Medikationsplanhistorie abrufen

Die Operation $medication-plan-history ermöglicht es, die Historie eines Medikationsplans abzurufen. Diese Operation ist besonders nützlich, um eine Übersicht über alle Versionen des elektronischen Medikationsplans (eMP) zu erhalten. Ein ePA-Client kann diese Informationen nutzen, um zu verstehen, welche Versionsnummern der Plan hat, wann und von wem der Plan bearbeitet wurde. Mit der Versionsnummer ist es dem ePA-Client möglich, eine bestimmte Version des eMP-Dokuments abzurufen.

OperationDefinition

Operation Definition: Get Medication Plan History

Geschäftslogik

Voraussetzungen

Dem Medication Service MÜSSEN zur Auswertung in Operationen für jede Aktivität die folgenden Informationen bereitstehen:

Name des Nutzers
Nutzergruppe/Rolle ((profession-)oid)
Kennung (Telematik-ID oder KVNR)
Hinweis auf eine gültige Befugnis des aktuellen Benutzers (requestor)

HTTP Header-Parameter

Ein ePA-Client MUSS die folgenden HTTP Header bei einer Anfrage an den Medication Service setzen:

Name	Anforderung	Datentyp	Beschreibung
x-insurantid	MUSS	String	Health Record Identifier
x-useragent	KANN	String	User Agent Information
X-Request-ID	MUSS	String	UUID der Nachricht

Wiederholungsintervalle

Die folgenden Wiederholungsintervalle werden im Falle einer Fehlerantwort definiert:

'409' Conflict (statusMismatch)
- etwa 24 Stunden
'500' Internal Error
- etwa 10 Minuten

Erlaubte Nutzergruppen

professionOID
oid_versicherter
oid_praxis_arzt
oid_krankenhaus
oid_institution
oid_krankenhaus
oid_institution-vorsorge-reha
oid_zahnarztpraxis
oid_praxis_psychotherapeut
oid_institution-oegd
oid_öffentliche_apotheke
oid_institution-pflege
oid_institution-geburtshilfe
oid_praxis-physiotherapeut
oid_institution-arbeitsmedizin

Interaktion ($medication-plan-history)

GET [base]/epa/medication/api/v1/fhir/$medication-plan-history

OperationId: getMedicationPlanHistory_MedicationSvc

{
    "resourceType": "Parameters",
    "id": "example-epa-op-history-medication-plan-in-parameters-1",
    "meta": {
        "profile":  [
            "https://gematik.de/fhir/epa-medication/StructureDefinition/epa-op-history-medicationplan-out-parameters"
        ]
    },
    "parameter":  [
        {
            "name": "history",
            "part":  [
                {
                    "name": "planVersion",
                    "valueId": "1"
                },
                {
                    "name": "lastUpdated",
                    "valueDateTime": "2025-07-15T13:00:00Z"
                }
            ]
        },
        {
            "name": "history",
            "part":  [
                {
                    "name": "planVersion",
                    "valueId": "2"
                },
                {
                    "name": "lastUpdated",
                    "valueDateTime": "2025-10-15T14:00:00Z"
                }
            ]
        },
        {
            "name": "operationOutcome",
            "resource": {
                "resourceType": "OperationOutcome",
                "id": "255002c7-aa1b-4163-bdd4-ede482453cca",
                "meta": {
                    "profile":  [
                        "https://gematik.de/fhir/epa/StructureDefinition/epa-operation-outcome"
                    ]
                },
                "issue":  [
                    {
                        "severity": "information",
                        "code": "informational",
                        "details": {
                            "coding":  [
                                {
                                    "code": "MEDICATIONSVC_OPERATION_SUCCESS",
                                    "system": "https://gematik.de/fhir/epa/CodeSystem/epa-operation-outcome-codes-cs",
                                    "display": "Operation Successfully Completed in Medication Service"
                                }
                            ]
                        }
                    }
                ]
            }
        }
    ]
}

<Parameters xmlns="http://hl7.org/fhir">
    <id value="example-epa-op-history-medication-plan-in-parameters-1" />
    <meta>
        <profile value="https://gematik.de/fhir/epa-medication/StructureDefinition/epa-op-history-medicationplan-out-parameters" />
    </meta>
    <parameter>
        <name value="history" />
        <part>
            <name value="planVersion" />
            <valueId value="1" />
        </part>
        <part>
            <name value="lastUpdated" />
            <valueDateTime value="2025-07-15T13:00:00Z" />
        </part>
    </parameter>
    <parameter>
        <name value="history" />
        <part>
            <name value="planVersion" />
            <valueId value="2" />
        </part>
        <part>
            <name value="lastUpdated" />
            <valueDateTime value="2025-10-15T14:00:00Z" />
        </part>
    </parameter>
    <parameter>
        <name value="operationOutcome" />
        <resource>
            <OperationOutcome>
                <id value="255002c7-aa1b-4163-bdd4-ede482453cca" />
                <meta>
                    <profile value="https://gematik.de/fhir/epa/StructureDefinition/epa-operation-outcome" />
                </meta>
                <issue>
                    <severity value="information" />
                    <code value="informational" />
                    <details>
                        <coding>
                            <system value="https://gematik.de/fhir/epa/CodeSystem/epa-operation-outcome-codes-cs" />
                            <code value="MEDICATIONSVC_OPERATION_SUCCESS" />
                            <display value="Operation Successfully Completed in Medication Service" />
                        </coding>
                    </details>
                </issue>
            </OperationOutcome>
        </resource>
    </parameter>
</Parameters>

Antwort-Status-Codes

Status Code	Bedingung	Error Code	Bemerkung
200	Successful operation		EPA OperationOutcome
400	Invalid request		EPA OperationOutcome
403	Requestor role is not in the list of allowed user groups	invalidOid
403	Requestor is not entitled	notEntitled
403	ID-Token or Insurant-ID mismatch		EPA OperationOutcome
404	Health record is in state UNKNOWN or INITIALIZED	noHealthRecord	(siehe 'Wiederholungsintervalle')
409	Health record is in state SUSPENDED	statusMismatch	(siehe 'Wiederholungsintervalle')
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
500	Any other error	internalError	(siehe 'Wiederholungsintervalle')

Serviceübergreifende Error Codes ohne Verweis auf EPA OperationOutcome MÜSSEN mit dem entsprechenden HTTP Status Code vom Medication Service mit dem Media Type application/json nach folgendem Schema zurückgegeben werden:

{
  "errorCode": "statusMismatch"
}