Render API: Medikationsliste abrufen
Der Medication Service unterstützt die aufbereitete Generierung einer Medikationsliste (eML) in den Datenformaten xHTML und PDF/A (d.h. hier kein FHIR).
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 (Render MedicationList)
Ein ePA-Client kann über die folgenden URL-Aufrufe die o.g. Formate anfordern:
GET [base]/epa/medication/render/v1/eml/xhtml
OperationId: renderMedicationListToHTML_MedicationSvc
GET [base]/epa/medication/render/v1/eml/pdf
OperationId: renderMedicationListToPDF_MedicationSvc
Suchparameter
Die Medikationen bei beiden eML-Ausgabeformaten können hinsichtlich des Zeitraums beeinflusst werden. Die folgenden beiden optionalen URL-Parameter im RFC 3339 Format und UTC-Zeit schränken die Medikationsliste zeitlich ein:
| Parameter | Bedeutung |
|---|---|
lowerDateTime |
Frühester Zeitpunkt zur Berücksichtigung der Medikationserstellung z.B. 2025-01-15T00:00:00 |
upperDateTime |
Spätester Zeitpunkt zur Berücksichtigung der Medikationserstellung z.B. 2025-01-15T23:59:59 |
Werden keine weiteren Suchparameter verwendet, MUSS der Medication Service standardmäßig alle Medikationen mit RxPrescriptionProcessIdentifier der letzten 12 Monate sortiert nach Verordnungsdatum für die Ausgabe berücksichtigen.
Rückgabeformate
Die folgenden Media Types (d.h. Content-Type) MUSS der Medication Service für eine erfolgreiche Ausgabe setzen:
| Ausgabeformat | Media Type | HTTP Code |
|---|---|---|
| xHTML | text/html |
200 |
| PDF/A | application/pdf |
200 |
Antwort-Status-Codes
| Status Code | Bedingung | Error Code | Bemerkung |
|---|---|---|---|
| 200 | Successful operation | ||
| 400 | Unknown or invalid search parameter (s) | ||
| 403 | Requestor role is not in the list of allowed user groups | invalidOid | |
| 404 | Health record is in state UNKNOWN or INITIALIZED | noHealthRecord | (siehe 'Wiederholungsintervalle') |
| 404 | Rendering led to empty list | noEntries | |
| 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') |
Error Codes 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"
}
Schematischer Aufbau
Die Medikationsliste wird in beiden Ausgabeformaten vom Medication Service generiert. Verbindliche Vorgaben für den schematischen Aufbau und die Benennung der Datenherkunft innerhalb des Medication Service erfolgt nachstehend. Liegen substituierte Arzneimittel vor, müssen diese pro Substitution als Listeneintrag für die Quelle herangezogen werden.
| Spaltenkopf | Quelle / Canonical URL FHIR Element-ID |
Bemerkung |
|---|---|---|
| Verordnungsdatum | https://gematik.de/fhir/epa-medication/StructureDefinition/epa-medication-request MedicationRequest.authoredOn |
|
| Dispensierdatum | https://gematik.de/fhir/epa-medication/StructureDefinition/epa-medication-dispense MedicationDispense.whenHandedOver |
|
| Wirkstoffname | Wenn vorhanden, dann wie folgt zu belegen: https://gematik.de/fhir/epa-medication/StructureDefinition/epa-medication Medication.ingredient.item[x]:itemCodeableConcept.text |
Das von der Apotheke abgegebende Arzneimittel aus dem Dispensierdatensatz MUSS anstelle des Arzneimittels aus der Verordnung angegeben werden. |
| Wirkstärke | Wenn vorhanden, dann wie folgt zu belegen: https://gematik.de/fhir/epa-medication/StructureDefinition/epa-medication Medication.ingredient.strength |
Das von der Apotheke abgegebende Arzneimittel aus dem Dispensierdatensatz MUSS anstelle des Arzneimittels aus der Verordnung angegeben werden. |
| Arzneimittelbezeichnung | Wenn vorhanden, dann bei Nicht-Wirkstoffverordnungen wie folgt zu belegen: https://gematik.de/fhir/epa-medication/StructureDefinition/epa-medication Medication.code.text |
Das von der Apotheke abgegebende Arzneimittel aus dem Dispensierdatensatz MUSS anstelle des Arzneimittels aus der Verordnung angegeben werden. |
| Form | Wenn vorhanden, dann wie folgt zu belegen: https://gematik.de/fhir/epa-medication/StructureDefinition/epa-medication Medication.form.form.coding |
Das von der Apotheke abgegebende Arzneimittel aus dem Dispensierdatensatz MUSS anstelle des Arzneimittels aus der Verordnung angegeben werden. |
| Dosierangabe/ Gebrauchsanweisung | Wenn vorhanden, dann wie folgt zu belegen: https://gematik.de/fhir/epa-medication/StructureDefinition/epa-medication-dispense MedicationDispense.dosageInstruction sonst, wenn vorhanden: https://gematik.de/fhir/epa-medication/StructureDefinition/epa-medication-request MedicationRequest.dosageInstruction |
Das von der Apotheke abgegebende Arzneimittel aus dem Dispensierdatensatz MUSS anstelle des Arzneimittels aus der Verordnung angegeben werden. |
| PZN | Bei PZN-Verordnung wie folgt zu belegen: https://gematik.de/fhir/epa-medication/StructureDefinition/epa-medication Medication.code.coding:pznCode Bei PZN-basierter Abgabe zu einer Rezepturverordnung wie folgt zu belegen: https://gematik.de/fhir/epa-medication/StructureDefinition/epa-medication Medication.ingredient.item[x]:itemCodeableConcept.coding:pznCode.code |
Das von der Apotheke abgegebende Arzneimittel aus dem Dispensierdatensatz MUSS anstelle des Arzneimittels aus der Verordnung angegeben werden. |
| Verordner | Beide Datenquellen aus der Verordnung sind zu verknüpfen: https://gematik.de/fhir/directory/StructureDefinition/PractitionerDirectory bzw. https://gematik.de/fhir/directory/StructureDefinition/OrganizationDirectory Practitioner.name + " " + Organization.name |
|
| abgebende Apotheke | https://gematik.de/fhir/epa-medication/StructureDefinition/epa-medication-dispense bzw. https://gematik.de/fhir/directory/StructureDefinition/OrganizationDirectory Organization.name in MedicationDispense.performer.actor |