Operation API: Dispensierung stornieren (Clientsysteme)
Die Operation $cancel-dispensation ermöglicht das Stornieren oder Rückgängigmachen einer Abgabe von medizinischen Produkten im Medication Service. Diese Operation wird von Clientsystemen ausgeführt, wenn das Einstellen von Dispensierinformationen versehentlich oder inhaltlich falsch erfolgt ist oder wenn eine Aktualisierung in der Arzneimittelhistorie des Versicherten notwendig wird. Nachdem das Clientsystem die Operation durchführt, wird die betreffende Abgabe im Medication Service des Versicherten als storniert bzw. rückgängig gemacht markiert, was zu einer genauen und aktuellen Erfassung der Arzneimitteldaten des Versicherten beiträgt.
OperationDefinition
Operation Definition: Cancel Dispensation
Geschäftslogik (Medication Service)
Ü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
Command 'page' could not render: Page not found.
Interaktion ($cancel-dispensation)
POST [base]/epa/medication/api/v1/fhir/$cancel-dispensation
OperationId: cancelDispensationPS_MedicationSvc
Beispielanfrage
{ "resourceType": "Parameters", "id": "example-epa-op-cancel-dispensation-input-parameters", "meta": { "profile": [ "https://gematik.de/fhir/epa-medication/StructureDefinition/epa-op-cancel-dispensation-input-parameters" ] }, "parameter": [ { "name": "dispensation", "part": [ { "name": "epaDispensationIdentifier", "valueIdentifier": { "system": "https://gematik.de/fhir/epa-medication/sid/dispensation-identifier", "value": "0190a6d9-8ef1-7c58-b7b8-de09aee1efd7" } }, { "name": "reason", "valueCode": "frr01" } ] }, { "name": "performerInstitution", "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" } ] } ] } } ] }
<Parameters xmlns="http://hl7.org/fhir"> <id value="example-epa-op-cancel-dispensation-input-parameters" /> <meta> <profile value="https://gematik.de/fhir/epa-medication/StructureDefinition/epa-op-cancel-dispensation-input-parameters" /> </meta> <parameter> <name value="dispensation" /> <part> <name value="epaDispensationIdentifier" /> <valueIdentifier> <system value="https://gematik.de/fhir/epa-medication/sid/dispensation-identifier" /> <value value="0190a6d9-8ef1-7c58-b7b8-de09aee1efd7" /> </valueIdentifier> </part> <part> <name value="reason" /> <valueCode value="frr01" /> </part> </parameter> <parameter> <name value="performerInstitution" /> <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> </parameter> </Parameters>
Beispielantwort
{ "resourceType": "Parameters", "id": "example-epa-op-cancel-dispensation-output-parameters", "meta": { "profile": [ "https://gematik.de/fhir/epa-medication/StructureDefinition/epa-op-dispensation-output-parameters" ] }, "parameter": [ { "name": "dispensation", "part": [ { "name": "medicationDispense", "resource": { "resourceType": "MedicationDispense", "id": "ExampleEpaMedicationDispenseDicloOTCOutputCancelled", "meta": { "profile": [ "https://gematik.de/fhir/epa-medication/StructureDefinition/epa-medication-dispense" ] }, "identifier": [ { "system": "https://gematik.de/fhir/epa-medication/sid/dispensation-identifier", "value": "0190a6d9-8ef1-7c58-b7b8-de09aee1efd7" } ], "status": "cancelled", "category": { "coding": [ { "code": "non-prescription", "system": "https://gematik.de/fhir/terminology/CodeSystem/EPAMedicationDispenseCategoryCS", "display": "non-prescription dispense" } ] }, "medicationReference": { "reference": "Medication/ExampleEpaMedicationDicloOTCOutputCancelled" }, "subject": { "identifier": { "type": { "coding": [ { "code": "KVZ10", "system": "http://fhir.de/CodeSystem/identifier-type-de-basis", "display": "Krankenversichertennummer" } ] }, "value": "X110411319", "system": "http://fhir.de/sid/gkv/kvid-10" } }, "whenHandedOver": "2025-01-22", "performer": [ { "actor": { "reference": "Organization/be51e0d2-783d-4e21-b16b-1a4cd7403515" } } ], "substitution": { "wasSubstituted": false }, "statusReasonCodeableConcept": { "coding": [ { "code": "frr01", "system": "https://hl7.org/fhir/R4/codesystem-medicationdispense-status-reason.html" } ] } } }, { "name": "medication", "resource": { "resourceType": "Medication", "id": "ExampleEpaMedicationDicloOTCOutputCancelled", "meta": { "versionId": "2", "lastUpdated": "2025-02-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/dispensation-identifier", "value": "0190a6d9-8ef1-7c58-b7b8-de09aee1efd7" }, "url": "https://gematik.de/fhir/epa-medication/StructureDefinition/dispensation-identifier-extension" }, { "url": "http://fhir.de/StructureDefinition/normgroesse", "valueCode": "N1" } ], "code": { "coding": [ { "system": "http://fhir.de/CodeSystem/ifa/pzn", "code": "14170042", "display": "Diclo-ratiopharm® bei Schmerzen und Fieber 25 mg Filmtabletten" } ] }, "form": { "coding": [ { "system": "https://fhir.kbv.de/CodeSystem/KBV_CS_SFHIR_KBV_DARREICHUNGSFORM", "code": "TAB" } ] }, "amount": { "numerator": { "extension": [ { "url": "https://gematik.de/fhir/epa-medication/StructureDefinition/medication-total-quantity-formulation-extension", "valueString": "20 St." } ], "value": 20, "unit": "St" }, "denominator": { "value": 1 } }, "identifier": [ { "system": "https://gematik.de/fhir/epa-medication/sid/epa-medication-unique-identifier", "value": "B849184C973EA5FA7D9751E6FAA6AFCFFD100183596239F84DD2C0FG4C751D67" } ], "status": "inactive" } }, { "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-cancel-dispensation-output-parameters" /> <meta> <profile value="https://gematik.de/fhir/epa-medication/StructureDefinition/epa-op-dispensation-output-parameters" /> </meta> <parameter> <name value="dispensation" /> <part> <name value="medicationDispense" /> <resource> <MedicationDispense> <id value="ExampleEpaMedicationDispenseDicloOTCOutputCancelled" /> <meta> <profile value="https://gematik.de/fhir/epa-medication/StructureDefinition/epa-medication-dispense" /> </meta> <identifier> <system value="https://gematik.de/fhir/epa-medication/sid/dispensation-identifier" /> <value value="0190a6d9-8ef1-7c58-b7b8-de09aee1efd7" /> </identifier> <status value="cancelled" /> <statusReasonCodeableConcept> <coding> <system value="https://hl7.org/fhir/R4/codesystem-medicationdispense-status-reason.html" /> <code value="frr01" /> </coding> </statusReasonCodeableConcept> <category> <coding> <system value="https://gematik.de/fhir/terminology/CodeSystem/EPAMedicationDispenseCategoryCS" /> <code value="non-prescription" /> <display value="non-prescription dispense" /> </coding> </category> <medicationReference> <reference value="Medication/ExampleEpaMedicationDicloOTCOutputCancelled" /> </medicationReference> <subject> <identifier> <type> <coding> <system value="http://fhir.de/CodeSystem/identifier-type-de-basis" /> <code value="KVZ10" /> <display value="Krankenversichertennummer" /> </coding> </type> <system value="http://fhir.de/sid/gkv/kvid-10" /> <value value="X110411319" /> </identifier> </subject> <performer> <actor> <reference value="Organization/be51e0d2-783d-4e21-b16b-1a4cd7403515" /> </actor> </performer> <whenHandedOver value="2025-01-22" /> <substitution> <wasSubstituted value="false" /> </substitution> </MedicationDispense> </resource> </part> <part> <name value="medication" /> <resource> <Medication> <id value="ExampleEpaMedicationDicloOTCOutputCancelled" /> <meta> <versionId value="2" /> <lastUpdated value="2025-02-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/dispensation-identifier-extension"> <valueIdentifier> <system value="https://gematik.de/fhir/epa-medication/sid/dispensation-identifier" /> <value value="0190a6d9-8ef1-7c58-b7b8-de09aee1efd7" /> </valueIdentifier> </extension> <extension url="http://fhir.de/StructureDefinition/normgroesse"> <valueCode value="N1" /> </extension> <identifier> <system value="https://gematik.de/fhir/epa-medication/sid/epa-medication-unique-identifier" /> <value value="B849184C973EA5FA7D9751E6FAA6AFCFFD100183596239F84DD2C0FG4C751D67" /> </identifier> <code> <coding> <system value="http://fhir.de/CodeSystem/ifa/pzn" /> <code value="14170042" /> <display value="Diclo-ratiopharm® bei Schmerzen und Fieber 25 mg Filmtabletten" /> </coding> </code> <status value="inactive" /> <form> <coding> <system value="https://fhir.kbv.de/CodeSystem/KBV_CS_SFHIR_KBV_DARREICHUNGSFORM" /> <code value="TAB" /> </coding> </form> <amount> <numerator> <extension url="https://gematik.de/fhir/epa-medication/StructureDefinition/medication-total-quantity-formulation-extension"> <valueString value="20 St." /> </extension> <value value="20" /> <unit value="St" /> </numerator> <denominator> <value value="1" /> </denominator> </amount> </Medication> </resource> </part> <part> <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> </part> </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"
}