Query API: AllergyIntolerance (Allergie und Intoleranz)

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 (Query AllergyIntolerance)

GET [base]/epa/medication/api/v1/fhir/AllergyIntolerance

OperationId: listAllergyIntolerances_MedicationSvc

Anfragen an die AllergyIntolerance-Ressource können über die RESTful API mittels HTTP GET-Anfragen durchgeführt werden. Dabei können spezifische Suchparameter genutzt werden, um die Anfragen zu verfeinern. Zum Beispiel:

Durch die Verwendung von ?code=[code] kann nach Allergien und Intoleranzen gesucht werden, die einem bestimmten Code entsprechen.
Die Verwendung von ?date=2025-01-15 kann genutzt werden, um nach Allergien und Intoleranzen zu suchen, die zu einem bestimmten Datum erfasst wurden.
Die Verwendung von ?status=active kann genutzt werden, um nach Allergien und Intoleranzen zu suchen, die zuletzt als aktiv verifiziert wurden.

Bei Anfragen an die QueryAPI für die AllergyIntolerance-Ressource wird die Antwort als ein FHIR Bundle des Typs searchset zurückgegeben. Dieses Bundle enthält eine Sammlung von Einträgen, die jeweils eine Instanz der AllergyIntolerance-Ressource oder weitere Ressourcen im Zusammenhang mit der Abfrage enthalten können.

Suchparameter

Parameter	Type	Definition	Beschreibung	Anforderung
_id	token	http://hl7.org/fhir/SearchParameter/Resource-id	Resource.id	MUSS
_lastUpdated	date	http://hl7.org/fhir/SearchParameter/Resource-lastUpdated	Resource.meta.lastUpdated	MUSS
identifier	token	http://hl7.org/fhir/SearchParameter/clinical-identifier	AllergyIntolerance.identifier	MUSS
code	token	http://hl7.org/fhir/SearchParameter/clinical-code	AllergyIntolerance.code \| AllergyIntolerance.reaction.substance	MUSS
clinical-status	token	http://hl7.org/fhir/SearchParameter/AllergyIntolerance-clinical-status	AllergyIntolerance.clinicalStatus	MUSS
date	date	http://hl7.org/fhir/SearchParameter/clinical-date	AllergyIntolerance.recordedDate	MUSS

Suche per Include oder RevInclude

Include
AllergyIntolerance.recorder

RevInclude
Provenance.target

{
    "resourceType": "Bundle",
    "id": "example-searchset-allergy-intolerance",
    "type": "searchset",
    "total": 100,
    "link":  [
        {
            "relation": "self",
            "url": "/epa/medication/api/v1/fhir/AllergyIntolerance?_offset=20&_count=10"
        },
        {
            "relation": "previous",
            "url": "/epa/medication/api/v1/fhir/AllergyIntolerance?_offset=10&_count=10"
        },
        {
            "relation": "next",
            "url": "/epa/medication/api/v1/fhir/AllergyIntolerance?_offset=30&_count=10"
        }
    ],
    "entry":  [
        {
            "fullUrl": "https://epa-as-0.prod.epa4all.de/vau-cid-1234/epa/medication/api/v1/fhir/AllergyIntolerance/4830eb83-be0a-4cce-921e-d73a5e5ddec3",
            "resource": {
                "resourceType": "AllergyIntolerance",
                "id": "4830eb83-be0a-4cce-921e-d73a5e5ddec3",
                "meta": {
                    "profile":  [
                        "https://gematik.de/fhir/epa/StructureDefinition/epa-allergy-intolerance"
                    ]
                },
                "code": {
                    "coding":  [
                        {
                            "system": "http://snomed.info/sct",
                            "code": "227493005",
                            "version": "http://snomed.info/sct/11000274103/version/20240515",
                            "display": "Allergy to penicillin"
                        }
                    ]
                },
                "reaction":  [
                    {
                        "manifestation":  [
                            {
                                "coding":  [
                                    {
                                        "system": "http://snomed.info/sct",
                                        "code": "43116000",
                                        "version": "http://snomed.info/sct/11000274103/version/20240515",
                                        "display": "Ekzem"
                                    }
                                ]
                            }
                        ],
                        "exposureRoute": {
                            "coding":  [
                                {
                                    "system": "http://snomed.info/sct",
                                    "code": "26643006",
                                    "version": "http://snomed.info/sct/11000274103/version/20240515",
                                    "display": "Peroral"
                                }
                            ]
                        },
                        "severity": "severe"
                    }
                ],
                "clinicalStatus": {
                    "coding":  [
                        {
                            "code": "active",
                            "system": "http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical",
                            "version": "4.0.1",
                            "display": "Active"
                        }
                    ]
                },
                "verificationStatus": {
                    "coding":  [
                        {
                            "code": "confirmed",
                            "system": "http://terminology.hl7.org/CodeSystem/allergyintolerance-verification",
                            "version": "4.0.1",
                            "display": "Confirmed"
                        }
                    ]
                },
                "type": "allergy",
                "category":  [
                    "medication"
                ],
                "criticality": "high",
                "patient": {
                    "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"
                    }
                },
                "onsetDateTime": "2025-08-01",
                "recordedDate": "2025-08-15",
                "recorder": {
                    "reference": "PractitionerRole/3b4e3403-a4c7-40ee-8792-6a855105d126"
                },
                "asserter": {
                    "reference": "PractitionerRole/3856402c-7636-4fbd-98bd-d278852b8e88"
                },
                "lastOccurrence": "2025-08-11",
                "note":  [
                    {
                        "text": "Patient reported a severe rash after taking penicillin."
                    }
                ]
            },
            "search": {
                "mode": "match"
            }
        }
    ]
}

