Implementation Guide
ePA Basisfunktionalitäten
Version 1.2.0-ballot.1 - draft

Generelle Prinzipien

Seiteninhalt:

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 MUSS als Ausprägung eines FHIR Data Service sämtliche Anforderungen aus [IG_TICommon#Audit] berücksichtigen. Der Patient Service MUSS als Ausprägung eines FHIR Data Service sämtliche Anforderungen aus [IG_TICommon#Patient] berücksichtigen.

Schnittstellenimplementierung

Der FHIR Data Service im ePA-Aktensystem MUSS folgende HTTP Status Codes unterstützen:

Code Beschreibung Error Code Anmerkung
200 Successful operation - -
403 Requestor not authorized invalAuth no user session with valid ID-Token available
403 Requestor has no valid entitlement notEntitled -
403 Requestor role is not in the list of allowed user groups invalidOid -
403 Device registration does not exist unregisteredDevice if requestor role is oid_versicherter only
404 Health record is in state UNKNOWN or INITIALIZED noHealthRecord -
409 Health record is in state SUSPENDED or MAINTENANCE statusMismatch siehe 'Wiederholungsintervalle'
500 Any other error internalError siehe 'Wiederholungsintervalle'
Tabelle: HTTP Status Codes für die FHIR-Data-Service-Antwortnachrichten
 Der FHIR Data Service im ePA-Aktensystem MUSS Fehlercodes mit dem entsprechenden HTTP-Statuscode im Media Type application/json nach folgendem Schema zurückgeben: 

    {
      "errorCode": "statusMismatch"
    }
 Der FHIR Data Service MUSS für die Fehlermeldung SVC_IDENTITY_MISMATCH den HTTP-403, wenn die Telematik-ID im ID-Token (ausgestellt durch den IDP-Dienst) oder die KVNR im x-insurantid-HTTP Header nicht mit den FHIR-Daten übereinstimmt.

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"
    ]
  },
  "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"/>
  </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>

Wiederholungsintervalle

Die folgenden Wiederholungsintervalle werden im Falle einer Fehlerantwort definiert:

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

Organisationserkennung mittels X-Requesting-Organization

Zur Identifikation der Organisation, die 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 Organisation. Diese wird vom FHIR Data Service mit der im ID-Token enthaltenen Telematik-ID verglichen, um die Identität der Organisation zu verifizieren.

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

