Zum Hauptinhalt springen

FHIR & Interoperabilität

Tietai speichert klinische Daten auf einem eigenen FHIR-Server (tietai-fhir-service). Diese Seite beschreibt die Funktionsweise dieses Servers, seine Aufrufweise und den Stand der Implementierung der anderen Standards (HL7 v2, DICOM, X12, IHE).

FHIR-Versionen​

Der Server liefert Daten FHIR R4 (4.0.1) und FHIR R5 (5.0.0) aus einem Datensatz. Ein Client an einem der beiden Endpunkte sieht alle Daten der Organisation. Ressourcen, die in der jeweils anderen Version geschrieben wurden, werden beim Lesen konvertiert (Einstellung components.fhir.cross_version_read ist standardmäßig aktiviert; deaktiviert, sieht jede Version nur ihre eigene).

Ein Datensatz, zwei FHIR-Versionen

WegAusgelieferte Version
/fhir/...Die konfigurierte Standardeinstellung ist: R4, sofern nicht anders angegeben FHIR_DEFAULT_VERSION).
/fhir/R4/...Immer R4
/fhir/R5/...Immer R5

Auf dem nicht versionierten Pfad /fhir kann die Version mit dem Medientypparameter fhirVersion in Zeile Accept oder Content-Type ausgewählt werden. Es werden 4.0 oder 5.0 akzeptiert (nicht 4.0.1). Die Angabe einer vom Server nicht implementierten Version (R4B, STU3, R6) führt zu einer 406-Fehlermeldung 406. OperationOutcome. Die Angabe einer anderen Version als im Pfad (z. B. fhirVersion=5.0 in Zeile /fhir/R4) führt ebenfalls zu einem 406-Fehler. Jede Antwort gibt ihre Version in Content-Type, z. B. application/fhir+json; fhirVersion=5.0.

Das Lesen eines Ressourcentyps, der nur zur anderen Version gehört, gibt 404 mit einer OperationOutcome zurück, die den zugehörigen Endpunkt angibt. R5 DeviceUsage und R4 DeviceUseStatement werden als derselbe Datensatz behandelt, ebenso wie RequestOrchestration und RequestGroup.

Bei der Konvertierung werden Daten niemals stillschweigend verworfen. Ein Element, das die Zielversion nicht darstellen kann, wird in einer Erweiterung mit der URL http://tiet.ai/fhir/StructureDefinition/unconverted-element beibehalten.

hinweis

Das Connect HL7-Gateway ist ein anderes Produkt. In seiner Leistungsmatrix wird FHIR R5 als „Nicht verfügbar“ aufgeführt und nur FHIR R4 beschrieben. Diese Seite beschreibt den FHIR-Server.

Aufruf der API​

Basispfad und Authentifizierung​

Über das API-Gateway wird der FHIR-Server unter /api/v1/fhir/ eingebunden. Das Gateway ordnet Port /api/v1/fhir/<resource> der Route /fhir/<resource> des Servers zu. Der Host der Entwicklungsumgebung ist https://api-hip-dev.tiet.ai.

  • Senden Sie Ihr Zugriffstoken als Authorization: Bearer <token>.
  • Das Gateway setzt den Wert Ihres Tokens auf X-Organization-ID, daher müssen Sie ihn nicht selbst senden. Wenn Sie den FHIR-Dienst direkt aufrufen (innerhalb des Clusters oder auf dessen VM), müssen Sie den Wert X-Organization-ID und eine Gateway-Assertion senden. Eine Diskrepanz zwischen Header und bestätigter Organisation wird abgelehnt.
  • Im URL-Pfad ist keine Organisations-ID enthalten.
BASE=https://api-hip-dev.tiet.ai/api/v1/fhir
TOKEN=<your access token>

# What versions does the server speak?
curl -H "Authorization: Bearer $TOKEN" "$BASE/\$versions"

Erwartete Antwort:

