Implementation Guide
ePA Basisfunktionalitäten
Version 1.3.1 - release

## Patient Service: Versicherteninformationen hinzufügen/aktualisieren

Das Hinzufügen und Aktualisieren einer Patient-Ressource wird vom zugehörigen Kostenträger über die FHIR RESTful API mittels HTTP PUT-Anfrage für den Versicherten durchgeführt. Der Patient Service setzt die Semantik des [FHIR Conditional update] um.

### Einsatzbereich

Die Primärsysteme der Kostenträger nutzen diese Operation, um die Versicherteninformationen hinzuzufügen oder zu aktualisieren.

### Nachricht

Die Nachricht zum Hinzufügen oder Aktualisieren der Versicherteninformationen durch den zuständigen Kostenträger.

#### Auslösung

Ein Kostenträger übermittelt die Versicherteninformationen, wenn ein Aktenkonto in einem ePA-Aktensystem angelegt wird oder sich demografische Daten ändern, wie beispielsweise Name, Anrede sowie amtliches Geschlecht.

#### Resource API

##### Conditional Update

Die bedingte Aktualisierung ([FHIR Conditional update]) ermöglicht das Aktualisieren einer vorhandenen FHIR-Ressourceninstanz anhand eines Identifikationskriteriums anstelle einer direkten Referenz über die logische ID. Falls keine passende Ressourceninstanz existiert, wird eine neue erstellt.

Bedingtes Update über Suchparameter

Die Aktualisierung einer FHIR-Ressourceninstanz erfolgt über eine HTTP PUT-Anfrage mit Suchparametern:

    PUT [base]/[type]?[search parameters]