Der FHIR Data Service MUSS den HTTP-Header X-Requesting-Organization unterstützen, um die anfragende Organisation im Rahmen eines Requests zu identifizieren. Der HTTP-Header X-Requesting-Organization MUSS eine vollständig serialisierte FHIR Organization-Ressource im Format FHIR+JSON enthalten, die mit Base64 gemäß [RFC4648] kodiert ist. Der FHIR Data Service MUSS sicherstellen, dass die im HTTP-Header X-Requesting-Organization enthaltene Organization-Ressource dem Profil TIOrganization entspricht. Bei fehlschlagender Validierung ist die Operation mit HTTP-Status 400 Bad Request und einem OperationOutcome mit dem Fehlercode issue.code=structure und issue.detaiuls=SVC_ORG_HEADER_PROFILE_MISMATCH abzulehnen. 
{
  "resourceType" : "OperationOutcome",
  "id" : "3e5635b7-5546-4b2b-8509-a138652985e7",
  "meta" : {
    "profile" : [
      🔗 "https://gematik.de/fhir/ti/StructureDefinition/operation-outcome"
    ]
  },
  "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"/>
  </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>
Der FHIR Data Service MUSS die in der übermittelten Organization.identifier enthaltene Telematik-ID mit der im ID-Token (ausgestellt durch den IDP-Dienst) enthaltenen Telematik-ID vergleichen. Stimmen die beiden Werte nicht überein, ist die Anfrage mit dem HTTP-Statuscode 403 Forbidden abzulehnen. Zusätzlich ist eine OperationOutcome-Ressource mit dem Fehlercode SVC_IDENTITY_MISMATCH zurückzugeben.

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: ewogICJyZXNvdXJjZVR5cGUiOiAiT3JnYW5pemF0aW9uIiwKICAibWV0YSI6IHsKICAgICJwcm9maWxlIjogWwogICAgICAiaHR0cHM6Ly9nZW1hdGlrLmRlL2ZoaXIvdGkvU3RydWN0dXJlRGVmaW5pdGlvbi90aS1vcmdhbml6YXRpb24iCiAgICBdCiAgfSwKICAiaWRlbnRpZmllciI6IFsKICAgIHsKICAgICAgInN5c3RlbSI6ICJodHRwczovL2dlbWF0aWsuZGUvZmhpci9zaWQvdGVsZW1hdGlrLWlkIiwKICAgICAgInZhbHVlIjogIjktMi41OC4wMDAwMDA0MCIKICAgIH0KICBdLAogICJ0eXBlIjogWwogICAgewogICAgICAiY29kaW5nIjogWwogICAgICAgIHsKICAgICAgICAgICJjb2RlIjogIjEuMi4yNzYuMC43Ni40LjU0IiwKICAgICAgICAgICJzeXN0ZW0iOiAiaHR0cHM6Ly9nZW1hdGlrLmRlL2ZoaXIvZGlyZWN0b3J5L0NvZGVTeXN0ZW0vT3JnYW5pemF0aW9uUHJvZmVzc2lvbk9JRCIsCiAgICAgICAgICAiZGlzcGxheSI6ICLDlmZmZW50bGljaGUgQXBvdGhla2UiCiAgICAgICAgfQogICAgICBdCiAgICB9CiAgXSwKICAiYWxpYXMiOiBbCiAgICAiQXBvdGhla2UiCiAgXSwKICAiYWRkcmVzcyI6IFsKICAgIHsKICAgICAgImxpbmUiOiBbCiAgICAgICAgIkZyaWVkcmljaHN0ci4gMTM2IgogICAgICBdLAogICAgICAidGV4dCI6ICJnZW1hdGlrIEFwb3RoZWtlXG5GcmllZHJpY2hzdHIuIDEzNixcbjEwMTE3IEJlcmxpbiIsCiAgICAgICJjaXR5IjogIkJlcmxpbiIsCiAgICAgICJkaXN0cmljdCI6ICJNaXR0ZSIsCiAgICAgICJzdGF0ZSI6ICJCZXJsaW4iLAogICAgICAicG9zdGFsQ29kZSI6ICIxMDExNyIsCiAgICAgICJjb3VudHJ5IjogIkRFIgogICAgfQogIF0sCiAgImNvbnRhY3QiOiBbCiAgICB7CiAgICAgICJuYW1lIjogewogICAgICAgICJ0ZXh0IjogImdlbWF0aWsgSVRTTSIKICAgICAgfSwKICAgICAgInRlbGVjb20iOiBbCiAgICAgICAgewogICAgICAgICAgInN5c3RlbSI6ICJlbWFpbCIsCiAgICAgICAgICAidmFsdWUiOiAiYmV0cmllYkBnZW1hdGlrLmRlIgogICAgICAgIH0KICAgICAgXSwKICAgICAgInB1cnBvc2UiOiB7CiAgICAgICAgImNvZGluZyI6IFsKICAgICAgICAgIHsKICAgICAgICAgICAgImNvZGUiOiAiQURNSU4iLAogICAgICAgICAgICAic3lzdGVtIjogImh0dHA6Ly90ZXJtaW5vbG9neS5obDcub3JnL0NvZGVTeXN0ZW0vY29udGFjdGVudGl0eS10eXBlIgogICAgICAgICAgfQogICAgICAgIF0KICAgICAgfQogICAgfQogIF0sCiAgImFjdGl2ZSI6IHRydWUsCiAgIm5hbWUiOiAiZ2VtYXRpayBBcG90aGVrZSIKfQo=

Erstellen und Verwenden eines Änderungseintrags (Provenance)

Änderungseinträge im FHIR Data Service der ePA 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.

Der FHIR Data Service MUSS für Änderungseinträge das Profil EPAActivityProvenance verwenden. Der FHIR Data Service MUSS im Änderungseintrag (Provenance.target) ausschließlich versionierte Referenzen (ResourceType/id/_history/vid) auf die durch die Änderung entstandenen oder aktualisierten Ressourceninstanz angeben. Der FHIR Data Service MUSS im Änderungseintrag sowohl den fachlichen Zeitpunkt der Änderung (Provenance.occurred) als auch den technischen Erfassungszeitpunkt (Provenance.recorded) angeben. Der FHIR Data Service MUSS im Änderungseintrag (Provenance.activity) die Art der Änderung angeben. Zulässig sind nur Werte aus dem ValueSet EPAActivityProvenanceTypeVS.

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.
Der FHIR Data Service MUSS bei Aufrufen den verantwortlichen Akteur im Änderungseintrag (Provenance.agent.who) aus dem im Header X-Requesting-Organization übermittelten Organization-Ressource referenzieren und den Identifier (Provenance.agent.who.identifier) sowie den Anzeigenamen (Provenance.agent.who.display) angeben. 
{
  "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"
    ]
  },
  "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"/>
  </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”).

Der FHIR Data Service MUSS bei selbstständig ausgelösten Änderungen sich selbst als verantwortlichen Akteur im Änderungseintrag (Provenance.agent.who) mit einem eindeutigen Identifier gemäß dem Profil IdentifierEPAFHIRDataService angeben. 
{
  "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"
    ]
  },
  "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"/>
  </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.

FHIR-spezifische Anforderungen

Der FHIR Data Service MUSS im Element Reference bei gleichzeitiger Angabe einer literal reference (References.reference) und einer logischen Referenz (References.identifier) die literal reference bevorzugt auswerten. Die Verarbeitung der logischen Referenz erfolgt nur, wenn keine literal reference vorhanden ist. Der FHIR Data Service des ePA-Aktensystems MUSS sicherstellen, dass der Host der absoluten URL im Feld Bundle.entry.fullUrl stets epa4all ist. Andere Hostnamen sind unzulässig.

Beispiel

http://epa4all/epa/audit/api/v1/fhir/AuditEvent/ea01ccbc-aa5d-4c34-8292-d95678d52c98
Der FHIR Data Service MUSS sicherstellen, dass bei der Erstellung von Referenzen zu einer Practitioner- oder Organization-Resourceninstanz die Reference.display Eigenschaft mit der Information aus Practitioner.name.text bzw. Organization.name der referenzierten Practitioner- bzw. Organization-Instanz gefüllt wird.