{
"resourceType": "Parameters",
"parameter": [
{ "name": "version", "valueString": "4.0" },
{ "name": "version", "valueString": "5.0" },
{ "name": "default", "valueString": "4.0" }
]
}
# Capability statement, one per version
curl -H "Authorization: Bearer $TOKEN" "$BASE/R5/metadata"

# Create, read, search
curl -X POST "$BASE/R4/Patient" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/fhir+json" \
-d '{"resourceType":"Patient","name":[{"family":"Patient","given":["Test"]}],"gender":"female","birthDate":"1980-01-01"}'

curl -H "Authorization: Bearer $TOKEN" "$BASE/R4/Patient/<id>"
curl -H "Authorization: Bearer $TOKEN" "$BASE/R4/Patient?name:contains=Test&_count=10"

# Read the same patient as R5
curl -H "Authorization: Bearer $TOKEN" -H "Accept: application/fhir+json; fhirVersion=5.0" "$BASE/Patient/<id>"

Wechselwirkungen​

Für jeden Ressourcentyp in der Versionsregistrierung stellt der Server Folgendes bereit:

InteraktionAnfrage
ErstellenPOST /fhir/{type}
LesenGET /fhir/{type}/{id}
AktualisierenPUT /fhir/{type}/{id}
LöschenDELETE /fhir/{type}/{id}
SuchenGET /fhir/{type}?...
Verlauf, Version gelesenGET /fhir/{type}/{id}/_history, .../_history/{vid}
Transaktion oder StapelPOST /fhir mit einer Bundle vom Typ transaction oder batch
FähigkeitsbeschreibungGET /fhir/metadata (auch unter /R4, /R5)
BestätigenPOST /fhir/{type}/$validate, POST /fhir/$validate (Bündel), GET /fhir/$validate-profiles
Unterstützte VersionenGET /fhir/$versions

Ein transaction Bundle ist ein Alles-oder-Nichts-Bundle. Ein batch Bundle führt jeden Eintrag einzeln aus und gibt pro Eintrag eine Antwort zurück. Bedingte Erstellung ist innerhalb von Bundles über die request.ifNoneExist Suchabfrage des Eintrags möglich, und request.ifMatch enthält eine Versions-ID. Der eigenständige If-None-Exist Header wird von den Ressourcenendpunkten nicht verarbeitet. PUT berücksichtigt If-Match (W/"<version>" oder *): Eine veraltete Version gibt den Fehlercode 412 zurück.

Ein Endpunkt POST /$sql ist zwar vorhanden, aber nur dann aktiv, wenn er FHIR_SQL_ENDPOINT_ENABLED=true (components.fhir.sql_endpoint_enabled) aufweist, da er keine Mandantenisolierung besitzt. In einer gemeinsam genutzten Umgebung ist er nicht zu erwarten.

Suchparameter werden pro Ressourcentyp definiert. Die Modifikatoren :exact und :contains gelten für Zeichenkettenparameter, und Datumsparameter akzeptieren die Präfixe eq, ne, gt, lt, ge, le, sa, eb, ap.

ParameterVerhalten
_countSeitengröße. Standardmäßig 20, maximal 1000
_offsetDiese Anzahl an Ergebnissen wird übersprungen; es werden next Links generiert.
_sortUnterstützt (Präfix - für absteigend)
_idFilter. Listen mit mehr als 1000 IDs werden abgelehnt.
_lastUpdated, _contentFilter
_includeUnterstützt. Die enthaltenen Ressourcen werden innerhalb desselben Organisationsbereichs gelesen.
_revincludeUnterstützt wird der Wert _revinclude=Target:param (z. B. Observation:subject bei einer Patientensuche), jedoch nur für Referenzparameter, die den gesuchten Typ als Ziel angeben. Eine Suche fügt maximal 1000 Ressourcen hinzu (components.fhir.revinclude_max, Umgebungsvariable FHIR_REVINCLUDE_MAX), und die Antwort gibt an, wann sie abgeschnitten wurde. Werte :iterate sowie unbekannte oder fehlerhafte Werte werden mit einer Warnung ignoriert.
_elements, _containedNicht implementiert. Sie werden ignoriert, daher erhalten Sie weniger Ergebnisse als ein vollständiger FHIR-Server liefern würde, niemals mehr.
_summary, _total, _format, _prettyAls Ergebnis akzeptierte Kontrollen

