# Retrieve Document - Implementation Guide ePA MHD Service v1.1.1

Implementation Guide

ePA MHD Service

Version 1.1.1 - release 

* [**Table of Contents**](toc.md)
* **Retrieve Document**

## Retrieve Document

Die **Retrieve-Document**-Transaktion des MHD Service basiert auf der IHE-Transaktion [ITI-68] der [MHD-Spezifikation](https://profiles.ihe.net/ITI/MHD/4.2.3/ITI-68.html#2-3-68-retrieve-document-iti-68). Sie wird vom ePA-Client-System verwendet, um ein Dokument abzurufen. Das Dokument kann dabei vorher über eine MHD Metadatensuche oder Volltextsuche gefunden werden oder anderweitig (z.B. aus dem XDS Document Service) bekannt sein.

### Einsatzbereich

Die Transaktion **Retrieve Document [ITI-68]** wird verwendet, um ein Dokument vom MHD Service abzurufen.

### Nachricht

**Abbildung:**
*Retrieve-Document*-Interaktion


Diese Nachricht ist eine HTTP GET-Request-Nachricht zum Abrufen des Dokuments der Form:

```
GET [base]/epa/mhd/retrieve/v1/content/<DocumentReference.identifier>.<file_extension>

```

Der **DocumentReference.identifier** ist gemäß [MHD-Metadaten-Mapping](./StructureDefinition-epa-mhd-document-reference-mappings.md) mit der **DocumentEntry.entryUUID** des dazugehörigen XDS-Dokuments belegt.

#### Auslösung

Das ePA-Client-System möchte ein Dokument herunterladen.

#### API

Das ePA-Client-System sendet eine HTTP GET-Request-Nachricht zum MHD Service.

Das MHD Service MUSS die nachstehende API unterstützen.

```

      {"resourceType":"CapabilityStatement","id":"epa-mhd-document-responder","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/mhd/api/v1/fhir/"}],"url":"https://gematik.de/fhir/epa-mhd/CapabilityStatement/epa-mhd-document-responder","version":"1.1.1","name":"EPAMHDDocumentResponder","title":"ePA MHD Service (Document Responder - Server)","status":"active","date":"2026-03-20","publisher":"gematik GmbH","contact":[{"telecom":[{"system":"url","value":"https://www.gematik.de"}]}],"description":"CapabilityStatement für den ePA MHD Service (Document Responder - Server)","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":"DocumentReference","supportedProfile":["https://gematik.de/fhir/epa-mhd/StructureDefinition/epa-mhd-document-reference"],"_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":"DocumentReference"}],"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"}],"versioning":"versioned-update","readHistory":true,"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":"Aktenweit eindeutige Kennung des Dokuments auf Basis von DocumentReference.entryUUID"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"_content","definition":"http://hl7.org/fhir/SearchParameter/Resource-content","type":"string","documentation":"Angaben für inhaltsbasierte Volltextsuche in von DocumentReference referenzierten Dokumenten"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"_lastUpdated","definition":"http://hl7.org/fhir/SearchParameter/Resource-lastUpdated","type":"date","documentation":"Änderungszeitpunkt der DocumentReference"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"author.given","type":"string","documentation":"Vorname der dokumenterstellenden Person auf Basis von DocumentReference.author, welcher dem authorPerson-Slot der DocumentEntry.author-Classification entspricht"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"author.family","type":"string","documentation":"Nachname der dokumenterstellenden Person auf Basis von DocumentReference.author, welcher dem authorPerson-Slot der DocumentEntry.author-Classification entspricht"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"author.organization.name","type":"string","documentation":"Name der dokumenterstellenden Leistungserbringerinstitution auf Basis von DocumentReference.author, welcher dem authorInstitution-Slot der DocumentEntry.author-Classification entspricht"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"category","definition":"http://hl7.org/fhir/SearchParameter/DocumentReference-category","type":"token","documentation":"Grobe Klassifizierung des Dokuments auf Basis von DocumentReference.category"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"contenttype","definition":"http://hl7.org/fhir/SearchParameter/DocumentReference-contenttype","type":"token","documentation":"MimeType des Dokuments auf Basis von DocumentReference.content.attachment.contentType"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"creation","definition":"https://profiles.ihe.net/ITI/MHD/SearchParameter/DocumentReference-Creation","type":"date","documentation":"Erstellungszeitpunkt des Dokuments auf Basis von DocumentReference.content.attachment.creation"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"date","definition":"https://profiles.ihe.net/ITI/MHD/SearchParameter/DocumentReference-date","type":"date","documentation":"Erstellungszeitpunkt der DocumentReference"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"description","definition":"http://hl7.org/fhir/SearchParameter/DocumentReference-description","type":"string","documentation":"Ergänzende Hinweise in Freitext auf Basis von DocumentReference.description"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"event","definition":"http://hl7.org/fhir/SearchParameter/DocumentReference-event","type":"token","documentation":"Die zur Erstellung des Dokuments geführten Ereignisse auf Basis von DocumentReference.context.event"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"facility","definition":"http://hl7.org/fhir/SearchParameter/DocumentReference-facility","type":"token","documentation":"Die auf Basis von DocumentReference.context.facilityTypeArt benannte Art der Einrichtung des dokumentierenden Ereignisses"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"format","definition":"http://hl7.org/fhir/SearchParameter/DocumentReference-format","type":"token","documentation":"Global eindeutiger Code für das Dokumentenformat  auf Basis von DocumentReference.content.format"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"identifier","definition":"http://hl7.org/fhir/SearchParameter/clinical-identifier","type":"token","documentation":"Aktenweit eindeutige Kennung des Dokuments auf Basis von DocumentReference.entryUUID"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"language","definition":"http://hl7.org/fhir/SearchParameter/DocumentReference-contenttype","type":"token","documentation":"Sprache in der ein Dokument verfasst ist"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"patient","definition":"http://hl7.org/fhir/SearchParameter/clinical-patient","type":"reference","documentation":"Aktenkontoinhaber"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"patient.identifier","type":"token","documentation":"Identifikator des Aktenkontoinhabers"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"period","definition":"http://hl7.org/fhir/SearchParameter/DocumentReference-period","type":"date","documentation":"Zeitraum des dokumentierenden Ereignisses auf Basis von DocumentReference.context.period"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"related","definition":"http://hl7.org/fhir/SearchParameter/DocumentReference-related","type":"reference","documentation":"ID-Liste mit assoziierten Dokumenten auf Basis von DocumentReference.context.related"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"security-label","definition":"http://hl7.org/fhir/SearchParameter/DocumentReference-security-label","type":"token","documentation":"Vertraulichkeitskennzeichnung/Datenkategorie des Dokuments auf Basis von DocumentReference.securityLabel"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"setting","definition":"http://hl7.org/fhir/SearchParameter/DocumentReference-setting","type":"token","documentation":"Art der Fachrichtung der erstellenden Einrichtung auf Basis von DocumentReference.context.practiceSetting"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"status","definition":"http://hl7.org/fhir/SearchParameter/DocumentReference-status","type":"token","documentation":"Status des Dokuments auf Basis von DocumentReference.status"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"title","definition":"https://gematik.de/fhir/epa-mhd/SearchParameter/epa-mhd-documentreference-title","type":"string","documentation":"Titel des Dokuments auf Basis von DocumentReference.content.attachment.title"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"type","definition":"http://hl7.org/fhir/SearchParameter/clinical-type","type":"token","documentation":"Art des Dokuments auf Basis von DocumentReference.type"}]},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"type":"Bundle","supportedProfile":["https://gematik.de/fhir/epa-mhd/StructureDefinition/epa-document-search-result-bundle"],"_supportedProfile":[{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}]}],"versioning":"versioned-update","readHistory":true}]}]}
    
```

Successful operation

Not Found

Not Acceptable

Das ePA-Client-System SOLL eine HTTP GET-Request-Nachricht nutzen, um Dokumente aus
*DocumentReference*-Instanzen über die URL aus deren FHIR-Element
*DocumentReference.content.attachment.url*) abzurufen.

