RED Interchange API

http://localhost:29221/alexanderwilms_7788/

Introduction

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

to send data to RED for processing and storage. This allows a third-party system e.g. to send data of patients that have been registered to RED. Patient data will be validated in RED as if entered manually and stored in the RED database using the RED end-to-end encryption.
to query data from RED. The third-party system may send query requests to RED (e.g. for patients, patient records or documents) and RED will return data retrieved from its database
to execute transactions with the Telematik-Infrastruktur such as basic Konnektor operations (e.g. PIN verification) or complex transactions (e.g. dispensing an electronic prescription)

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.

Setup in RED

In order to use the RED Interchange API you will need an account in RED. Please contact us for an offer and help.

If you have a RED account open RED in your web browser https://redclient.redmedical.de/redclient/index.html and log in using your user credentials. If you log in on a machine for the first time you will be prompted to install RED commander. RED commander is a local application enabling RED to access the local resources and to execute the FHIR server. Download and install the RED commander using the installation wizard. RED commander - Technische Informationen | RED commander - Installation

The FHIR interface is disable by default. If it is to be used the FHIR server must be enabled for each machine. Log in as an administrator user and navigate to management of terminals (search for #b arbeits and select Arbeitsplätze. Select your current terminal (marked by ICH) and navigate down to the Schnittstelle FHIR section.

RED shows a list of all FHIR interfaces defined for this terminal. A FHIR interface may be active or paused. Active FHIR interfaces are marked by Aktiv. Click on FHIR-Schnittstelle hinzufügen to create a new FHIR interface or FHIR-Schnittstelle bearbeiten to modify an existing definition.

Schnittstelle verwenden: allows to activate and deactivate the interface (e.g. for testing purposes)

Bezeichnung: name of this interface

Typ der Schnittstelle: for RED Interchange API select the option “FHIR-Schnittstelle”

Sichere Verbindung: if set to “Nein” a http-connection is used, if set to “Ja”, https is used

Anwendungsadresse: path to the application that is to be opened by RED

Erweiterte Optionen: options string to send to the application when opened (not required)

Save the setting with the orange Speichern button. The interface is set up and FHIR server will be started automatically during the next login.

For testing purposes on a local environment the interface can be reached at: http://localhost:29221/{tenantID}. The tenantID is the internal ID of the RED instance. You will find your tenant ID by clicking on the user name (next to the house icon) in the top panel. The tenant ID is shown as ID.

Receiving data from RED - Search and Get

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.

Search

To query for data items stored in the RED database GET requests are sent to RED. A search requests uses GET and contains

address of the system (base URL)
RED tenant ID
type of data to fetch (e.g Patient) with attributes
page set to restrict amount of data to fetch
optional further parameters to restrict the search

Search requests will return all data items matching the given search criteria. Please note that search for patients is available on request only.

Example for a SEARCH request to search for a patients diagnoses

http://localhost:29221/alexanderwilms_7788/Condition?page=1&subject=Patient/6006

Example of a search request for all Conditions (=diagnoses) of a given patient. In this example

base URL is localhost:29221
RED tenant ID is alexanderwilms_7788
type of data to fetch is Condition

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 entries see below.

Example for the SEARCH result FHIR bundle wrapper

<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

Encounters (Visits or consultations) and Chargecodes
Diagnoses
Medication (orders and overviews)
History items documented in patient record
Document references, including stored files (e.g PDF files from scanner or imaging results, printouts of forms created (e.g. Muster, Rezepte) or letters written
Practitioners and Organizations (users and user groups)

Read

In order to fetch a specific identifiable data item a Read request is used. A read requests uses GET and contains

address of the system (base url)
RED tenant ID
type of data to fetch (e.g Patient)
identifier of the specific data item. The identifier may be an external identifier sent by the third-party system when the data item was created in RED or may have been retrieved by search

Example for a READ request for a specific condition

http://localhost:29221/alexanderwilms_7788/Condition/IEG6VfAE0uw0AuYyzQtx2oIsXLFbUslA

Example of a search request for all Conditions (=diagnoses) of a given patient. In this example

base URL is localhost:29221
RED tenant ID is alexanderwilms_7788
type of data to fetch is Condition
identifier of the condition to fetch is IEG6VfAE0uw0AuYyzQtx2oIsXLFbUslA

A read request for a specific data item will be answered with a single FHIR item of the reqested type.

Example for an entry in the FHIR bundle of search or result of read request

<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>

Practitioners

Practitioners are the physicians defined in RED as users/user LANRs. Practitioners contain names and identifiers for physicians. Practitioners can be searched using a search request. Search returns a bundle of one or more FHIR items of type KBV_PR_AW_Behandelnder.

SEARCH request for all practitioners

{{baseURL}}/{{tenant}}/Practitioner?page=1

Example: this search requests fetches all practitioners using paging to limit the number of results.

Data of a specific practitioner may be fetched using a read request with the identifier of the specific practitioner. The request returns a FHIR item of type KBV_PR_AW_Behandelnder

READ request for a specific practitioner

{{baseURL}}/{{tenant}}/Practitioner/wK7hhpbEIG1qkSdvRCCd3AEA3W4lBfDB

Example: this read request returns the FHIR item for practitionier with ID wK7hhpbEIG1qkSdvRCCd3AEA3W4lBfDB. The ID may be retrieved by a search request sent before this request.

Example of a FHIR item practitioner

<Practitioner xmlns="http://hl7.org/fhir">
    <id value="wK7hhpbEIG1qkSdvRCCd3AEA3W4lBfDB"/>
    <meta>
        <versionId value="1"/>
        <lastUpdated value="2022-06-27T18:54:31+00:00"/>
        <profile value="https://fhir.kbv.de/StructureDefinition/KBV_PR_AW_Behandelnder|1.2.0"/>
    </meta>
    <text>
        <status value="extensions"/>
        <div xmlns="http://www.w3.org/1999/xhtml">Behandler Dr. med. Annie More (V1) | ID wK7hhpbEIG1qkSdvRCCd3AEA3W4lBfDB | Geschlecht unbekannt | Qualifikation Allgemeinmedizin | LANR 362364901 | Adresse Hauptstrasse 180, 56170 Bendorf | Telefon 0171 1014211 | E-Mail aw@redmedical.de | zuletzt bearbeitet 2022-06-27T18:54:31+00:00</div>
    </text>
    <identifier>
        <type>
            <coding>
                <system value="http://terminology.hl7.org/CodeSystem/v2-0203"/>
                <code value="LANR"/>
            </coding>
        </type>
        <system value="https://fhir.kbv.de/NamingSystem/KBV_NS_Base_ANR"/>
        <value value="362364901"/>
    </identifier>
    <name>
        <use value="official"/>
        <text value="Dr. med. Annie More"/>
        <family value="More">
            <extension url="http://hl7.org/fhir/StructureDefinition/humanname-own-name">
                <valueString value="More"/>
            </extension>
        </family>
        <given value="Annie"/>
        <prefix value="Dr. med.">
            <extension url="http://hl7.org/fhir/StructureDefinition/iso21090-EN-qualifier">
                <valueCode value="AC"/>
            </extension>
        </prefix>
    </name>
    <telecom>
        <system value="phone"/>
        <value value="01711014211"/>
    </telecom>
    <telecom>
        <system value="fax"/>
        <value value="0643144672"/>
    </telecom>
    <telecom>
        <system value="email"/>
        <value value="annie.more@redmedical.de"/>
    </telecom>
    <address>
        <type value="both"/>
        <line value="Hauptstrasse 180">
            <extension url="http://hl7.org/fhir/StructureDefinition/iso21090-ADXP-streetName">
                <valueString value="Hauptstrasse"/>
            </extension>
            <extension url="http://hl7.org/fhir/StructureDefinition/iso21090-ADXP-houseNumber">
                <valueString value="180"/>
            </extension>
        </line>
        <city value="Bendorf"/>
        <postalCode value="56170"/>
        <country value="D"/>
    </address>
    <gender value="female"/>
    <qualification>
        <code>
            <coding>
                <system value="https://fhir.kbv.de/CodeSystem/KBV_CS_SFHIR_BAR2_ARZTNRFACHGRUPPE"/>
                <code value="01"/>
            </coding>
        </code>
    </qualification>
</Practitioner>

Organizations

Organizations are practices defined in RED as user groups. Organizations contain e.g. addresses and contact information for a practice. Organizations can be searched using a search request. Search for organizations will return a bundle including one or more FHIR items of type KBV_PR_AW_Betriebsstaette

SEARCH request for all organizations

{{baseURL}}/{{tenant}}/Organization?page=1

Data of a specific organization may be fetched using a read request including the identifier of the specific organization. A read request returns one FHIR item of type KBV_PR_AW_Betriebsstaette. A read requesrt for an organization specifies the organization by its organization ID. The organization ID may be fetched by a previous search request.

{{baseURL}}/{{tenant}}/Organization/{{OrganizationId}}

Claims

A claim represents a chargecode for statutory or private billing (Leistungsziffer EBM oder GOÄ). Claims are assigned to a patient and may be searched using a search request. If the search request contains pagination but no patient reference it will return all claims stored in RED. In order to retrieve all claims for a given person the patient ID must be added. The patient ID is either defined by the 3rd-party-system when creating a patient via POST request (see below) or must be retrieved by a previous search.

Example for a SEARCH request for all claims of a given patient

{{baseURL}}/{{tenant}}/Claim?page=1&patient=Patient/{{patientID}}

Encounters

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.

Example for a SEARCH request for all encounters of a given patient

{{baseURL}}/{{tenant}}/Encounter?page=1&subject=Patient/{{patientID}}

Diagnoses

ICD-10 patient diagnoses are represented by conditions.

Example for a SEARCH for all diagnoses for a given patient

{{baseURL}}/{{tenant}}/Condition?page=1&subject=Patient/{{patientID}}

Medication

Medication returns all pharmaceuticals prescribed or documented for a patient.

{{baseURL}}/{{tenant}}/Medication?page=1&subject=Patient/{{patientID}}

Document References

Document references are

document files that have been uploaded and stored in RED (e.g. pdf files created by a scan and uploaded in RED)
forms created in RED (e.g. Überweisung, AU etc.). All Forms will be returned as PDF files regardless of whether a printout has been created or not → Erlkönig - Formulardruck
letters created for patients - Erlkönig - Briefe

A SEARCH request for document references returns a bundle of one or more FHIR items of type DocumentReference.

Example for a SEARCH request for all documents of given patient

{{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

Get data items

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

address of the system,
RED tenant ID
type of data to fetch
identifier of the data item

> 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>

<meta>

</meta>

Using this ID the full document content can be retrieved using a second GET request.

> GET http://localhost:29221/{tenant}/DocumentReference/egMHGB0DlhuKsLzN

Create data items

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)

the patient including address and contact information
an encounter item stating the date of patient consultation
a claim containing insurance data
a document reference with file data to store for the new patient
the practitioner who has created the data, including name, address and contact information
the organization on which behalf the data is created, including address and contact information
a practitioner role joining practitioner and organization
a provenance item for EVERY data item in the bundle. Provenances specify the context of user and user group in RED. These are required, e.g. to control and limit access to the data item in RED.

> 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 Items from RED

> DELETE http://localhost:29221/{tenant}/Bundle/10000

Deletes a stored bundle in RED medical application.

Request an electronic prescription

The RED interchange API may also be used to communicate with gematik Fachdienst to retrieve stored electronic prescriptions and to send dispense requests.

Request prescription

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:

> GET http://localhost:29221/{tenant}/Task?action=$accept&prescriptionid={PrescriptionID}&accesscode={AccessCode}

Example

http://localhost:29221/{tenant}/Task?action=$accept&prescriptionid=160.000.111.065.827.98&accesscode=b8d9e513cd11cfe0a1d829b96a503e9df5b17803bbdbc4036f32858494539f28

This request returns a FHIR bundle with several items.

Composition: contains summary information and references to all items in the bundle
MedicationRequest: refers to Medication, patient, requester and insurance. Includes administrative information such as copayment, emergencyFee, substitution (aut-idem) or payer (BVG). Also contains the dosage and quantity
Medication: contains data of prescribed product (e.g. PZN ID, flag vaccine, Normgröße, form and amount)
Patient: person the prescription was created for, including insurance ID, name and address
Practitioner: physician who created and signed the prescription, including LANR, name and qualification
Organization: practice which created the prescription, including BSNR, address and contact
Coverage: payer and insurance information, including insurance status, WOP, person group, copayment status, payer identification

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.

Return a prescription

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.

> GET http://localhost:29221/{tenant}/Task?action=$reject&prescriptionid={PrescriptionID}&accesscode={AccessCode}