Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/gematik/api-ti-messenger

API specification for gematik's TI-Messenger - a messaging standard, which will enable healthcare personnel in the German healthcare sector to communicate interoperable via DSGVO-conform messaging-services. The TI-Messenger builds on matrix, the open standard for interoperable, decentralised, real-time communication over IP.
https://github.com/gematik/api-ti-messenger

api fhir gematik idp matrix oidc specification ti-messenger tim vzd

Last synced: 5 days ago
JSON representation

API specification for gematik's TI-Messenger - a messaging standard, which will enable healthcare personnel in the German healthcare sector to communicate interoperable via DSGVO-conform messaging-services. The TI-Messenger builds on matrix, the open standard for interoperable, decentralised, real-time communication over IP.

Awesome Lists containing this project

README 

        
ifdef::env-github[]

:tip-caption: :bulb:

:note-caption: :information_source:

:important-caption: :heavy_exclamation_mark:

:caution-caption: :fire:

:warning-caption: :warning:

:source-style: listing

endif::[]



ifndef::env-github[:source-style: source]



:imagesdir: ./images/

= TI Messenger Documentation v1.1.1



image::meta/gematik_logo.svg[gematik,width="70%"]



image:https://github.com/gematik/api-ti-messenger/actions/workflows/lint.yml/badge.svg[link="https://github.com/gematik/api-ti-messenger/actions/workflows/lint.yml"]

image:https://github.com/gematik/api-ti-messenger/actions/workflows/generate-images.yml/badge.svg[link="https://github.com/gematik/api-ti-messenger/actions/workflows/generate-images.yml"]



image:https://img.shields.io/badge/Release%20Notes-tim‐pro‐1.0.0-red?style=plastic&logo=github&logoColor=red[link="ReleaseNotes.md"] +

image:https://img.shields.io/badge/TI‐Messenger‐Basis-v1.1.0-green?style=plastic&logo=github&logoColor=green[link="https://gemspec.gematik.de/docs/gemSpec/gemSpec_TI-M_Basis/gemSpec_TI-M_Basis_V1.1.0/"]

image:https://img.shields.io/badge/TI‐Messenger‐ePA-v1.0.0-green?style=plastic&logo=github&logoColor=green[link="https://gemspec.gematik.de/docs/gemSpec/gemSpec_TI-M_ePA/gemSpec_TI-M_ePA_V1.0.0/"]

image:https://img.shields.io/badge/TI‐Messenger‐Pro-v1.0.0-green?style=plastic&logo=github&logoColor=green[link="https://gemspec.gematik.de/docs/gemSpec/gemSpec_TI-M_Pro/gemSpec_TI-M_Pro_V1.0.0/"] +

image:https://img.shields.io/badge/Matrix_Client_Server_API-v1.11-yellow?style=plastic&logo=github&logoColor=yellow[link="https://spec.matrix.org/v1.11/client-server-api/"] 

image:https://img.shields.io/badge/Matrix_Server_Server_API-v1.11-yellow?style=plastic&logo=github&logoColor=yellow[link="https://spec.matrix.org/v1.11/server-server-api/"] 

image:https://img.shields.io/badge/Matrix_Push_Gateway_API-v1.11-yellow?style=plastic&logo=github&logoColor=yellow[link="https://spec.matrix.org/v1.11/push-gateway-api/"] 



== Überblick

Die folgende Dokumentation ergänzt die Spezifikationen *TI-Messenger ePA* und *TI-Messenger Pro*. An dieser Stelle werden insbesondere die in der Spezifikation genannten Komponenten der Lösung sowie deren Schnittstellen weiter dargestellt und erläutert, um Hersteller und Anbieter bestmöglich zu unterstützen.



== Branches

Für die Dokumentation des *TI-Messenger-Dienstes* werden in GitHub die folgenden Branches verwendet:



- `main`: enthält die Dokumentation für das aktuell veröffentlichte Release gemäß *[gemSpec_TI-Messenger-Dienst]*,

- `develop`: enthält die Dokumentation der in Entwicklung befindlichen Features, die noch nicht released sind, 

- `hotfix`: enthält die Dokumentation kurzfristig notwendiger Änderungen am aktuellen Release, 

- `feature/*`: enthält eine Vorschau, Vorbereitungen und Diskussion eines neuen Themas, welches noch nicht in der Entwicklung ist. Die Inhalte können unvollständig sein und sich bis zur Fertigstellung noch ändern.



== Systemübersicht

Die folgende Abbildung gibt einen Überblick über die Systemarchitektur des *TI-Messenger-Dienst* v1.1.1 insbesondere auf die Schnittstellen zwischen den Komponenten, die in den folgenden Kapiteln weiter betrachtet werden. 



image::System_overview.png[width="100%"]



