Operation API: Medikament hinzufügen
Die $provide Operation erlaubt die Erstellung einer Medication-Ressource. Diese Operation unterstützt die Typ-Level-Interaktionen auf dem Typ Medication zum Erstellen neuer Medication-Ressourcen. Sie stellt sicher, dass die Herkunft der Medikation durch die Angabe von Informationen über die durchführende Leistungserbringerinstitution nachvollziehbar ist.
Die Operation gibt die Medication-Instanz als Antwort zurück. Referenzen werden bei der Operation nicht berücksichtigt. Falls eine Ressource-ID übermittelt wird, MUSS diese vom Medication Service neu gesetzt werden und danach im Zusammenspiel mit dem Medication Service verwendet werden.
OperationDefinition
Operation Definition: Provide Medication
Geschäftslogik (Medication Service)
Herkunftsnachweis
Der Herkunftsnachweis für die Werte aus den Input-Parametern (performer, enterer, author, unconfirmedAuthor und informant) MUSS in einer Provenance-Instanz mit dem Profil EPAProvenance gespeichert werden. Der Wert für den target Parameter MUSS auf die spezifische Version der Ressourceninstanz verweisen.
Detaillierte Informationen zur Durchführung der Erstellung der Provenance-Instanz
EPAMedicationUniqueIdentifier
Anforderungen an den EPAMedicationUniqueIdentifier
Überprüfung der Telematik-ID bei einem Schreibvorgang
Jeder Lese- und Schreibvorgang erfordert die Authentifizierung der Leistungserbringerinstitution mittels OpenID Connect. Das signierte ID-Token des Identity Providers (IDP-Dienst) MUSS die Telematik-ID des zugreifenden Nutzers enthalten. Bei einem Schreibvorgang MUSS die Übereinstimmung der Telematik-ID des Nutzers überprüft und sichergestellt werden.
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 ($provide)
POST [base]/epa/medication/api/v1/fhir/Medication/$provide
OperationId: provideMedication_MedicationSvc
Beispielanfrage
{ "resourceType": "Parameters", "id": "example-epa-op-provide-medication-input-parameters-1", "meta": { "profile": [ "https://gematik.de/fhir/epa-medication/StructureDefinition/epa-op-provide-medication-input-parameters" ] }, "parameter": [ { "name": "medication", "resource": { "resourceType": "Medication", "id": "dc810e53-c26b-47bc-8c78-c7f79ea5f7ae", "meta": { "profile": [ "https://gematik.de/fhir/epa-medication/StructureDefinition/epa-medication" ] }, "extension": [ { "url": "https://gematik.de/fhir/epa-medication/StructureDefinition/epa-medication-type-extension", "valueCoding": { "code": "781405001", "system": "http://snomed.info/sct", "display": "Medicinal product package (product)" } } ], "status": "inactive", "code": { "coding": [ { "system": "http://fhir.de/CodeSystem/ask", "code": "5682", "display": "Ibuprofen" } ] } } }, { "name": "performer", "part": [ { "name": "organization", "resource": { "resourceType": "Organization", "id": "be51e0d2-783d-4e21-b16b-1a4cd7403515", "meta": { "tag": [ { "system": "https://gematik.de/fhir/directory/CodeSystem/Origin", "code": "ldap" } ], "profile": [ "https://gematik.de/fhir/directory/StructureDefinition/OrganizationDirectory" ] }, "identifier": [ { "system": "https://gematik.de/fhir/sid/telematik-id", "value": "9-2.58.00000040" } ], "active": true, "type": [ { "coding": [ { "code": "1.2.276.0.76.4.58", "system": "https://gematik.de/fhir/directory/CodeSystem/OrganizationProfessionOID", "display": "Betriebsstätte gematik" } ] } ], "name": "gematik GmbH", "alias": [ "gematik" ], "address": [ { "text": "gematik GmbH\nFriedrichstr. 136, \n10117 Berlin", "line": [ "Friedrichstr. 136" ], "city": "Berlin", "district": "Mitte", "state": "Berlin", "postalCode": "10117", "country": "DE" } ], "contact": [ { "purpose": { "coding": [ { "code": "ADMIN", "system": "http://terminology.hl7.org/CodeSystem/contactentity-type" } ] }, "name": { "text": "gematik ITSM" }, "telecom": [ { "system": "email", "value": "betrieb@gematik.de" } ] } ] } }, { "name": "practitioner", "resource": { "resourceType": "Practitioner", "id": "498c345f-31f5-4da6-9f04-00fa2bc8af7c", "meta": { "tag": [ { "system": "https://gematik.de/fhir/directory/CodeSystem/Origin", "code": "ldap" } ], "profile": [ "https://gematik.de/fhir/directory/StructureDefinition/PractitionerDirectory" ] }, "identifier": [ { "system": "https://gematik.de/fhir/sid/telematik-id", "value": "1-1.58.00000040" }, { "system": "https://fhir.kbv.de/NamingSystem/KBV_NS_Base_ANR", "value": "123456789" } ], "active": true, "qualification": [ { "code": { "coding": [ { "code": "1.2.276.0.76.4.31", "system": "https://gematik.de/fhir/directory/CodeSystem/PractitionerProfessionOID" } ] } }, { "code": { "coding": [ { "code": "010", "system": "urn:oid:1.2.276.0.76.5.514", "display": "FA Allgemeinmedizin" } ] } }, { "code": { "coding": [ { "code": "523", "system": "urn:oid:1.2.276.0.76.5.514", "display": "FA Innere Medizin und (SP) Gastroenterologie" } ] } } ], "name": [ { "prefix": [ "Dr." ], "given": [ "Max", "Manfred" ], "family": "Musterman", "text": "Dr. Max Manfred Mustermann" } ] } }, { "name": "practitionerRole", "resource": { "resourceType": "PractitionerRole", "id": "ExampleEPAPractitionerRoleMax", "meta": { "versionId": "1", "lastUpdated": "2023-02-03T11:20:00+01:00", "profile": [ "https://gematik.de/fhir/epa/StructureDefinition/epa-practitioner-role" ] }, "organization": { "identifier": { "system": "https://gematik.de/fhir/sid/telematik-id", "type": { "coding": [ { "system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "PRN", "version": "2.9.0", "display": "Provider number" } ] }, "value": "9-2.58.00000040" }, "reference": "Organization/be51e0d2-783d-4e21-b16b-1a4cd7403515" }, "practitioner": { "reference": "Practitioner/498c345f-31f5-4da6-9f04-00fa2bc8af7c", "identifier": { "type": { "coding": [ { "version": "2.9.0", "code": "PRN", "system": "http://terminology.hl7.org/CodeSystem/v2-0203", "display": "Provider number" } ] }, "system": "https://gematik.de/fhir/sid/telematik-id", "value": "1-1.58.00000040" } }, "code": [ { "coding": [ { "code": "API", "system": "https://gematik.de/fhir/terminology/CodeSystem/epa-role-care-cs", "display": "Ärztliche(r) PraxisinhaberIn", "version": "1.0.0" } ], "text": "Ärztlicher Praxisinhaber" } ], "specialty": [ { "coding": [ { "code": "01", "system": "https://fhir.kbv.de/CodeSystem/KBV_CS_SFHIR_BAR2_ARZTNRFACHGRUPPE", "display": "Allgemeinmedizin", "version": "1.03" } ], "text": "Allgemeinmedizin" } ], "telecom": [ { "system": "phone", "value": "0300000000000000" } ] } } ] } ] }
<Parameters xmlns="http://hl7.org/fhir"> <id value="example-epa-op-provide-medication-input-parameters-1" /> <meta> <profile value="https://gematik.de/fhir/epa-medication/StructureDefinition/epa-op-provide-medication-input-parameters" /> </meta> <parameter> <name value="medication" /> <resource> <Medication> <id value="dc810e53-c26b-47bc-8c78-c7f79ea5f7ae" /> <meta> <profile value="https://gematik.de/fhir/epa-medication/StructureDefinition/epa-medication" /> </meta> <extension url="https://gematik.de/fhir/epa-medication/StructureDefinition/epa-medication-type-extension"> <valueCoding> <system value="http://snomed.info/sct" /> <code value="781405001" /> <display value="Medicinal product package (product)" /> </valueCoding> </extension> <code> <coding> <system value="http://fhir.de/CodeSystem/ask" /> <code value="5682" /> <display value="Ibuprofen" /> </coding> </code> <status value="inactive" /> </Medication> </resource> </parameter> <parameter> <name value="performer" /> <part> <name value="organization" /> <resource> <Organization> <id value="be51e0d2-783d-4e21-b16b-1a4cd7403515" /> <meta> <profile value="https://gematik.de/fhir/directory/StructureDefinition/OrganizationDirectory" /> <tag> <system value="https://gematik.de/fhir/directory/CodeSystem/Origin" /> <code value="ldap" /> </tag> </meta> <identifier> <system value="https://gematik.de/fhir/sid/telematik-id" /> <value value="9-2.58.00000040" /> </identifier> <active value="true" /> <type> <coding> <system value="https://gematik.de/fhir/directory/CodeSystem/OrganizationProfessionOID" /> <code value="1.2.276.0.76.4.58" /> <display value="Betriebsstätte gematik" /> </coding> </type> <name value="gematik GmbH" /> <alias value="gematik" /> <address> <text value="gematik GmbH\nFriedrichstr. 136, \n10117 Berlin" /> <line value="Friedrichstr. 136" /> <city value="Berlin" /> <district value="Mitte" /> <state value="Berlin" /> <postalCode value="10117" /> <country value="DE" /> </address> <contact> <purpose> <coding> <system value="http://terminology.hl7.org/CodeSystem/contactentity-type" /> <code value="ADMIN" /> </coding> </purpose> <name> <text value="gematik ITSM" /> </name> <telecom> <system value="email" /> <value value="betrieb@gematik.de" /> </telecom> </contact> </Organization> </resource> </part> <part> <name value="practitioner" /> <resource> <Practitioner> <id value="498c345f-31f5-4da6-9f04-00fa2bc8af7c" /> <meta> <profile value="https://gematik.de/fhir/directory/StructureDefinition/PractitionerDirectory" /> <tag> <system value="https://gematik.de/fhir/directory/CodeSystem/Origin" /> <code value="ldap" /> </tag> </meta> <identifier> <system value="https://gematik.de/fhir/sid/telematik-id" /> <value value="1-1.58.00000040" /> </identifier> <identifier> <system value="https://fhir.kbv.de/NamingSystem/KBV_NS_Base_ANR" /> <value value="123456789" /> </identifier> <active value="true" /> <name> <text value="Dr. Max Manfred Mustermann" /> <family value="Musterman" /> <given value="Max" /> <given value="Manfred" /> <prefix value="Dr." /> </name> <qualification> <code> <coding> <system value="https://gematik.de/fhir/directory/CodeSystem/PractitionerProfessionOID" /> <code value="1.2.276.0.76.4.31" /> </coding> </code> </qualification> <qualification> <code> <coding> <system value="urn:oid:1.2.276.0.76.5.514" /> <code value="010" /> <display value="FA Allgemeinmedizin" /> </coding> </code> </qualification> <qualification> <code> <coding> <system value="urn:oid:1.2.276.0.76.5.514" /> <code value="523" /> <display value="FA Innere Medizin und (SP) Gastroenterologie" /> </coding> </code> </qualification> </Practitioner> </resource> </part> <part> <name value="practitionerRole" /> <resource> <PractitionerRole> <id value="ExampleEPAPractitionerRoleMax" /> <meta> <versionId value="1" /> <lastUpdated value="2023-02-03T11:20:00+01:00" /> <profile value="https://gematik.de/fhir/epa/StructureDefinition/epa-practitioner-role" /> </meta> <practitioner> <reference value="Practitioner/498c345f-31f5-4da6-9f04-00fa2bc8af7c" /> <identifier> <type> <coding> <system value="http://terminology.hl7.org/CodeSystem/v2-0203" /> <version value="2.9.0" /> <code value="PRN" /> <display value="Provider number" /> </coding> </type> <system value="https://gematik.de/fhir/sid/telematik-id" /> <value value="1-1.58.00000040" /> </identifier> </practitioner> <organization> <reference value="Organization/be51e0d2-783d-4e21-b16b-1a4cd7403515" /> <identifier> <type> <coding> <system value="http://terminology.hl7.org/CodeSystem/v2-0203" /> <version value="2.9.0" /> <code value="PRN" /> <display value="Provider number" /> </coding> </type> <system value="https://gematik.de/fhir/sid/telematik-id" /> <value value="9-2.58.00000040" /> </identifier> </organization> <code> <coding> <system value="https://gematik.de/fhir/terminology/CodeSystem/epa-role-care-cs" /> <version value="1.0.0" /> <code value="API" /> <display value="Ärztliche(r) PraxisinhaberIn" /> </coding> <text value="Ärztlicher Praxisinhaber" /> </code> <specialty> <coding> <system value="https://fhir.kbv.de/CodeSystem/KBV_CS_SFHIR_BAR2_ARZTNRFACHGRUPPE" /> <version value="1.03" /> <code value="01" /> <display value="Allgemeinmedizin" /> </coding> <text value="Allgemeinmedizin" /> </specialty> <telecom> <system value="phone" /> <value value="0300000000000000" /> </telecom> </PractitionerRole> </resource> </part> </parameter> </Parameters>
Beispielantwort
{ "resourceType": "Parameters", "id": "example-epa-op-provide-medication-output-parameters-1", "meta": { "profile": [ "https://gematik.de/fhir/epa-medication/StructureDefinition/epa-op-provide-medication-output-parameters" ] }, "parameter": [ { "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" } ] } } ] } }, { "name": "medication", "resource": { "resourceType": "Medication", "id": "2571d29b-e213-40ec-b817-a1490718a490", "meta": { "versionId": "1", "lastUpdated": "2025-01-22T14:43:33.244Z", "profile": [ "https://gematik.de/fhir/epa-medication/StructureDefinition/epa-medication" ] }, "extension": [ { "url": "https://gematik.de/fhir/epa-medication/StructureDefinition/epa-medication-type-extension", "valueCoding": { "code": "781405001", "system": "http://snomed.info/sct", "version": "http://snomed.info/sct/11000274103/version/20240515", "display": "Medicinal product package (product)" } }, { "valueIdentifier": { "system": "https://gematik.de/fhir/epa-medication/sid/rx-prescription-process-identifier", "value": "160.153.303.257.459_20250122" }, "url": "https://gematik.de/fhir/epa-medication/StructureDefinition/rx-prescription-process-identifier-extension" } ], "identifier": [ { "system": "https://gematik.de/fhir/epa-medication/sid/epa-medication-unique-identifier", "value": "A632B2AB4232C9787E0731E3824942350070FB492EB1005A4AFA00F4BACD8AA1" }, { "system": "https://gematik.de/fhir/epa-medication/sid/rx-originator-process-identifier", "value": "dc810e53-c26b-47bc-8c78-c7f79ea5f7ae_160.153.303.257.459" } ], "status": "active", "code": { "coding": [ { "system": "http://fhir.de/CodeSystem/ask", "code": "5682", "display": "Ibuprofen" } ] } } } ] }
<Parameters xmlns="http://hl7.org/fhir"> <id value="example-epa-op-provide-medication-output-parameters-1" /> <meta> <profile value="https://gematik.de/fhir/epa-medication/StructureDefinition/epa-op-provide-medication-output-parameters" /> </meta> <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> <parameter> <name value="medication" /> <resource> <Medication> <id value="2571d29b-e213-40ec-b817-a1490718a490" /> <meta> <versionId value="1" /> <lastUpdated value="2025-01-22T14:43:33.244Z" /> <profile value="https://gematik.de/fhir/epa-medication/StructureDefinition/epa-medication" /> </meta> <extension url="https://gematik.de/fhir/epa-medication/StructureDefinition/epa-medication-type-extension"> <valueCoding> <system value="http://snomed.info/sct" /> <version value="http://snomed.info/sct/11000274103/version/20240515" /> <code value="781405001" /> <display value="Medicinal product package (product)" /> </valueCoding> </extension> <extension url="https://gematik.de/fhir/epa-medication/StructureDefinition/rx-prescription-process-identifier-extension"> <valueIdentifier> <system value="https://gematik.de/fhir/epa-medication/sid/rx-prescription-process-identifier" /> <value value="160.153.303.257.459_20250122" /> </valueIdentifier> </extension> <identifier> <system value="https://gematik.de/fhir/epa-medication/sid/epa-medication-unique-identifier" /> <value value="A632B2AB4232C9787E0731E3824942350070FB492EB1005A4AFA00F4BACD8AA1" /> </identifier> <identifier> <system value="https://gematik.de/fhir/epa-medication/sid/rx-originator-process-identifier" /> <value value="dc810e53-c26b-47bc-8c78-c7f79ea5f7ae_160.153.303.257.459" /> </identifier> <code> <coding> <system value="http://fhir.de/CodeSystem/ask" /> <code value="5682" /> <display value="Ibuprofen" /> </coding> </code> <status value="active" /> </Medication> </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 | Resource is not known | EPA OperationOutcome | |
| 404 | Unknown resource type | 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"
}