# Audit Event Service: Render API - Implementation Guide ePA Basisfunktionalitäten v1.3.1

Implementation Guide

ePA Basisfunktionalitäten

Version 1.3.1 - release 

* [**Table of Contents**](toc.md)
* [**Basisdienst Audit Event Service**](api-audit.md)
* **Audit Event Service: Render API**

## Audit Event Service: Render API

Der Audit Event Service unterstützt die Abfrage aufbereiteter Protokolle im Datenformat PDF/A (d.h. **kein** FHIR) über die **Render API: AuditEvent**.

### Einsatzbereich

Ein Nutzer des ePA-Client-Systems möchte keinen FHIR-basierte Abruf mit spezifischen Filtermöglichkeiten durchführen und stattdessen eine aufbereitete Anzeige protokollierter Ereignisse und ePA-Zugriffe in Form eines PDF/A-Dokuments anzeigen.

### Nachricht

Die Nachricht zum Abruf von Protokolldaten wird als HTTP GET-Anfrage an den Audit Event Service gesendet, um eine Liste von Audit-Ereignissen in Form eines PDF/A-Dokuments abzurufen.

#### Auslösung

Wenn das ePA-Client-System eine zeitbasierte Suche über protokollierter Ereignisse und ePA-Zugriffe durchführen möchte, sendet er eine **Render API: AuditEvent**-Nachricht an den Audit Event Service.

#### API

```

    {"resourceType":"CapabilityStatement","id":"epa-audit-event-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/audit/api/v1/fhir"}],"url":"https://gematik.de/fhir/epa/CapabilityStatement/epa-audit-event-server","version":"1.3.1","name":"EPAAuditEventServer","title":"EPA Capability Statement für den Audit Event 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 Audit Event 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":"AuditEvent","profile":"https://gematik.de/fhir/epa/StructureDefinition/epa-auditevent","_profile":{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}]},"supportedProfile":["https://gematik.de/fhir/epa/StructureDefinition/epa-auditevent"],"_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":"EPAAuditEvent"}],"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"}],"searchParam":[{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"_id","definition":"http://hl7.org/fhir/SearchParameter/Resource-id","type":"token","documentation":"Resource.id"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"_lastUpdated","definition":"http://hl7.org/fhir/SearchParameter/Resource-lastUpdated","type":"date","documentation":"Resource.meta.lastUpdated"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"action","definition":"http://hl7.org/fhir/SearchParameter/AuditEvent-action","type":"token","documentation":"AuditEvent.action"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"altid","definition":"http://hl7.org/fhir/SearchParameter/AuditEvent-altid","type":"token","documentation":"AuditEvent.agent.altId"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"date","definition":"http://hl7.org/fhir/SearchParameter/AuditEvent-date","type":"date","documentation":"AuditEvent.recorded"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"outcome","definition":"http://hl7.org/fhir/SearchParameter/AuditEvent-outcome","type":"token","documentation":"AuditEvent.outcome"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"entity-name","definition":"http://hl7.org/fhir/SearchParameter/AuditEvent-entity-name","type":"string","documentation":"AuditEvent.entity.name"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"agent-name","definition":"http://hl7.org/fhir/SearchParameter/AuditEvent-agent-name","type":"string","documentation":"AuditEvent.agent.name"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"type","definition":"http://hl7.org/fhir/SearchParameter/AuditEvent-type","type":"token","documentation":"AuditEvent.type"}]}]}]}
    
```

Signierte PDF/A anfordern (`true`) oder unsignierte PDF/A anfordern (`false`)

Frühester Zeitpunkt zur Berücksichtigung der Audit-Ereignisse z.B. 2025-07-15T00:00:00Z

Spätester Zeitpunkt zur Berücksichtigung der Audit-Ereignisse z.B. 2025-07-15T23:59:59Z

Successful operation

Request (parameters) are malformed

**Beispiele**

Den Audit Event Service zur Bereitstellung eines signierten PDF/A anfragen:

```
GET [base]/epa/audit/render/v1/pdf?signed=true

```

Den Audit Event Service zur Bereitstellung eines unsignierten PDF/A für die Protokolleinträge vom 15. Juli 2025 anfragen:

```
GET [base]/epa/audit/render/v1/pdf?lowerDateTime=2025-07-15T00:00:00Z&upperDateTime=2025-07-15T23:59:59Z

```

#### Verarbeitung

Der Audit Event Service MUSS eine Liste von Audit-Event-Ereignissen als PDF/A (signiert oder unsigniert) erstellen und bei diesem API GET Aufruf zurückgeben.

Der Audit Event Service muss in der
*Render API: PDF Audit*den Parameter signed unterstützen.

* *signed*=true fordert eine signiertes PDF/A an
* *signed*=false fordert eine unsigniertes PDF/A an

Die Standardsortierung der Daten in dem PDF/A-Export des Audit Event Service MUSS anhand des Attributs
*recorded*in absteigender Reihenfolge, sodass die neuesten Daten zuerst angezeigt werden.

Der Audit Event Service MUSS für die
*Render API: PDF Audit*bei einer erfolgreichen Ausgabe im PDF/A-Format den Media Type
*application/pdf*im HTTP Header Content-Type setzen und den HTTP Status Code 200 zurückgeben.

Der Audit Event Service MUSS auch dann ein PDF/A für die protokollierten Ereignisse als Ergebnis einer Anfrage über die Render API: PDF Audit erzeugen, wenn keine protokollierten Ereignisse für den verwendeten Suchbereich vorliegen. In diesem Fall MUSS anstelle der Liste der Ereignisse ein für den Versicherten verständlicher Hinweistext verwendet werden, welcher den Versicherten darüber informiert, dass für den betrachteten Zeitraum keine protokollierten Ereignisse zur Ausgabe vorliegen.

Der Audit Event Service MUSS in der
*Render API: PDF Audit*die Suchparameter
*lowerDateTime*und
*upperDateTime*unterstützen.

* *lowerDateTime* definiert den frühesten Zeitpunkt zur Berücksichtigung der *AuditEvent*-Ereignisse
* *upperDateTime* definiert den spätesten Zeitpunkt zur Berücksichtigung der *AuditEvent*-Ereignisse

Der Audit Event Service MUSS für die
*Render API: PDF Audit*, falls Suchparameter
*lowerDateTime*oder
*upperDateTime*im falschen Format vorliegen oder mehr als einmal vorkommen, den HTTP Status Code
*400*mit dem Error Code
*malformedRequest*zurückgeben.
### Sicherheitsanforderungen

Generelle Sicherheitsanforderungen werden [hier](./privacy-security.md) festgehalten.