<Bundle xmlns="http://hl7.org/fhir">
    <id value="example-searchset-allergy-intolerance" />
    <type value="searchset" />
    <total value="100" />
    <link>
        <relation value="self" />
        <url value="/epa/medication/api/v1/fhir/AllergyIntolerance?_offset=20&amp;_count=10" />
    </link>
    <link>
        <relation value="previous" />
        <url value="/epa/medication/api/v1/fhir/AllergyIntolerance?_offset=10&amp;_count=10" />
    </link>
    <link>
        <relation value="next" />
        <url value="/epa/medication/api/v1/fhir/AllergyIntolerance?_offset=30&amp;_count=10" />
    </link>
    <entry>
        <fullUrl value="https://epa-as-0.prod.epa4all.de/vau-cid-1234/epa/medication/api/v1/fhir/AllergyIntolerance/4830eb83-be0a-4cce-921e-d73a5e5ddec3" />
        <resource>
            <AllergyIntolerance>
                <id value="4830eb83-be0a-4cce-921e-d73a5e5ddec3" />
                <meta>
                    <profile value="https://gematik.de/fhir/epa/StructureDefinition/epa-allergy-intolerance" />
                </meta>
                <clinicalStatus>
                    <coding>
                        <system value="http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical" />
                        <version value="4.0.1" />
                        <code value="active" />
                        <display value="Active" />
                    </coding>
                </clinicalStatus>
                <verificationStatus>
                    <coding>
                        <system value="http://terminology.hl7.org/CodeSystem/allergyintolerance-verification" />
                        <version value="4.0.1" />
                        <code value="confirmed" />
                        <display value="Confirmed" />
                    </coding>
                </verificationStatus>
                <type value="allergy" />
                <category value="medication" />
                <criticality value="high" />
                <code>
                    <coding>
                        <system value="http://snomed.info/sct" />
                        <version value="http://snomed.info/sct/11000274103/version/20240515" />
                        <code value="227493005" />
                        <display value="Allergy to penicillin" />
                    </coding>
                </code>
                <patient>
                    <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>
                </patient>
                <onsetDateTime value="2025-08-01" />
                <recordedDate value="2025-08-15" />
                <recorder>
                    <reference value="PractitionerRole/3b4e3403-a4c7-40ee-8792-6a855105d126" />
                </recorder>
                <asserter>
                    <reference value="PractitionerRole/3856402c-7636-4fbd-98bd-d278852b8e88" />
                </asserter>
                <lastOccurrence value="2025-08-11" />
                <note>
                    <text value="Patient reported a severe rash after taking penicillin." />
                </note>
                <reaction>
                    <manifestation>
                        <coding>
                            <system value="http://snomed.info/sct" />
                            <version value="http://snomed.info/sct/11000274103/version/20240515" />
                            <code value="43116000" />
                            <display value="Ekzem" />
                        </coding>
                    </manifestation>
                    <severity value="severe" />
                    <exposureRoute>
                        <coding>
                            <system value="http://snomed.info/sct" />
                            <version value="http://snomed.info/sct/11000274103/version/20240515" />
                            <code value="26643006" />
                            <display value="Peroral" />
                        </coding>
                    </exposureRoute>
                </reaction>
            </AllergyIntolerance>
        </resource>
        <search>
            <mode value="match" />
        </search>
    </entry>
</Bundle>

Antwort-Status-Codes

Status Code	Bedingung	Error Code	Bemerkung
200	Successful operation
400	Unknown search parameter		EPA OperationOutcome
400	Invalid query parameter(s)		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	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"
}

Interaktion (AllergyIntolerance Instance API)

GET [base]/epa/medication/api/v1/fhir/AllergyIntolerance/[id]

OperationId: getAllergyIntoleranceById_MedicationSvc

Um spezifische Details zu einer einzelnen AllergyIntolerance mittels der RESTful API zu erhalten, kann die AllergyIntolerance Instance API verwendet werden, sodass eine HTTP GET-Anfrage an den Endpunkt /AllergyIntolerance/[id] gerichtet wird.

Antwort-Status-Codes

Status Code	Bedingung	Error Code	Bemerkung
200	Successful operation
400	Unknown search parameter		EPA OperationOutcome
400	Invalid query parameter(s)		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')

{
  "errorCode": "statusMismatch"
}