Ein nicht erkannter Suchparameter führt zu einem Fehler, anstatt ignoriert zu werden; ein Tippfehler kann die Suche also nicht erweitern.

Massenexport​

Der Server implementiert den asynchronen Massenexport. Der Kick-off-Wert ist immer GET.

Massenexportsequenz

  1. Starten Sie den Export. Der Header Prefer muss exakt respond-async sein (der Server vergleicht den gesamten Wert, daher werden zusätzliche Token wie respond-async, return=minimal abgelehnt); andernfalls gibt der Server den Fehlercode 400 (Prefer header must be 'respond-async' for bulk data export) zurück. Accept muss application/fhir+ndjson, */* oder nicht vorhanden sein.

    curl -i "$BASE/\$export?_type=Patient,Condition&_since=2026-01-01T00:00:00Z" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Prefer: respond-async" -H "Accept: application/fhir+ndjson"

    Die Antwort ist 202 Accepted mit einem Content-Location Header, der die Status-URL enthält.

  2. Die Status-URL (GET /fhir/bulkdata/status/{id}) wird regelmäßig überprüft. Sie gibt 202 mit X-Progress zurück, solange der Auftrag aussteht oder ausgeführt wird, und 200 mit einem Manifest, sobald er abgeschlossen ist. Ein fehlgeschlagener Auftrag gibt 500 mit Export failed: ... zurück.

  3. Laden Sie jede Datei in der Liste output des Manifests ({type, url, count}) mit GET /fhir/bulkdata/download/{exportId}/{Type}.ndjson herunter. Für den Download wird auch der Organisationsheader benötigt.

  4. Optional DELETE /fhir/bulkdata/status/{id}. Es wird der Statuscode 202 zurückgegeben und die Dateien eines abgeschlossenen Exports werden entfernt; der Export einer anderen Organisation gibt den Statuscode 403 zurück.

OptionVerhalten
EndpunkteGET /fhir/$export (Systemebene) und GET /fhir/Patient/$export (Patientenebene)
_typeKommagetrennte Ressourcentypen
_sinceRFC-3339-Zeitstempel, angewendet als _lastUpdated >= value. Ein ungültiger Wert gibt 400 Invalid _since parameter zurück.
Nr _typeAlle Ressourcentypen, die Daten für Ihre Organisation enthalten. Der Export auf Patientenebene ist auf die Patientenkompartimenttypen beschränkt.
Im Code nicht gefunden_typeFilter, _outputFormat, Gruppenexport

Typen ohne passende Ressourcen erzeugen keine Datei. Die Dateien werden in das Exportverzeichnis des Servers geschrieben (components.fhir.bulk_export.output_dir, Standardwert /tmp/fhir-bulkdata; der Export kann mit BULK_EXPORT_ENABLED=false deaktiviert werden).

Im Produkt​

In der Web-App hat Tiet · Govern → FHIR Server vier Einträge: Explorer, Editor, Patients und Server Informationen zu den Patientenansichten finden Sie unter Patienten verwalten.

  • Explorer durchsucht Ressourcen nach Typ und zeigt eine Ressource als gerendert, JSON, Referenzen oder Verlauf an. Ressourcen verfügen außerdem über eine Suchansicht, eine Validierungsansicht und eine Referenzansicht im selben Bereich.
  • Editor erstellt und aktualisiert Ressourcen aus Vorlagen, einem Formular (für unterstützte Typen) oder JSON.
  • Server hat drei Registerkarten: Server (die Capability-Anweisung, strukturiertes oder rohes JSON), Bulk Data (Import und Export; Export enthält Ressourcentyp, Geändert seit, Start Bulk Export und Check Status) und Bundles.

Der Massendatenexport beginnt mit einer Systemebene $export für einen Ressourcentyp aus der Dropdown-Liste. Der Import verwendet eingefügtes oder hochgeladenes JSON oder NDJSON und erstellt jede Ressource einzeln mit einer Erstellungsanforderung.

Andere Standards rund um FHIR​

Diese Interoperabilitätsfunktionen erstrecken sich über Tiet · Connect und Workflow-Knoten. Die Tabelle enthält die unter „Funktionsstatus“ zusammengefassten Aktualisierungen der Standardverfügbarkeit. X12 GA deckt Parsing- und Workflow-Knoten ab; vereinbaren Sie einen Datei- oder API-Transport mit dem Quellsystem, da kein dedizierter X12 Connect-Konnektor verfügbar ist. Die Beschränkungen des FHIR-Servers werden weiter unten beschrieben.

StandardStatus
HL7 v2-Analyse, ADT A01/A03/A08, ORU^R01, ORA^R41GA
HL7 v2 ORM, SIU, VXU, BAR, ApothekeGA
MLLP-Zuhörer und KlientGA
HL7 v2 zu FHIR-TransformationGA. Der Knoten hl7-to-fhir ordnet ADT (Patient, Encounter), ORM/OMG (Patient, ServiceRequest) und ORU (Observation, DiagnosticReport) zu. Andere Typen verwenden einen Best-Effort-PID/OBX-Fallback.
FHIR R4 JavaScript-Transformationen, CapabilityStatement, OperationOutcome bei FehlernGA
FHIR R4 StrukturvalidierungGA
FHIR R4 Touchstone-ZertifizierungGA
DICOMweb (QIDO-RS, WADO-RS, STOW-RS)GA. Der DICOM-Dienst proximiert ausschließlich QIDO-RS und WADO-RS.
DICOM C-STORE, C-FIND, C-MOVE, C-ECHO (DIMSE)GA
X12 837 AnsprücheGA
X12 835, 270/271, 276/277, 278, 834, 820GA
IHE PCD (Gerätedaten)GA
IHE XDS.b und MHD (CDA-zu-MHD-Brücke)GA
IHE ATNA-AuditGA
IHE PIXm, PDQmGA

Im FHIR-Server selbst ist die IHE-Unterstützung auf die Validierung von MHD-ITI-65-Dokumentbündeln (nur wenn das Bündel das MHD-Profil deklariert) und eine PDQm-Ergebnisbeschränkung beschränkt. Es gibt keine MHD-Such- oder Abrufoperationen und keine PIXm- oder PDQm-Endpunkte.

Grenzen​

  • Nr. _elements, _contained oder _revinclude:iterate.
  • Beim Massenexport ist nur GET möglich, als einzige Filter stehen _type und _since zur Verfügung.
  • Der eigenständige Header If-None-Exist wird bei Ressourcenendpunkten nicht verarbeitet; verwenden Sie Bundle-Einträge. If-Match wird nur bei PUT verarbeitet.
  • Im Code wurde keine IPS-Generierung (International Patient Summary) gefunden.

Häufige Fehler​

AntwortUrsacheFix
400 Prefer header must be 'respond-async'...Fehlende Prefer bei $exportFüge Prefer: respond-async hinzu
400 Accept header must include 'application/fhir+ndjson'Falsche Accept auf $exportVerwenden Sie application/fhir+ndjson oder */*
401 Missing X-Organization-ID headerAufruf des Dienstes ohne GatewayGehe durch /api/v1/fhir oder sende den Header
404 "... ist kein Ressourcentyp in FHIR R4; FHIR R5 definiert ihn."Falsche Version des EndpunktsVerwenden Sie den in der Nachricht genannten Endpunkt.
406Nicht unterstützt oder widersprüchlich fhirVersionVerwenden Sie 4.0 oder 5.0, entsprechend dem Pfad

Etwas unklar? Senden Sie Feedback zur Dokumentation per E-Mail..