Der Patient Service MUSS die Funktionalität eines Conditional Update gemäß der FHIR R4-Spezifikation [FHIR Conditional update] vollständig unterstützen. Dies ermöglicht die Aktualisierung einer FHIR-Ressourceninstanz anhand von Suchparametern, ohne dass eine direkte Referenz über die ID erforderlich ist.

          {"resourceType":"CapabilityStatement","id":"epa-patient-server","meta":{"profile":["https://gematik.de/fhir/ti/StructureDefinition/ti-capability-statement"]},"extension":[{"extension":[{"url":"name","valueString":"X-Request-ID"},{"url":"type","valueString":"string"},{"url":"description","valueString":"UUID of the request message"},{"url":"format","valueString":"uuid"},{"url":"required","valueBoolean":true}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-header"},{"extension":[{"url":"name","valueString":"x-insurantid"},{"url":"type","valueString":"string"},{"url":"description","valueString":"Health Record Identifier"},{"url":"pattern","valueString":"^[A-Z]{1}\\d{9}$"},{"url":"required","valueBoolean":true}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-header"},{"extension":[{"url":"name","valueString":"x-useragent"},{"url":"type","valueString":"string"},{"url":"description","valueString":"user agent information"},{"url":"pattern","valueString":"^[a-zA-Z0-9]{20}\\/[a-zA-Z0-9\\-\\.]{1,15}$"},{"url":"required","valueBoolean":true}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-header"},{"extension":[{"url":"statusCode","valueString":"403"},{"url":"description","valueString":"Requestor not authorized (no user session with valid ID-Token available)"},{"url":"responseType","valueString":"application/json"},{"url":"errorCode","valueString":"invalAuth"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"403"},{"url":"description","valueString":"Requestor has no valid entitlement"},{"url":"responseType","valueString":"application/json"},{"url":"errorCode","valueString":"notEntitled"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"403"},{"url":"description","valueString":"Requestor role is not in the list of allowed user groups"},{"url":"responseType","valueString":"application/json"},{"url":"errorCode","valueString":"invalidOid"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"403"},{"url":"description","valueString":"Device registration does not exist (if requestor role is oid_versicherter only)"},{"url":"responseType","valueString":"application/json"},{"url":"errorCode","valueString":"unregisteredDevice"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"404"},{"url":"description","valueString":"Health record is in state UNKNOWN or INITIALIZED"},{"url":"responseType","valueString":"application/json"},{"url":"errorCode","valueString":"noHealthRecord"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"409"},{"url":"description","valueString":"Request conflicts with the current state of the health record"},{"url":"responseType","valueString":"application/json"},{"url":"errorCode","valueString":"statusMismatch"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"500"},{"url":"description","valueString":"Any other error"},{"url":"responseType","valueString":"application/json"},{"url":"errorCode","valueString":"internalError"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-base-url","valueString":"http://epa4all/epa/patient/api/v1/fhir"}],"url":"https://gematik.de/fhir/epa/CapabilityStatement/epa-patient-server","version":"1.3.1","name":"EPAPatientServer","title":"EPA CapabilityStatement für den Patient Service","status":"active","date":"2025-03-20","publisher":"gematik GmbH","contact":[{"telecom":[{"system":"url","value":"https://www.gematik.de"}]}],"description":"EPA Capability Statement für den Patient Service","jurisdiction":[{"coding":[{"system":"urn:iso:std:iso:3166","code":"DE"}]}],"copyright":"gematik GmbH / Dieser Implementation Guide ist lizenziert unter [Apache License](./license.html), Version 2.0.","kind":"requirements","imports":["https://gematik.de/fhir/epa/CapabilityStatement/epa-basic-server"],"_imports":[{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}]}],"fhirVersion":"4.0.1","format":["application/fhir+json","application/fhir+xml"],"rest":[{"mode":"server","resource":[{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"type":"Patient","profile":"https://gematik.de/fhir/epa/StructureDefinition/epa-patient","_profile":{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}]},"supportedProfile":["https://gematik.de/fhir/ti/StructureDefinition/ti-patient"],"_supportedProfile":[{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}]}],"interaction":[{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"},{"extension":[{"url":"statusCode","valueString":"200"},{"url":"description","valueString":"Successful operation"},{"url":"responseType","valueString":"Bundle"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"400"},{"url":"description","valueString":"Unknown search parameter"},{"url":"responseType","valueString":"TIOperationOutcome"},{"url":"errorCode","valueString":"MSG_PARAM_UNKNOWN"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"400"},{"url":"description","valueString":"Invalid query parameter(s)"},{"url":"responseType","valueString":"TIOperationOutcome"},{"url":"errorCode","valueString":"MSG_BAD_SYNTAX"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"400"},{"url":"description","valueString":"Invalid request"},{"url":"responseType","valueString":"TIOperationOutcome"},{"url":"errorCode","valueString":"MSG_BAD_FORMAT"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"404"},{"url":"description","valueString":"Unknown resource type"},{"url":"responseType","valueString":"TIOperationOutcome"},{"url":"errorCode","valueString":"MSG_UNKNOWN_TYPE"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"}],"code":"search-type"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"},{"extension":[{"url":"statusCode","valueString":"200"},{"url":"description","valueString":"Successful operation"},{"url":"responseType","valueString":"Bundle"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"400"},{"url":"description","valueString":"Invalid request"},{"url":"responseType","valueString":"TIOperationOutcome"},{"url":"errorCode","valueString":"MSG_BAD_FORMAT"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"404"},{"url":"description","valueString":"Unknown resource type"},{"url":"responseType","valueString":"TIOperationOutcome"},{"url":"errorCode","valueString":"MSG_UNKNOWN_TYPE"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"}],"code":"history-type"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"},{"extension":[{"url":"statusCode","valueString":"200"},{"url":"description","valueString":"Successful operation"},{"url":"responseType","valueString":"EPAPatient"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"400"},{"url":"description","valueString":"Invalid request"},{"url":"responseType","valueString":"TIOperationOutcome"},{"url":"errorCode","valueString":"MSG_BAD_FORMAT"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"404"},{"url":"description","valueString":"Unknown resource type"},{"url":"responseType","valueString":"TIOperationOutcome"},{"url":"errorCode","valueString":"MSG_UNKNOWN_TYPE"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"404"},{"url":"description","valueString":"Resource is not known"},{"url":"responseType","valueString":"TIOperationOutcome"},{"url":"errorCode","valueString":"MSG_RESOURCE_ID_FAIL"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"}],"code":"read"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"},{"extension":[{"url":"statusCode","valueString":"200"},{"url":"description","valueString":"Successful operation"},{"url":"responseType","valueString":"Bundle"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"400"},{"url":"description","valueString":"Invalid request"},{"url":"responseType","valueString":"TIOperationOutcome"},{"url":"errorCode","valueString":"MSG_BAD_FORMAT"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"404"},{"url":"description","valueString":"Unknown resource type"},{"url":"responseType","valueString":"TIOperationOutcome"},{"url":"errorCode","valueString":"MSG_UNKNOWN_TYPE"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"404"},{"url":"description","valueString":"Resource is not known"},{"url":"responseType","valueString":"TIOperationOutcome"},{"url":"errorCode","valueString":"MSG_RESOURCE_ID_FAIL"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"}],"code":"history-instance"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"},{"extension":[{"url":"statusCode","valueString":"200"},{"url":"description","valueString":"Successful operation"},{"url":"responseType","valueString":"EPAPatient"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"400"},{"url":"description","valueString":"Invalid request"},{"url":"responseType","valueString":"TIOperationOutcome"},{"url":"errorCode","valueString":"MSG_BAD_FORMAT"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"404"},{"url":"description","valueString":"Unknown resource type"},{"url":"responseType","valueString":"TIOperationOutcome"},{"url":"errorCode","valueString":"MSG_UNKNOWN_TYPE"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"404"},{"url":"description","valueString":"Resource is not known"},{"url":"responseType","valueString":"TIOperationOutcome"},{"url":"errorCode","valueString":"MSG_RESOURCE_ID_FAIL"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"}],"code":"vread"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"},{"extension":[{"url":"statusCode","valueString":"201"},{"url":"description","valueString":"Created, wenn eine neue Ressourceninstanz erstellt wurde"},{"url":"responseType","valueString":"EPAPatient"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"200"},{"url":"description","valueString":"Successful operation"},{"url":"responseType","valueString":"EPAPatient"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"400"},{"url":"description","valueString":"Invalid request"},{"url":"responseType","valueString":"TIOperationOutcome"},{"url":"errorCode","valueString":"MSG_BAD_FORMAT"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"400"},{"url":"description","valueString":"Invalid request"},{"url":"responseType","valueString":"application/json"},{"url":"errorCode","valueString":"malformedRequest"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"422"},{"url":"description","valueString":"Unprocessable Content, falls ein falscher Identifier (KVNR) in der Anfrage angegeben wurde"},{"url":"responseType","valueString":"TIOperationOutcome"},{"url":"errorCode","valueString":"MSG_RESOURCE_ID_MISMATCH"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"403"},{"url":"description","valueString":"ID-Token or Insurant-ID mismatch"},{"url":"responseType","valueString":"TIOperationOutcome"},{"url":"errorCode","valueString":"SVC_IDENTITY_MISMATCH"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"404"},{"url":"description","valueString":"Unknown resource type"},{"url":"responseType","valueString":"TIOperationOutcome"},{"url":"errorCode","valueString":"MSG_UNKNOWN_TYPE"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"404"},{"url":"description","valueString":"Resource is not known"},{"url":"responseType","valueString":"TIOperationOutcome"},{"url":"errorCode","valueString":"MSG_RESOURCE_ID_FAIL"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"422"},{"url":"description","valueString":"Unprocessable Entity"},{"url":"responseType","valueString":"TIOperationOutcome"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"412"},{"url":"description","valueString":"Precondition Failed, wenn mehrere Ressourceninstanzen gefunden wurden"},{"url":"responseType","valueString":"TIOperationOutcome"},{"url":"errorCode","valueString":"UPDATE_MULTIPLE_MATCHES"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"}],"code":"update"}],"versioning":"versioned-update","readHistory":true,"conditionalUpdate":true,"_conditionalUpdate":{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}]},"searchParam":[{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"identifier","definition":"http://hl7.org/fhir/SearchParameter/Patient-identifier","type":"token","documentation":"Patient.identifier"}]}]}]}