TIP: Auf die Schnittstellen zur Autentisierung am *Auth-Service* des *VZD-FHIR-Directory* wird in der oben gezeigten Abbildung verzichtet. Die Informationen hierzu können in dem entsprechenden Kapitel für das *VZD-FHIR-Directory* link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.2.2/docs/FHIR_VZD_HOWTO_Authenticate.adoc#fhirdirectoryauthenticationapis[hier] nachgelesen werden.



link:docs/Fachdienst/Fachdienst.adoc[*TI Messenger-Fachdienst*]



* link:docs/Fachdienst/Registrierungsdienst.adoc[*Registrierungs-Dienst*] +

Der *Registrierungs-Dienst* bietet drei abstrakte Schnittstellen an. Die Schnittstelle `I_Registration` wird vom *Frontend des Registrierungs-Dienstes* aufgerufen, um eine Organisation beim *Registrierungs-Dienst* zu authentifizieren und *Messenger-Services* zu administrieren. Die Schnittstelle `I_internVerification` wird von den *Messenger-Proxies* aufgerufen, um die Föderationsliste abzurufen und dient zusätzlich der Prüfung (der beteiligten Akteure) auf existierende VZD-FHIR-Einträge. Die Schnittstelle `I_requestToken` wird vom *Org-Admin-Client* aufgerufen, um Zugang zum *FHIR-Proxy* für die Bearbeitung von FHIR-Ressourcen zu erhalten.



* link:docs/Fachdienst/MessengerService.adoc[*Messenger-Service*] +

Ein *Messenger-Service* besteht aus den Teilkomponenten *Messenger-Proxy* und einem *Matrix-Homeserver*. Die Teilkomponente *Matrix-Homeserver* basiert auf dem offenen Kommunikationsprotokoll Matrix und bietet die `Matrix-Client-Server API` sowie die `Matrix-Server-Server API` an. Die Kommunikation zu einem *Matrix-Homeserver* wird immer über den *Messenger-Proxy* geleitet, sofern die Berechtigungsprüfung erfolgreich war. Der *Messenger-Proxy* stellt die Schnittstelle `I_TiMessengerContactManagement` bereit, um die Administration der Freigabeliste eines Akteurs zu ermöglichen. 



* https://spec.matrix.org/v1.3/push-gateway-api/[*Push-Gateway*] +

Das *Push-Gateway* stellt die `Matrix-Push-Gateway API` gemäß der Matrix Spezifikation bereit. Dieses ermöglicht die Weiterleitung von Benachrichtigungen an Akteure des *TI-Messenger-Dienstes*.



link:docs/Client/Client.adoc[*TI Messenger-Client*] +



* Der *TI-Messenger-Client* basiert auf der `Matrix-Client-Server API`. Er wird durch weitere Funktionsmerkmale erweitert und ruft die Schnittstellen am *TI-Messenger-Fachdienst* sowie am *VZD-FHIR-Directory* auf.



link:https://github.com/gematik/api-vzd/blob/main/docs/Fachkonzept_FHIR-Directory.adoc[*VZD-FHIR-Directory*] +



* Beim *VZD-FHIR-Directory* handelt es sich um einen zentralen Verzeichnisdient der TI, der die deutschlandweite Suche von Organisationen und Akteuren des *TI-Messenger-Dienstes* ermöglicht. Das *VZD-FHIR-Directory* basiert auf dem FHIR-Standard und bietet neben der Suche (`FHIRDirectorySearchAPI`) für den *TI-Messenger-Dienst* Schnittstellen zur Administration der link:docs/Foederationsliste/Foederationsliste.adoc[*Föderationsliste*] an (`FHIRDirectoryTIMProviderAPI`). Zusätzlich existiert für Organisaitonen und Practitioner eine Schnittstelle (`FHIRDirectoryOwnerAPI`), über die die Verwaltung des eigenen Eintrages im *VZD-FHIR-Directory* möglich ist. Details sind dem link:https://github.com/gematik/api-vzd/blob/gemILF_VZD_FHIR_Directory/1.2.2/docs/gemILF_VZD_FHIR_Directory.adoc[*Implementierungsleitfaden*] des *VZD-FHIR-Directory* zu entnehmen.



link:docs/IDP/idp.adoc[*Zentraler IDP-Dienst*] +



* Der *Zentrale IDP-Dienst* der gematik übernimmt die Aufgabe der smartcard-basierten Authentisierung eines Akteures. Hierbei fasst der *IDP-Dienst* aus der Smartcard notwendige Attribute (z. B. `TelematikID`, `ProfessionOID`) in ein signiertes JSON Web Token (`ID_TOKEN`) zusammen, damit sich ein Client gegenüber Fachanwendungen (*Registrierungs-Dienst* und *VZD-FHIR-Directory*) identifizieren kann. 



