http://localhost:29221/alexanderwilms_7788/
RED medical offers a FHIR interface for third-party data providers/consumers. This interface is based on the German regulatory standards §291 (Verordnungssoftware - Schnittstelle / VOS) and §371 (Archiv- und Wechselschnittstelle / AWS) SGB V. These interfaces are based on the international FHIR-Standard with local extensions e.g. for statutory billing purposes.
RED Interchange API provides a third-party system with functions
The RED Interchange API uses the XML-based FHIR format for data exchange. Data to be sent to RED must be separated and packaged into FHIR bundles, and data queried from RED will be returned in FHIR bundles. RED uses the FHIR bundles defined by Kassenärztliche Bundesvereinigung in their AWS project.
In order to ensure the secrecy of person-related data (as required by German criminal law) RED uses end-to-end encryption of all person-related data stored in its data-centers. In order to access data in RED Users must authenticate during login and obtain the cryptographic keys necessary to decrypt and encrypt data. Therefore the RED Interchange API cannot be a server interface, as encryption keys are in the possession of the users only, and data cannot be encrypted or decrypted server-side. By requirement the RED Interchange API expects to communicate with an application installed on the local machine or a locally installed server reachable via localhost.
After a user has logged in successfully and obtained his cryptographic keys a local FHIR server is started by RED on the users machine. If the FHIR server is running RED will act as recipient and listen to POST and GET requests from the sending third-party application.
To use the RED Interchange API it must be set up for each RED terminal (Arbeitsplatz). For development and testing the tool Postman (https://www.postman.com/downloads/) can be used as sending application. Please contact us to receive a Postman collection with sample requests.
To query for data items stored in the RED database GET requests are sent to RED. A search requests uses GET and contains
Search requests will return all data items matching the given search criteria. Please note that search for patients is available on request only.
http://localhost:29221/alexanderwilms_7788/Condition?page=1&subject=Patient/6006 |
Example of a search request for all Conditions (=diagnoses) of patient with patient-ID 6006. In this example
localhost:29221
alexanderwilms_7788
Condition
(=diagnoses)A successful search request will be responded with a FHIR-Bundle. In this example two diagnoses are found for the given patient. The FHIR bundle has a wrapper with two entries. For detailed description of an entry see below.
<Bundle xmlns="http://hl7.org/fhir"> <id value="3548c21b-28e2-b29e-1f83-9a9658909dd6"/> <meta> <lastUpdated value="2022-06-24T19:39:11+00:00"/> // date-timestamp of request </meta> <type value="searchset"/> <total value="2"/> // number of results found and returned as <entry> <entry> <fullUrl value="/Condition/IEG6VfAE0uw0AuYyzQtx2oIsXLFbUslA"/> <resource> <Condition xmlns="http://hl7.org/fhir"> <id value="IEG6VfAE0uw0AuYyzQtx2oIsXLFbUslA"/> ... </Condition> </resource> </entry> <entry> <fullUrl value="/Condition/ROAG8t8Bz7MO8yHXAZOA5y2Tc5zVR8RA"/> <resource> <Condition xmlns="http://hl7.org/fhir"> <id value="ROAG8t8Bz7MO8yHXAZOA5y2Tc5zVR8RA"/> ... </Condition> </resource> </entry> </Bundle> |
Search is used to query if a certain data item or data items of a given type have been stored in RED. Search can be applied to
Read requests
In order to fetch a specific identifiable data item a Read request is used. A read requests uses GET and contains
http://localhost:29221/alexanderwilms_7788/Condition/IEG6VfAE0uw0AuYyzQtx2oIsXLFbUslA |
Example of a search request for all Conditions (=diagnoses) of a given patient. In this example
localhost:29221
alexanderwilms_7788
Condition
IEG6VfAE0uw0AuYyzQtx2oIsXLFbUslA
A read request for a specific data item will be answered with a single FHIR item of the reqested type.
<Condition xmlns="http://hl7.org/fhir"> <id value="IEG6VfAE0uw0AuYyzQtx2oIsXLFbUslA"/> <meta> <versionId value="1"/> <lastUpdated value="2022-04-27T00:00:00+00:00"/>. // date of creation / last update in RED <profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_AW_Diagnose|1.2.0"/> </meta> <text> // text contains a human-readable description of its content <status value="extensions"/> <div xmlns="http://www.w3.org/1999/xhtml">Diagnose von Patient Luca Fink</div> </text> <extension url="https://fhir.kbv.de/StructureDefinition/KBV_EX_AW_Diagnose_istDauerdiagnose"> <valueBoolean value="true"/> </extension> <extension url="https://fhir.kbv.de/StructureDefinition/KBV_EX_AW_istAbrechnungsrelevant"> <valueBoolean value="false"/> </extension <clinicalStatus> <coding> <system value="http://terminology.hl7.org/CodeSystem/condition-clinical"/> <code value="active"/> </coding> </clinicalStatus> <verificationStatus> <coding> <system value="http://terminology.hl7.org/CodeSystem/condition-ver-status"/> <code value="confirmed"/> </coding> </verificationStatus> <code> <coding> <system value="http://fhir.de/CodeSystem/dimdi/icd-10-gm"/> <version value="2017"/> <code value="I20.9"/> <display value="Angina pectoris"/> </coding> </code> <subject> <reference value="Patient/6tVbNJZq1buNwKmp6UKpd8CpLceNDlRF/_history/1"/> </subject> <encounter> <reference value="Encounter/P2U6P2J9K53tahcsGALfMyXA1wEAAroy/_history/1"/> </encounter> <recordedDate value="2022-04-27"/> </Condition> |
Search and read requests can retrieve data for these data types
Encounters represent a patient visit or consultation. Each time a patient record is created for a patient there will be corresponding encounter. Encounters are assignetd to a patient and may be searched.
{{baseURL}}/{{tenant}}/Encounter?page=1&subject=Patient/{{patientID}} |
ICD-10 patient diagnoses are represented by conditions.
{{baseURL}}/{{tenant}}/Condition?page=1&subject=Patient/{{patientID}} |
Medication returns all pharmaceuticals prescribed or documented for a patient.
{{baseURL}}/{{tenant}}/Medication?page=1&subject=Patient/{{patientID}} |
Document references are
A SEARCH request for document references returns a bundle of one or more FHIR items of type DocumentReference.
{{baseURL}}/{{tenant}}/DocumentReference?page=1&subject=Patient/{{patientID}} |
For each document found the FHIR bundle includes the base64-encoded document content. To avoid long loading time the request can be modified with the summary option to fetch the document metadata without the actual document content.
{{baseURL}}/{{tenant}}/DocumentReference?page=1&subject=Patient/{{patientID}}&_summary=true |
While search retrieves all data matching the given search criteria (e.g. a patient) specific items can be retrieved by adding their identification to the GET request.
A GET request to retrieve a specific item contains
> GET http://localhost:29221/{tenant}/Patient/1
A GET request containing an identifier always returns a single data item
<Patient xmlns="http://hl7.org/fhir">
<id value="1"/>
...
</Patient>
GET patient
This request will return a FHIR bundle containing the patient FHIR item of a given patient. Patients are identified by their user-readable Patient ID.
> GET http://localhost:29221/{tenant}/Patient/{id}
The Patient ID is displayed for each patient in the patient header. If a patient was created from external data using the FHIR interface the given external patient ID will be used.
GET Document
The base-64 encoded content of a document stored in RED can be accessed by requesting the document by its ID.
> GET http://localhost:29221/{tenant}/DocumentReference/eR4LDh4fJtmzlwTa
RED uses the internal patient record ID to identify the Document. This can be accessed by requesting all patient documents using the summary option, then requesting the document using the ID in the summary result.
> GET http://localhost:29221/{tenant}/DocumentReference?subject=Patient/{id}&_summary=true
This request returns a FHIR bundle with DocumentReferences. Each DocumentReference has its own unique ID.
<entry>
<fullUrl value="/DocumentReference/egMHGB0DlhuKsLzN"/>
<resource>
<DocumentReference xmlns="http://hl7.org/fhir">
<id value="egMHGB0DlhuKsLzN"/>
<meta>
<versionId value="1"/>
<lastUpdated value="2022-02-03T00:00:00+00:00"/>
<profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_AW_Anlage|1.2.0"/>
</meta>
Using this ID the full document content can be retrieved using a second GET request.
> GET http://localhost:29221/{tenant}/DocumentReference/egMHGB0DlhuKsLzN
POST requests can be used to send data to and create new data items in RED. Data to be created and stored must be packaged in FHIR bundles. A FHIR bundle contains all data necessary to create the new data item.
Example: the bundle of a new patient may contain (see Postman example Create Patient)
> POST http://localhost:29221/{tenant}/Bundle
Request Header should set the content-type to
> 'Content-Type': 'application/fhir+xml; charset=UTF-8'
Request body (see Postman examples)
<Bundle xmlns="http://hl7.org/fhir">
<id value="10000"/>
<meta>
<versionId value="1"/>
<lastUpdated value="2020-09-24T12:52:00+00:00"/>
<profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_AW_Bundle_Patientenakte|1.2.0"/>
</meta>
<type value="history"/>
<entry>
...
</entry>
<entry>
...
</entry>
</Bundle>
> DELETE http://localhost:29221/{tenant}/Bundle/10000
Deletes a stored bundle in RED medical application.
The RED interchange API may also be used to communicate with gematik Fachdienst to retrieve stored electronic prescriptions and to send dispense requests.
A prescription is identified by its PrescriptionID and the AccessCode. PrescriptionID and AccessCode are represented by the barcode on the prescription form. The barcode contains a string containing an array of urls. Each url is represented by a string with this format:
Task/<Prescription ID>/$accept?ac=<AccessCode>
{"urls":["Task/160.000.111.065.827.98/$accept?ac=b8d9e513cd11cfe0a1d829b96a503e9df5b17803bbdbc4036f32858494539f28"]}
In this example the prescriptionID is 160.000.111.065.827.98 and AccessCode is b8d9e513cd11cfe0a1d829b96a503e9df5b17803bbdbc4036f32858494539f28.
To get the prescription data for this prescription a GET request is sent:
Example
This request returns a FHIR bundle with several items.
This GET request can be used for the initial fetch of prescription data as well as further requests to fetch the same data later. When the FHIR bundle is returned from Fachdienst a second access code (“secret”) is added. All further requests to Fachdienst (in order to retrieve prescription data again, cancel or dispense the prescription) must include this secret to prove the requesters authorization to access the data. RED stores the secret in its database and adds it automatically for every further processing action of this request.
After a pharmacy has requested an electronic prescription from Fachdienst and received the FHIR bundle the Fachdienst locks the prescription. If the pharmacy is not able to deliver the prescribed products the prescription can be returned. If a prescription is returned it is released on Fachdienst and may be requested by someone else.
To return a prescription a GET request is sent. In addition to PrescriptionID and AccessCode RED automatically includes the secret.
Example
After a pharmacy has delivered the prescription a dispense request is created. The dispense request contains a FHIR bundle of type MedicationDispense.
The bundle is sent to RED using POST
> POST http://localhost:29221/{tenant}/Bundle