Generelle Prinzipien

Dieser Implementation Guide verwendet die Schlüsselwörter MUSS, DARF NICHT, SOLL NICHT und KANN als deutsche Pendants des [RFC2119], um Anforderungen als Ausdruck normativer Festlegungen zu kennzeichnen. Anforderungen werden im Implementation Guide wie folgt dargestellt:

<IG-ID-Version> - <Titel der Anforderung>
Text / Beschreibung
[<=]

Übergeordnete Anforderungen

Der Audit Event Service berücksichtigt als Ausprägung eines FHIR Data Service allgemeingültige [gemIG_TI_Common#Audit] Anforderungen.

Der Patient Service berücksichtigt als Ausprägung eines FHIR Data Service allgemeingültige [gemIG_TI_Common#Patient] Anforderungen.

Schnittstellenimplementierung

    {
      "errorCode": "statusMismatch"
    }

Beispiel für ein OperationOutcome mit SVC_IDENTITY_MISMATCH

{
  "resourceType" : "OperationOutcome",
  "id" : "ad48bf90-a664-44f4-af14-ee6e81db3df4",
  "meta" : {
    "profile" : [
      🔗 "https://gematik.de/fhir/ti/StructureDefinition/operation-outcome|1.1.1"
    ]
  },
  "issue" : [
    {
      "severity" : "error",
      "code" : "forbidden",
      "details" : {
        "coding" : [
          {
            "system" : "https://gematik.de/fhir/ti/CodeSystem/operation-outcome-details-codes",
            "code" : "SVC_IDENTITY_MISMATCH",
            "display" : "Telematik-ID inside ID-Token or KVNR in x-insurantid HTTP header does not match FHIR data"
          }
        ]
      }
    }
  ]
}

<OperationOutcome xmlns="http://hl7.org/fhir">
  <id value="ad48bf90-a664-44f4-af14-ee6e81db3df4"/>
  <meta>
    <profile
             value="https://gematik.de/fhir/ti/StructureDefinition/operation-outcome|1.1.1"/>
  </meta>
  <issue>
    <severity value="error"/>
    <code value="forbidden"/>
    <details>
      <coding>
        <system
                value="https://gematik.de/fhir/ti/CodeSystem/operation-outcome-details-codes"/>
        <code value="SVC_IDENTITY_MISMATCH"/>
        <display
                 value="Telematik-ID inside ID-Token or KVNR in x-insurantid HTTP header does not match FHIR data"/>
      </coding>
    </details>
  </issue>
</OperationOutcome>

{
  "resourceType" : "OperationOutcome",
  "id" : "72c7abbf-51c5-4647-846e-7c5af57e2105",
  "meta" : {
    "profile" : [
      🔗 "https://gematik.de/fhir/ti/StructureDefinition/operation-outcome|1.1.1"
    ]
  },
  "issue" : [
    {
      "severity" : "error",
      "code" : "structure"
    }
  ]
}

<OperationOutcome xmlns="http://hl7.org/fhir">
  <id value="72c7abbf-51c5-4647-846e-7c5af57e2105"/>
  <meta>
    <profile
             value="https://gematik.de/fhir/ti/StructureDefinition/operation-outcome|1.1.1"/>
  </meta>
  <issue>
    <severity value="error"/>
    <code value="structure"/>
  </issue>
</OperationOutcome>

Wiederholungsintervalle

Die folgenden Wiederholungsintervalle werden im Falle einer Fehlerantwort definiert:

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

Leistungserbringerinstitutionserkennung mittels X-Requesting-Organization

Zur Identifikation der Leistungserbringerinstitution, desssen Primärsystem eine FHIR-Operation auslöst, wird der HTTP Header X-Requesting-Organization verwendet. Dieser Header überträgt eine FHIR Organization-Ressource im JSON-Format, base64-kodiert gemäß [RFC4648].

Die übermittelte Organization muss dem Profil TIOrganization entsprechen und enthält unter anderem die Telematik-ID der Leistungserbringerinstitution. Diese wird vom FHIR Data Service mit der im ID-Token enthaltenen Telematik-ID verglichen, um die Identität der Leistungserbringerinstitution zu verifizieren. Dabei ist zu beachten, dass der HTTP Header X-Requesting-Organization eine maximale Größe von 8 KByte nicht überschreiten darf.

Neben der Validierung dient die übermittelte Leistungserbringerinstitution bzw. der Organization-Datensatz auch der automatischen Referenzierung in Provenance-Ressourcen, die bei Änderungsoperationen erzeugt werden. So kann jede Änderung systematisch der verantwortlichen Leistungserbringerinstitution zugeordnet werden.

{
  "resourceType" : "OperationOutcome",
  "id" : "3e5635b7-5546-4b2b-8509-a138652985e7",
  "meta" : {
    "profile" : [
      🔗 "https://gematik.de/fhir/ti/StructureDefinition/operation-outcome|1.1.1"
    ]
  },
  "issue" : [
    {
      "severity" : "error",
      "code" : "structure",
      "details" : {
        "coding" : [
          {
            "system" : "https://gematik.de/fhir/epa/CodeSystem/epa-operation-outcome-details-codes",
            "code" : "SVC_ORG_HEADER_PROFILE_MISMATCH",
            "display" : "Profile mismatch in header Organization"
          }
        ]
      }
    }
  ]
}

<OperationOutcome xmlns="http://hl7.org/fhir">
  <id value="3e5635b7-5546-4b2b-8509-a138652985e7"/>
  <meta>
    <profile
             value="https://gematik.de/fhir/ti/StructureDefinition/operation-outcome|1.1.1"/>
  </meta>
  <issue>
    <severity value="error"/>
    <code value="structure"/>
    <details>
      <coding>
        <system
                value="https://gematik.de/fhir/epa/CodeSystem/epa-operation-outcome-details-codes"/>
        <code value="SVC_ORG_HEADER_PROFILE_MISMATCH"/>
        <display value="Profile mismatch in header Organization"/>
      </coding>
    </details>
  </issue>
</OperationOutcome>

Beispiel HTTP Request mit X-Requesting-Organization Header

POST /epa/medication/api/v1/fhir/$add-emp-entry HTTP/1.1
Host: epa4all
Content-Type: application/fhir+json
X-Request-ID: bb22b14f-9c95-49fe-b889-d03e2d692bca
x-insurantid: Z123456789
x-useragent: CLIENTID1234567890AB/2.1.12-45
X-Requesting-Organization: eyJyZXNvdXJjZVR5cGUiOiJPcmdhbml6YXRpb24iLCJpZCI6IkV4YW1wbGVNaW5pbWFsT3JnYW5pemF0aW9uSGVhZGVyIiwibWV0YSI6eyJwcm9maWxlIjpbImh0dHBzOi8vZ2VtYXRpay5kZS9maGlyL3RpL1N0cnVjdHVyZURlZmluaXRpb24vdGktb3JnYW5pemF0aW9uIl19LCJpZGVudGlmaWVyIjpbeyJzeXN0ZW0iOiJodHRwczovL2dlbWF0aWsuZGUvZmhpci9zaWQvdGVsZW1hdGlrLWlkIiwidmFsdWUiOiI5LTIuNTguMDAwMDAwODkifSx7InN5c3RlbSI6Imh0dHBzOi8vZmhpci5rYnYuZGUvTmFtaW5nU3lzdGVtL0tCVl9OU19CYXNlX0JTTlIiLCJ2YWx1ZSI6IjcyMTExMTEwMCJ9XSwidHlwZSI6W3siY29kaW5nIjpbeyJjb2RlIjoiMS4yLjI3Ni4wLjc2LjQuNTAiLCJzeXN0ZW0iOiJodHRwczovL2dlbWF0aWsuZGUvZmhpci9kaXJlY3RvcnkvQ29kZVN5c3RlbS9Pcmdhbml6YXRpb25Qcm9mZXNzaW9uT0lEIiwiZGlzcGxheSI6IkJldHJpZWJzc3TDpHR0ZSBBcnp0In1dfV0sImFkZHJlc3MiOlt7ImxpbmUiOlsiRnJpZWRyaWNoc3RyLiAxMzYiXSwidGV4dCI6IkZyaWVkcmljaHN0ci4gMTM2LCBcbjEwMTE3IEJlcmxpbiIsImNpdHkiOiJCZXJsaW4iLCJkaXN0cmljdCI6Ik1pdHRlIiwic3RhdGUiOiJCZXJsaW4iLCJwb3N0YWxDb2RlIjoiMTAxMTciLCJjb3VudHJ5IjoiREUifV0sImNvbnRhY3QiOlt7InRlbGVjb20iOlt7InN5c3RlbSI6InBob25lIiwidmFsdWUiOiIwMzAxMjM0NTY3In0seyJzeXN0ZW0iOiJmYXgiLCJ2YWx1ZSI6IjAzMDEyMzQ1Njc4OSJ9LHsic3lzdGVtIjoiZW1haWwiLCJ2YWx1ZSI6ImhhdXNhcnp0cHJheGlzQGV4YW1wbGUuY29tIn1dfV0sIm5hbWUiOiJEaWUgSGF1c2FyenRwcmF4aXMifQ==

Erstellen und Verwenden eines Änderungseintrags (Provenance)

Änderungseinträge im FHIR Data Service des ePA-Aktenkontos werden mit der Ressource Provenance dokumentiert. Sie erfassen, welche Änderungen an Ressourcen durchgeführt wurden, welche Versionen dieser Ressourcen dadurch entstanden sind, sowie wer für diese Änderung verantwortlich war und wann diese fachlich durchgeführt und technisch dokumentiert wurde.

Für diese Änderungseinträge muss das Profil EPAActivityProvenance verwendet werden. Dieses Profil legt verbindlich fest,

• welche Angaben zu den betroffenen Ressourcen (target) zu machen sind,
• wie der verantwortliche Akteur (agent) als Leistungserbringer:in, Institution oder System referenziert wird,
• und wie die Art der Aktivität (activity) sowie die zeitlichen Angaben (occurred, recorded) anzugeben sind.

Ein Änderungseintrag dient dabei nicht nur als technisches Audit, sondern als fachlich relevanter Nachweis im Kontext des jeweiligen FHIR Data Service. Jede betroffene Ressourceninstanz wird versioniert referenziert, sodass der genaue Zustand der jeweiligen FHIR-Instanzen zum Zeitpunkt der Änderung eindeutig nachvollzogen werden kann.

Die Provenance-Instanzen werden ausschließlich vom jeweiligen FHIR Data Service selbst erstellt. Eine Erstellung oder Bearbeitung dieser Änderungseinträge durch externe Systeme oder Clients ist nicht vorgesehen. Die Provenance entsteht typischerweise im Rahmen von Operationen, die fachliche Änderungen an Ressourceninstanzen bewirken. Es wird nicht für jede einzelne Ressourceninstanz automatisch ein Änderungseintrag erstellt. Die jeweilige Geschäftslogik des FHIR Data Service definiert, für welche fachlich relevanten Änderungen ein Änderungseintrag erzeugt wird. Beispielsweise kann eine zusammengehörige Gruppe von Instanzen, die gemeinsam einen Verschreibungs- unad Abgdabedatensatz bilden, in einem einzigen Änderungseintrag dokumentiert werden.

Ermittlung des verantwortlichen Akteurs (Agent)

Der verantwortliche Akteur wird im Änderungseintrag durch das Element Provenance.agent.who angegeben. Dabei gilt folgende Unterscheidung:

Bei Aufrufen durch Leistungserbringerinstitutionen:

Es ist die im Header X-Requesting-Organization übermittelte Organization-Ressource zu verwenden. Für die Referenzierung in agent.who gilt:

• Es ist eine Referenz auf die übermittelte Organization-Instanz zu verwenden, sofern diese im FHIR Data Service gespeichert ist.
• Zusätzlich sind der Identifier (Telematik-ID) sowie der Anzeigename (display) aus der übermittelten Organization in agent.who einzutragen.

{
  "resourceType" : "Provenance",
  "id" : "fdfc2842-bfff-436f-ab13-74785d0188c0",
  "meta" : {
    "versionId" : "1",
    "lastUpdated" : "2025-06-02T11:15:00+01:00",
    "profile" : [
      🔗 "https://gematik.de/fhir/epa/StructureDefinition/epa-activity-provenance|1.3.0"
    ]
  },
  "target" : [
    {
      "reference" : "MedicationStatement/29d46448-b585-4501-9660-a1236436560f/_history/2"
    }
  ],
  "occurredDateTime" : "2025-06-02T11:15:00+01:00",
  "recorded" : "2025-06-02T11:15:00+01:00",
  "activity" : {
    "coding" : [
      {
        "system" : "http://terminology.hl7.org/CodeSystem/v3-DataOperation",
        "code" : "Update",
        "display" : "revise"
      }
    ]
  },
  "agent" : [
    {
      "type" : {
        "coding" : [
          {
            "system" : "http://terminology.hl7.org/CodeSystem/provenance-participant-type",
            "code" : "author"
          }
        ]
      },
      "who" : {
        🔗 "reference" : "Organization/e66d6c66-96e0-4725-b48c-73702ee63cdf",
        "identifier" : {
          "system" : "https://gematik.de/fhir/sid/telematik-id",
          "value" : "9-2.58.00000040"
        },
        "display" : "gematik Praxis"
      }
    }
  ]
}

<Provenance xmlns="http://hl7.org/fhir">
  <id value="fdfc2842-bfff-436f-ab13-74785d0188c0"/>
  <meta>
    <versionId value="1"/>
    <lastUpdated value="2025-06-02T11:15:00+01:00"/>
    <profile
             value="https://gematik.de/fhir/epa/StructureDefinition/epa-activity-provenance|1.3.0"/>
  </meta>
  <target>
    <reference
               value="MedicationStatement/29d46448-b585-4501-9660-a1236436560f/_history/2"/>
  </target>
  <occurredDateTime value="2025-06-02T11:15:00+01:00"/>
  <recorded value="2025-06-02T11:15:00+01:00"/>
  <activity>
    <coding>
      <system value="http://terminology.hl7.org/CodeSystem/v3-DataOperation"/>
      <code value="Update"/>
      <display value="revise"/>
    </coding>
  </activity>
  <agent>
    <type>
      <coding>
        <system
                value="http://terminology.hl7.org/CodeSystem/provenance-participant-type"/>
        <code value="author"/>
      </coding>
    </type>
    <who>🔗 
      <reference value="Organization/e66d6c66-96e0-4725-b48c-73702ee63cdf"/>
      <identifier>
        <system value="https://gematik.de/fhir/sid/telematik-id"/>
        <value value="9-2.58.00000040"/>
      </identifier>
      <display value="gematik Praxis"/>
    </who>
  </agent>
</Provenance>

Bei Änderungen, die der FHIR Data Service selbst durchführt:

Es ist ein eindeutiger Identifier des jeweiligen ePA FHIR Data Service anzugeben, z. B. ein Identifier nach dem Profil EPAFHIRDataServiceIdentifier. Auch in diesem Fall ist zusätzlich ein display anzugeben, der den Dienstnamen beschreibt (z. B. “ePA Medication Service”).

{
  "resourceType" : "Provenance",
  "id" : "c7b6dcfc-d535-4f8f-9d86-841693f788d1",
  "meta" : {
    "versionId" : "1",
    "lastUpdated" : "2025-06-02T11:15:00+01:00",
    "profile" : [
      🔗 "https://gematik.de/fhir/epa/StructureDefinition/epa-activity-provenance|1.3.0"
    ]
  },
  "target" : [
    {
      "reference" : "MedicationStatement/29d46448-b585-4501-9660-a1236436560f/_history/1"
    }
  ],
  "occurredDateTime" : "2025-06-02T11:15:00+01:00",
  "recorded" : "2025-06-02T11:15:00+01:00",
  "activity" : {
    "coding" : [
      {
        "system" : "http://terminology.hl7.org/CodeSystem/v3-DataOperation",
        "code" : "CREATE",
        "display" : "create"
      }
    ]
  },
  "agent" : [
    {
      "type" : {
        "coding" : [
          {
            "system" : "http://terminology.hl7.org/CodeSystem/provenance-participant-type",
            "code" : "author"
          }
        ]
      },
      "who" : {
        "identifier" : {
          "system" : "https://gematik.de/fhir/sid/epa-fhir-data-service",
          "value" : "MEDICATIONSVC"
        },
        "display" : "ePA Medication Service"
      }
    }
  ]
}

<Provenance xmlns="http://hl7.org/fhir">
  <id value="c7b6dcfc-d535-4f8f-9d86-841693f788d1"/>
  <meta>
    <versionId value="1"/>
    <lastUpdated value="2025-06-02T11:15:00+01:00"/>
    <profile
             value="https://gematik.de/fhir/epa/StructureDefinition/epa-activity-provenance|1.3.0"/>
  </meta>
  <target>
    <reference
               value="MedicationStatement/29d46448-b585-4501-9660-a1236436560f/_history/1"/>
  </target>
  <occurredDateTime value="2025-06-02T11:15:00+01:00"/>
  <recorded value="2025-06-02T11:15:00+01:00"/>
  <activity>
    <coding>
      <system value="http://terminology.hl7.org/CodeSystem/v3-DataOperation"/>
      <code value="CREATE"/>
      <display value="create"/>
    </coding>
  </activity>
  <agent>
    <type>
      <coding>
        <system
                value="http://terminology.hl7.org/CodeSystem/provenance-participant-type"/>
        <code value="author"/>
      </coding>
    </type>
    <who>
      <identifier>
        <system value="https://gematik.de/fhir/sid/epa-fhir-data-service"/>
        <value value="MEDICATIONSVC"/>
      </identifier>
      <display value="ePA Medication Service"/>
    </who>
  </agent>
</Provenance>

Abruf des Änderungsverlaufs

Zur Auswertung und Nachverfolgung von Änderungen stellt der FHIR Data Service geeignete Zugriffsmöglichkeiten bereit. Diese ermöglichen es, den Änderungsverlauf zu einer oder mehreren Ressourcen gezielt abzufragen – beispielsweise basierend auf den Provenance-Instanzen, die für diese Ressourcen erstellt wurden. Eine direkte Abfrage kann z.B. über eine FHIR-Suche auf Provenance mit dem Suchparameter target oder über eine spezialisierte Operation des jeweiligen FHIR Data Service erfolgen.

Ablauf der Provenance-Erstellung bei Änderungen

Bei jeder fachlich relevanten Änderung an FHIR-Ressourcen wird eine Provenance-Instanz erzeugt, die den konkreten Zustand der betroffenen Ressourceninstanz zum Zeitpunkt der Änderung versioniert referenziert. Die Provenance wird dabei immer nach erfolgreicher Persistierung der geänderten Ressource (bzw. unmittelbar vor einem Löschvorgang) durch den FHIR Data Service erstellt.

Erzeugung bei Erstellung (CREATE)

Nach dem erfolgreichen Anlegen einer neuen Ressourceinstanz (z.B. MedicationRequest, MedicationStatement) wird eine Provenance-Instanz erzeugt, die auf die neu entstandene Version der Ressource verweist:

• Provenance.target → Resource/id/_history/1
• Provenance.activity = CREATE

Diese Provenance-Instanz dokumentiert die fachliche Erstellung der Ressourceninstanz durch den verantwortlichen Akteur (z.B. Leistungserbringerinstitution).

Erzeugung bei Aktualisierung (UPDATE)

Wird eine bestehende Ressourceninstanz geändert, entsteht eine neue Version. Nach erfolgreicher Aktualisierung wird eine Provenance-Instanz erzeugt, die auf die neu erzeugte Version verweist:

• Provenance.target → Resource/id/_history/n
• Provenance.activity = UPDATE

Damit ist nachvollziehbar, welche Änderungen an einer bestehenden Ressourceninstanz vorgenommen wurden und welcher konkrete Zustand dadurch entstanden ist.

Erzeugung bei Löschung (DELETE)

Beim Löschen einer Ressource wird eine Provenance-Instanz erstellt, bevor der Löschvorgang ausgeführt wird, um die letzte gültige Version der Ressourceninstanz zu referenzieren:

• Provenance.target → Resource/id/_history/n (letzte Version vor Löschung)
• Provenance.activity = DELETE

So bleibt der letzte bekannte Zustand der Ressourceninstanz nachvollziehbar.

Beispiel: Versionierung und Nachvollziehbarkeit

Durch dieses Vorgehen entsteht eine lückenlose Kette von Provenance-Einträgen:

• Provenance(CREATE) → Version 1
• Provenance(UPDATE) → Version 2
• Provenance(UPDATE) → Version 3
• Provenance(DELETE) → Version 3

FHIR-spezifische Anforderungen

Beispiel

http://epa4all/epa/audit/api/v1/fhir/AuditEvent/ea01ccbc-aa5d-4c34-8292-d95678d52c98

Persistieren der Profilversion in FHIR

Hinweis: Validierungsgrundlage bei Erhalt und anschließender Persistierung der FHIR-Ressource ist das aktuell gültige FHIR Package der zugehörigen Spezifikation beziehungsweise des Implementation Guide.