# Patient Service: Versicherteninformationen hinzufügen/aktualisieren - Implementation Guide ePA Basisfunktionalitäten v1.3.1

Implementation Guide

ePA Basisfunktionalitäten

Version 1.3.1 - release 

* [**Table of Contents**](toc.md)
* [**Basisdienst Patient Service**](api-patient.md)
* **Patient Service: Versicherteninformationen hinzufügen/aktualisieren**

## 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.
### 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:

| |
| :--- |
| oid_kostentraeger |

**Tabelle:**Befugbare Nutzergruppen mit Ausführungsrecht für das Hinzufügen und Aktualisieren von Versicherteninformationen
Generelle Sicherheitsanforderungen werden [hier](./privacy-security.md) festgehalten.