link:docs/Authenticator/authenticator.adoc[*gematik Authenticator*] +



* Der *Authenticator* der gematik erhält vom *zentralen IDP-Dienst* einen `AUTHORIZATION_CODE` zurück, welcher durch Vorlage vom *Registrierungs-Dienst* oder vom *Auth-Service* des *VZD-FHIR-Directory* am *IDP-Dienst* durch ein `ID_TOKEN` ausgetauscht wird.



== Ordnerstruktur

Im Folgenden sind die wesentlichen Inhalte des Repositories dargestellt.



[{source-style},subs="macros"]

----

TI-Messenger Dokumentation

├─ link:docs[docs] (weiterführende Informationen)

|   ├──── link:docs/Authenticator[Authenticator]

|   ├──── link:docs/Client[Client]

|   ├──── link:docs/Foederationsliste[Föderationsliste]

|   ├──── link:docs/Fachdienst[Fachdienst]

|   ├──── link:docs/IDP[IDP]

|   ├──── link:docs/Primaersystem[Primaersystem]

|   ├──── link:docs/anwendungsfaelle[Anwendungsfälle]

|   ├──── link:docs/anwendungsfaelle/COM-chatbot.adoc[Chatbot]

|   ├──── link:docs/Test/Test.adoc[Testkonzept]

|   └──── link:docs/FAQ[FAQ]

├─ link:images[images] (Bildarchiv)

│   └──── link:images/generated[generated] (draw.io & PlantUML gerenderte Bilder)

├─ link:samples[samples] (Codebeispiele, Postman Collections, etc)

├─ link:src[src] (Quellen)

│   ├──── link:src/images[images] (Quellen der draw.io- und PlantUML-Diagramme)

│   └──── link:src/openapi[openapi] (Schnittstellenbeschreibungen)

│        ├── link:src/openapi/TiMessengerContactManagement.yaml[TiMessengerContactManagement.yaml] (API-Beschreibung der Freigabeliste)

│        └── link:src/openapi/TiMessengerTestTreiber.yaml[TiMessengerTestTreiber.yaml] (API-Beschreibung der TestTreiber-Schnittstelle)

├── link:README.adoc[README.adoc]

├── link:CODE_OF_CONDUCT.md[CODE_OF_CONDUCT.md]

├── link:CONTRIBUTING.md[CONTRIBUTING.md]

├── link:LICENSE.md[LICENSE.md]

├── link:Pull_request_template.md[Pull_request_template.md]

├── link:SECURITY.md[SECURITY.md]

└── link:ReleaseNotes.md[ReleaseNotes.md]

----



== 💡 Onboarding

Hersteller und Anbieter eines *TI-Messenger-Dienstes* können das von der gematik im https://fachportal.gematik.de/anwendungen/ti-messenger[Fachportal] bereitgestellte Welcome Package zum Onboarding nutzen. Dieses Welcome Package ist als "Schritt-für-Schritt"-Anleitung gedacht, um Hersteller und Anbieter beim Onboarding des *TI-Messenger-Dienstes* zu unterstützen.



== Weiterführende Seiten

*Produkttypen* +

link:docs/Fachdienst/Fachdienst.adoc[- TI-Messenger-Fachdienst] +

link:docs/Client/Client.adoc[- TI-Messenger-Client] +

link:https://github.com/gematik/api-vzd/blob/main/docs/Fachkonzept_FHIR-Directory.adoc[- VZD-FHIR-Directory] +

link:docs/IDP/idp.adoc[- Zentraler IDP-Dienst] +



*Leitfaden für Primärsystemhersteller* +

link:docs/Primaersystem/Primaersystem.adoc[- Primärsystem] +



*Diverses* +

https://fachportal.gematik.de/anwendungen/ti-messenger[- TI-Messenger im gematik Fachportal]

https://fachportal.gematik.de/hersteller-anbieter/komponenten-dienste/authenticator[- Authenticator im gematik Fachportal] +

https://github.com/gematik/TI-Messenger-Testsuite[- TI-Messenger-Testsuite] +

link:docs/FAQ/FAQ.adoc[- Fragen und Antworten zur aktuellen Spezifikation [FAQ]]



*Referenz-Implementierungen* +

- [comming soon]



== Lizenzbedingungen

Copyright (c) 2023 gematik GmbH



Licensed under the Apache License, Version 2.0 (the "License");

you may not use this file except in compliance with the License.

You may obtain a copy of the License at



http://www.apache.org/licenses/LICENSE-2.0



Unless required by applicable law or agreed to in writing, software

distributed under the License is distributed on an "AS IS" BASIS,

WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

See the License for the specific language governing permissions and

limitations under the License.