Das ePA-Client-System DARF den HTTP
`If-Unmodified-Since`Header NICHT im HTTP GET-Request inkludieren.
#### Verarbeitung

Die HTTP-Antwortnachricht wird nach Bearbeitung des **Retrieve Document Request** gesendet.

Der MHD Service MUSS ausschließlich einen MIME-Type zurückgeben, welcher im Element
*DocumentReference.content.attachment.contentType*angegeben und damit konform zum IHE XDS Mapping ist.

Der MHD Service MUSS das Dokument im angeforderten MIME-Type bereitstellen oder mit dem HTTP Status Code
*406 "Not Acceptable"*antworten, wenn der angeforderte MIME-Type nicht verfügbar ist. Der MHD Service DARF das angeforderte Dokument NICHT transformieren.

Der MHD Service MUSS eine HTTP Response-Nachricht nach [RFC2616] erzeugen. Wenn das angeforderte Dokument zurückgegeben wird, MUSS der MHD Service mit dem HTTP Status Code 200 antworten. Der HTTP Body MUSS den Inhalt des angeforderten Dokuments beinhalten.

Wenn das angeforderte Dokument nicht existiert oder der Abruf des Dokuments dem Anfragenden nicht erlaubt ist, MUSS der MHD Service mit dem HTTP Status Code 404 antworten.
Für den Client darf es nicht unterscheidbar sein, ob das Dokument nicht vorhanden oder vor ihm verborgen ist.

### Sicherheitsanforderungen

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

