The RED interchange API connects systems with the electronic patient record (ePA). It provides features to check if a patient has an electronic record and if so allows to upload data to the patient record.
Every patient is entitled to a personal electronic health record (elektronische Patientenakte ePA). The electronic health record is provided by the patients health insurance organization. Physicians, pharmacies and other health providers shall be able to send documents to and read documents from the electronic health record which therefore acts as a central data exchange hub.
Access to the electronic health record is managed by the patient using a special application (Frontend des Versicherten). There are two ways of granting access
ad-hoc access: the health provider (e.g. a physician) must be connected to the Telematik-Infrastruktur and the patients smartcard (elektronische Gesundheitskarte) must be placed in a card terminal connected to the health providers system. The health provider then may request ad-hoc access, the patient confirms the request and allows access by entering his personal PIN to the card terminal. This process is not feasible for systems without access to the patient smartcard
regular access: the patient uses a feature in his Frontend des Versicherten application to select a health provider and grant access. For a system without access to the patient smartcard (e.g. DIGA) this is the only way to get access to the patient record.
Check record existence and access
If a system wants to use an electronic health record record it may use this request to
check if the patient has a record provided by an organization (identified by its HomeCommunityID)
check if the patient has granted access to the system.
This check is optional; RED will check the status every time a document is sent to the ePA. It is recommended to execute this request only once before the first document is sent.
The patient identifier (Versichertennummer der eGK) must be provided as parameter patient.
If sucessfull the request returns a http status 201 with an XML object containing status for the homeCommunity ID (a health record was provided for this patient) and for authorization of the system identified by its SMC-B. If no person identification was provided the request returs a status 404.
Send a document to the patients electronic health record (non-DiGA)
Data is sent to the electronic health record using aPOST request. The request body must include a valid FHIR bundle with a patient item and a document reference containing the data.
The patient item must reference the unique patient identifier (Versichertennummer)
The sending system identifies itself by its Telematik-ID. RED ensures connection to Telematik-Infrastruktur and access to the identifying SMC-B.
Data may be sent to the electronic patient record as PDF or XML (e.g. as medical information object MIO). The Frontend des Versicherten application however may not be able to display all XML-files in a meaningful way.
The data is handed over as a base64 string
Additional meta data is may be sent to describe the document in the electronic health record (see details below)
A successful request will return a http status code 200. If an error has occured the status code is 204 with a xml error description
POST request to send new data to an electronic health record
{{baseURL}}/{{tenant}}/Bundle?action=$createepa
Example: this POST requests sends data to the electronic patient record of the patient referenced in the FHIR bundle
In some cases more than one SMC-B is used to distinguish different sending systems. For this the SMC-B may be attributed with a name (in Terminal setup). The name of the SMC-B to use for the request must be added to the request parameters.
POST request to send new data to an electronic health record
Send a document to the patients electronic health record as a DiGA
Data is sent to the electronic health record using a POST request. The request body must include a valid FHIR bundle with a patient item and a document reference containing the data. Meta data for document description are not needed as all DiGA documents use a standardized meta data set. RED will automatically add the meta data to the document if the request contains the action "creatediga".
POST request to send new data to an electronic health record as a DiGA
{{baseURL}}/{{tenant}}/Bundle?action=$creatediga
Example: this POST requests sends data to the electronic patient record of the patient referenced in the FHIR bundle as a DiGA
The sending DiGA is identified by its SMC-B. If data is to be sent for several DiGAs each DiGA needs its own named SMC-B (naming in RED terminal setup). The name of the SMC-B to use for the request must be added to the request parameters.
POST request to send new data to an electronic health record
Each document is marked with a unique ID (DocumentEntry.entryUUID). This ID determines if the ePA treats the data received as a new document (new UUID) or an update for an existing document (UUID of the original document to be replaced). The UUID is created by RED. RED stores the UUID of each processed document and if a document is to be updated, place the correct UUID in the bundle.
Whether a document is a new or an update for an existing document is determined by you. The header of each document bundle contains an ID (Bundle.id) and a version number (Bundle.meta.versionId):
A new document is marked by an individual document ID (format determined by you) and versionId 1. An update must contain the same id and a versionId larger than 1.
The request body contains two entries - an entry with patient identification and the entry with the document to be sent.
<Bundle xmlns="http://hl7.org/fhir">
<id and bundle meta data>
<entry>
<resource>
<Patient>
<id> // is the patient identifier used by the sending system. It is not transmitted to the health record or used to identify the patient in other ways!
<meta>
<identifier>
<value> // is the unique patient identifier (Versichertennummer). This is required to identify the right patient.
</identifier>
<name>
</Patient>
</resource>
</entry>
<entry>
<resource>
<DocumentReference>
<identifier>
<content>
<attachment>
<contentType> // type of document (attachment/pdf or attachment/xml)
<extension> // optional set with meta information. The value sets are derived from the HL7 definition: https://wiki.hl7.de/index.php?title=IG:Value_Sets_f%C3%BCr_XDS
<title> // document title for display in patient ePA
<creation> // date for display and sorting in patient ePA
</attachment>
</DocumentReference>
</reference>
</entry>
</Bundle>