Beispiel:

              PUT [base]/epa/patient/api/v1/fhir/Patient?identifier=http://fhir.de/sid/gkv/kvid-10|G995030566
              Content-Type: application/fhir+json
              x-insurantid: G995030566
              X-Request-ID: 3f19049d-5c73-450e-94f3-856b43a9a9c3

Das ePA-Client-System des Kostenträgers MUSS die Versicherteninformationen übermitteln, wenn ein Aktenkonto in einem ePA-Aktensystem angelegt wird oder sich demografische Daten ändern, wie beispielsweise Name, Anrede beziehungsweise amtliches Geschlecht. Der Patient Service MUSS beim Erstellen und Aktualisieren von Patient-Ressourceninstanzen eine Validierung gegen das Profil EPAPatient durchführen. Der Patient Service MUSS bei einem Conditional Update, wenn keine bestehende Patient-Ressource gefunden wird und daher eine neue Instanz erstellt wird, mit dem HTTP Status Code 201 antworten und die neu erstellte Ressource gemäß dem Profil EPAPatient in der Antwort zurückgeben. Der Patient Service MUSS bei einem Conditional Update, wenn eine bestehende Patient-Ressource gefunden und erfolgreich aktualisiert wird, mit dem HTTP Status Code 200 antworten und die aktualisierte Ressource gemäß dem Profil EPAPatient in der Antwort zurückgeben. Der Patient Service MUSS beim Aktualisieren einer bestehenden Patient-Instanz per HTTP PUT, wenn sich der Inhalt der Ressource nicht gegenüber dem gespeicherten Zustand geändert hat, mit dem HTTP Status Code 200 antworten und die unveränderte Ressource in der Antwort zurückgeben. Der Patient Service MUSS beim Versuch eines Conditional Update mit einer ungültigen oder abweichenden KVNR mit dem HTTP Status Code 403 antworten und ein OperationOutcome mit dem Wert SVC_IDENTITY_MISMATCH in issue.details.coding.code zurückgeben.

    {
      "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" : "Identity mismatch: Access token or x-insurantid header does not match FHIR data (Telematik-ID / KVNR)"
              }
            ]
          }
        }
      ]
    }

### Sicherheitsanforderungen

Der Patient Service MUSS die Zugriffsrechte zur generellen Ausführung der Versicherteninformationen hinzufügen/aktualisieren Operation für ePA-Client-Systeme mit der Nutzergruppe aus der nachstehenden Liste zulassen:

professionOID
oid_kostentraeger

Tabelle: Befugbare Nutzergruppen mit Ausführungsrecht für das Hinzufügen und Aktualisieren von Versicherteninformationen

Generelle Sicherheitsanforderungen werden hier festgehalten.