TIFlow - Kernfunktionalitäten
Version 2.0.0-ballot.1 - ci-build

Additional API: Subscription

Seiteninhalt:

Diese Seite beschreibt den Einstieg in die Subscription-Query-Schnittstelle.

Nachricht

Die Nachricht zum Registrierungsanforderungen zur Benachrichtigungen über Communications wird als HTTP GET-Anfrage an den TI-Flow-Fachdienst gesendet.

Die Nachricht zur Interaktion mit Subscription als FHIR-Ressource Subscription wird über die folgenden HTTP-Methoden ermöglicht:

Akteur HTTP-Methode Ergebnis der Anfrage
Apotheke, Kostenträger POST Registrierung an der TI-Flow-Fachdienst Webschnittstelle
Apotheke, Kostenträger GET Websocket-Verbindung zum NotificationService

Anforderungen an Schnittstelle

Resource API

Anfragen an die Subscription-Ressource können über die RESTful API mittels HTTP GET-Anfragen durchgeführt werden.

API Beschreibung

      {"resourceType":"CapabilityStatement","id":"ti-flow-fachdienst-server","meta":{"profile":["https://gematik.de/fhir/ti/StructureDefinition/ti-capability-statement"]},"text":{"status":"extensions","div":"<div xmlns=\"http://www.w3.org/1999/xhtml\"><p class=\"res-header-id\">Generated Narrative: CapabilityStatement ti-flow-fachdienst-server</p><a name=\"ti-flow-fachdienst-server\"> </a><a name=\"hcti-flow-fachdienst-server\"> </a><div style=\"display: inline-block; background-color: #d9e0e7; padding: 6px; margin: 4px; border: 1px solid #8da1b4; border-radius: 5px; line-height: 60%\"><p style=\"margin-bottom: 0px\"/><p style=\"margin-bottom: 0px\">Profile: <a href=\"https://simplifier.net/resolve?scope=de.gematik.ti@1.3.1&canonical=https://gematik.de/fhir/ti/StructureDefinition/ti-capability-statement\">Capability Statement Profil für TI FHIR Data Service</a></p></div><h2 id=\"title\">CapabilityStatement für den TI-Flow-Fachdienst</h2>
  • Implementation Guide Version: 2.0.0-ballot.1 
  • FHIR Version: 4.0.1 
  • Supported Formats: application/fhir+json, application/fhir+xml
  • Published on: 2028-04-01 
  • Published by: gematik GmbH 
<blockquote class=\"impl-note\">
Note to Implementers: FHIR Capabilities
Any FHIR capability may be 'allowed' by the system unless explicitly marked as 'SHALL NOT'. A few items are marked as MAY in the Implementation Guide to highlight their potential relevance to the use case.
</blockquote><h2 id=\"rest\">FHIR RESTful Capabilities</h2><div class=\"panel panel-default\"><div class=\"panel-heading\"><h3 id=\"mode1\" class=\"panel-title\">Mode: server</h3></div><div class=\"panel-body\"/></div><h3 id=\"resourcesCap1\">Capabilities by Resource/Profile</h3><h4 id=\"resourcesSummary1\">Summary</h4>
The summary table lists the resources that are part of this configuration, and for each resource it lists:
  • The relevant profiles (if any)
  • The interactions supported by each resource (<span class=\"bg-info\">R</span>ead, <span class=\"bg-info\">S</span>earch, <span class=\"bg-info\">U</span>pdate, and <span class=\"bg-info\">C</span>reate, are always shown, while <span class=\"bg-info\">VR</span>ead, <span class=\"bg-info\">P</span>atch, <span class=\"bg-info\">D</span>elete, <span class=\"bg-info\">H</span>istory on <span class=\"bg-info\">I</span>nstance, or <span class=\"bg-info\">H</span>istory on <span class=\"bg-info\">T</span>ype are only present if at least one of the resources has support for them.
  • The required, recommended, and some optional search parameters (if any). 
  • The linked resources enabled for _include
  • The other resources enabled for _revinclude
  • The operations on the resource (if any)
<div class=\"table-responsive\"><table class=\"table table-condensed table-hover\">Resource TypeProfile<th class=\"text-center\"><b title=\"GET a resource (read interaction)\">R</b></th><th class=\"text-center\"><b title=\"GET all set of resources of the type (search interaction)\">S</b></th><th class=\"text-center\"><b title=\"PUT a new resource version (update interaction)\">U</b></th><th class=\"text-center\"><b title=\"POST a new resource (create interaction)\">C</b></th><b title=\"Required and recommended search parameters\">Searches</b>_include_revincludeOperations<a href=\"#Device1-1\">Device</a>Supported Profiles
\u00a0\u00a0<a href=\"StructureDefinition-GEM-ERP-PR-Device.html\">GEM ERP PR Device</a><td class=\"text-center\"/><td class=\"text-center\"><span title=\"SHALL\">Y</span></td><td class=\"text-center\"/><td class=\"text-center\"/><a href=\"#AuditEvent1-2\">AuditEvent</a>Supported Profiles
\u00a0\u00a0<a href=\"StructureDefinition-audit-event-rest.html\">TI Audit Event Rest</a><td class=\"text-center\"><span title=\"SHALL\">Y</span></td><td class=\"text-center\"><span title=\"SHALL\">Y</span></td><td class=\"text-center\"/><td class=\"text-center\"/>date, entity, _sort, _count, _offset</table></div>
<div class=\"panel panel-default\"><div class=\"panel-heading\"><h4 id=\"Device1-1\" class=\"panel-title\"><span style=\"float: right;\">Resource Conformance: SHALL </span>Device</h4></div><div class=\"panel-body\"><div class=\"container\"><div class=\"row\"><div class=\"col-lg-4\"><span class=\"lead\">Core FHIR Resource</span>
<a href=\"http://hl7.org/fhir/R4/device.html\">Device</a></div><div class=\"col-lg-4\"><span class=\"lead\">Reference Policy</span>
</div><div class=\"col-lg-4\"><span class=\"lead\">Interaction summary</span>
  • SHALL support search-type.
</div></div>
<div class=\"row\"><div class=\"col-6\"><span class=\"lead\">Supported Profiles</span>
<a href=\"StructureDefinition-GEM-ERP-PR-Device.html\">GEM ERP PR Device</a>
</div></div>
</div></div></div><div class=\"panel panel-default\"><div class=\"panel-heading\"><h4 id=\"AuditEvent1-2\" class=\"panel-title\"><span style=\"float: right;\">Resource Conformance: SHALL </span>AuditEvent</h4></div><div class=\"panel-body\"><div class=\"container\"><div class=\"row\"><div class=\"col-lg-4\"><span class=\"lead\">Core FHIR Resource</span>
<a href=\"http://hl7.org/fhir/R4/auditevent.html\">AuditEvent</a></div><div class=\"col-lg-4\"><span class=\"lead\">Reference Policy</span>
</div><div class=\"col-lg-4\"><span class=\"lead\">Interaction summary</span>
  • SHALL support search-type, read.
</div></div>
<div class=\"row\"><div class=\"col-6\"><span class=\"lead\">Supported Profiles</span>
<a href=\"StructureDefinition-audit-event-rest.html\">TI Audit Event Rest</a>
</div></div>
<div class=\"row\"><div class=\"col-lg-7\"><span class=\"lead\">Search Parameters</span><table class=\"table table-condensed table-hover\">ConformanceParameterTypeDocumentationSHALL<a href=\"http://hl7.org/fhir/R4/auditevent.html#search\">date</a>date
AuditEvent.recorded - Unterstützt die Suche nach dem Aufzeichnungsdatum; default sort if _sort is not provided
\n
SHALL<a href=\"http://hl7.org/fhir/R4/auditevent.html#search\">entity</a>reference
AuditEvent.entity.what.identifier.value - Unterstützt die Suche nach betroffenen Entitäten
\n
SHALL_sortstring
Unterstützt das Sortieren nach unterstützten AuditEvent-Suchkriterien
\n
SHALL_countnumber
Maximale Anzahl zurückgegebener Einträge pro Seite; maximum value is 50
\n
SHALL_offsetnumber
Nullbasierter Offset des ersten zurückgegebenen Eintrags; default is 0
\n
</table></div><div class=\"col-lg-5\">\u00a0</div></div></div></div></div></div>"},"extension":[{"extension":[{"url":"name","valueString":"content-type"},{"url":"type","valueString":"string"},{"url":"required","valueBoolean":true},{"url":"description","valueString":"INNERER REQUEST: Content-Type des HTTP-Body"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-header"},{"extension":[{"url":"name","valueString":"authorization"},{"url":"type","valueString":"string"},{"url":"required","valueBoolean":true},{"url":"description","valueString":"INNERER REQUEST: Bearer Token zur Authentifizierung gegenüber dem TI-Flow-Fachdienst"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-header"}],"url":"https://gematik.de/fhir/tiflow/CapabilityStatement/ti-flow-fachdienst-server","version":"2.0.0-ballot.1","name":"TIFlowFachdienstServer","title":"CapabilityStatement für den TI-Flow-Fachdienst","status":"active","date":"2028-04-01","publisher":"gematik GmbH","contact":[{"name":"gematik GmbH","telecom":[{"system":"url","value":"https://gematik.de"},{"system":"email","value":"erp-umsetzung@gematik.de"}]}],"description":"CapabilityStatement für den TI-Flow-Fachdienst","jurisdiction":[{"coding":[{"system":"urn:iso:std:iso:3166","code":"DE","display":"Germany"}]}],"kind":"requirements","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":"Device","supportedProfile":["https://gematik.de/fhir/erp/StructureDefinition/GEM_ERP_PR_Device"],"_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":"400"},{"url":"description","valueString":"Invalid request"},{"url":"responseType","valueString":"TIFlowOperationOutcome"},{"url":"errorCode","valueString":"MSG_BAD_FORMAT"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"408"},{"url":"description","valueString":"Request timeout"},{"url":"responseType","valueString":"TIFlowOperationOutcome"},{"url":"errorCode","valueString":"MSG_TIMEOUT"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"500"},{"url":"description","valueString":"Internal server error"},{"url":"responseType","valueString":"TIFlowOperationOutcome"},{"url":"errorCode","valueString":"MSG_INTERNAL_ERROR"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"200"},{"url":"description","valueString":"Successful operation"}],"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":"TIFlowOperationOutcome"},{"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":"TIFlowOperationOutcome"},{"url":"errorCode","valueString":"MSG_BAD_SYNTAX"}],"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":"TIFlowOperationOutcome"},{"url":"errorCode","valueString":"MSG_UNKNOWN_TYPE"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"}],"code":"search-type"}],"versioning":"versioned-update","readHistory":true},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"type":"AuditEvent","supportedProfile":["https://gematik.de/fhir/tiflow/StructureDefinition/audit-event-rest"],"_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":"400"},{"url":"description","valueString":"Invalid request"},{"url":"responseType","valueString":"TIFlowOperationOutcome"},{"url":"errorCode","valueString":"MSG_BAD_FORMAT"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"408"},{"url":"description","valueString":"Request timeout"},{"url":"responseType","valueString":"TIFlowOperationOutcome"},{"url":"errorCode","valueString":"MSG_TIMEOUT"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"500"},{"url":"description","valueString":"Internal server error"},{"url":"responseType","valueString":"TIFlowOperationOutcome"},{"url":"errorCode","valueString":"MSG_INTERNAL_ERROR"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"200"},{"url":"description","valueString":"Successful operation"}],"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":"TIFlowOperationOutcome"},{"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":"TIFlowOperationOutcome"},{"url":"errorCode","valueString":"MSG_BAD_SYNTAX"}],"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":"TIFlowOperationOutcome"},{"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":"400"},{"url":"description","valueString":"Invalid request"},{"url":"responseType","valueString":"TIFlowOperationOutcome"},{"url":"errorCode","valueString":"MSG_BAD_FORMAT"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"408"},{"url":"description","valueString":"Request timeout"},{"url":"responseType","valueString":"TIFlowOperationOutcome"},{"url":"errorCode","valueString":"MSG_TIMEOUT"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"500"},{"url":"description","valueString":"Internal server error"},{"url":"responseType","valueString":"TIFlowOperationOutcome"},{"url":"errorCode","valueString":"MSG_INTERNAL_ERROR"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"200"},{"url":"description","valueString":"Successful operation"}],"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":"TIFlowOperationOutcome"},{"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":"TIFlowOperationOutcome"},{"url":"errorCode","valueString":"MSG_RESOURCE_ID_FAIL"}],"url":"https://gematik.de/fhir/ti/StructureDefinition/extension-http-response-info"},{"extension":[{"url":"statusCode","valueString":"410"},{"url":"description","valueString":"Resource was deleted"},{"url":"responseType","valueString":"TIFlowOperationOutcome"},{"url":"errorCode","valueString":"MSG_DELETED"}],"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":"date","definition":"http://hl7.org/fhir/SearchParameter/AuditEvent-date","type":"date","documentation":"AuditEvent.recorded - Unterstützt die Suche nach dem Aufzeichnungsdatum; default sort if _sort is not provided"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"entity","definition":"http://hl7.org/fhir/SearchParameter/AuditEvent-entity","type":"reference","documentation":"AuditEvent.entity.what.identifier.value - Unterstützt die Suche nach betroffenen Entitäten"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"_sort","type":"string","documentation":"Unterstützt das Sortieren nach unterstützten AuditEvent-Suchkriterien"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"_count","type":"number","documentation":"Maximale Anzahl zurückgegebener Einträge pro Seite; maximum value is 50"},{"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/capabilitystatement-expectation","valueCode":"SHALL"}],"name":"_offset","type":"number","documentation":"Nullbasierter Offset des ersten zurückgegebenen Eintrags; default is 0"}]}]}]}

Error processing command: Unable to find fragment resource Subscription/example-create-subscription-request pointed to in file /Users/gematik/dev/FHIR/fhir-igs-workflow/igs/core/input/pagecontent/query-api-subscription </div>

Error processing command: Unable to find fragment resource Subscription/example-create-subscription-request pointed to in file /Users/gematik/dev/FHIR/fhir-igs-workflow/igs/core/input/pagecontent/query-api-subscription </div> </div>

Error processing command: Unable to find fragment resource Subscription/example-create-subscription-response pointed to in file /Users/gematik/dev/FHIR/fhir-igs-workflow/igs/core/input/pagecontent/query-api-subscription </div>

Error processing command: Unable to find fragment resource Subscription/example-create-subscription-response pointed to in file /Users/gematik/dev/FHIR/fhir-igs-workflow/igs/core/input/pagecontent/query-api-subscription </div> </div> </div> #### Beispielhafter Ablauf ```http GET https://subscription.zentral.erp.splitdns.ti-dienste.de/subscription Authorization: Bearer secret-token-abc-123 Connection: Upgrade Pragma: no-cache Cache-Control: no-cache Upgrade: websocket Sec-WebSocket-Version: 13 Sec-WebSocket-Key: q4xkcO32u266gldTuKaSOw== ``` Der Subscription Service antwortet mit dem Upgrade ```http HTTP/1.1 101 Switching Protocols Upgrade: websocket Connection: Upgrade Sec-WebSocket-Accept: fA9dggdnMPU79lJgAE3W4TRnyDM= ``` Das Upgrade erfolgt mit einer "bind" Text-Nachricht über die Web Socket-Verbindung an den Server. `bind: ` Der Subscription Service antwortet mit einer "bound" um die Einrichtung der Subscription zu bestätigen. `bound: ` Wenn eine neue Nachricht für die Telematik-ID der Apotheke eingestellt wird, dann sendet der TI-Flow-Fachdienst eine Nachricht ping: <subscription-id>. Das AVS kann dann diese Nachricht mittels des Anwendungsfalls "Nachrichten von Versicherten empfangen" unter Nutzung des Requests GET /Communication?received=null&recipient=<Telematik-ID> abrufen. Bei Nutzung des Subscription Services kann abweichend von der Anforderung "A_21556 - PS abgebende LEI: Häufigkeit des Abrufen von Nachrichten" die Operation GET /Communication häufiger als alle 5 Minuten, d.h. nach jeder Notification, mit den obigen Parametern angefragt werden. Die Websocket-Verbindung kann bis zu 12 h bestehen. Danach muss das Clientsystem die Subscription neu registrieren. #### Hinweise - Das Signaturzertifikat muss nicht aus der Komponenten-PKI der TI abgeleitet werden. - Es wird kein fester Turnus festgelegt, in dem der Schlüssel gewechselt wird. Ein Wechsel kann über betriebliche Prozesse initiiert werden. - Der Schlüssel für die Signatur muss sicher gespeichert, jedoch nicht zwingend im HSM abgelegt werden. - Jede eingestellte Nachricht führt zu einem Ping, ggfs. im Millisekundenbereich, wenn viele Nachrichten an einen Empfänger gerichtet werden. In Abhängigkeit von der Implementierung kann dieses Verhalten zu einer Überlastung des PS führen, wenn bspw. jedes einzelne Ping den Anwendungsfall "Nachrichten von Versicherten empfangen" triggert.