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).
| Weg | Ausgelieferte 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.
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 WertX-Organization-IDund 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:
| Interaktion | Anfrage |
|---|---|
| Erstellen | POST /fhir/{type} |
| Lesen | GET /fhir/{type}/{id} |
| Aktualisieren | PUT /fhir/{type}/{id} |
| Löschen | DELETE /fhir/{type}/{id} |
| Suchen | GET /fhir/{type}?... |
| Verlauf, Version gelesen | GET /fhir/{type}/{id}/_history, .../_history/{vid} |
| Transaktion oder Stapel | POST /fhir mit einer Bundle vom Typ transaction oder batch |
| Fähigkeitsbeschreibung | GET /fhir/metadata (auch unter /R4, /R5) |
| Bestätigen | POST /fhir/{type}/$validate, POST /fhir/$validate (Bündel), GET /fhir/$validate-profiles |
| Unterstützte Versionen | GET /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.
Suchen
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.
| Parameter | Verhalten |
|---|---|
_count | Seitengröße. Standardmäßig 20, maximal 1000 |
_offset | Diese Anzahl an Ergebnissen wird übersprungen; es werden next Links generiert. |
_sort | Unterstützt (Präfix - für absteigend) |
_id | Filter. Listen mit mehr als 1000 IDs werden abgelehnt. |
_lastUpdated, _content | Filter |
_include | Unterstützt. Die enthaltenen Ressourcen werden innerhalb desselben Organisationsbereichs gelesen. |
_revinclude | Unterstü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, _contained | Nicht implementiert. Sie werden ignoriert, daher erhalten Sie weniger Ergebnisse als ein vollständiger FHIR-Server liefern würde, niemals mehr. |
_summary, _total, _format, _pretty | Als 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.
-
Starten Sie den Export. Der Header
Prefermuss exaktrespond-asyncsein (der Server vergleicht den gesamten Wert, daher werden zusätzliche Token wierespond-async, return=minimalabgelehnt); andernfalls gibt der Server den Fehlercode 400 (Prefer header must be 'respond-async' for bulk data export) zurück.Acceptmussapplication/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 Acceptedmit einemContent-LocationHeader, der die Status-URL enthält. -
Die Status-URL (
GET /fhir/bulkdata/status/{id}) wird regelmäßig überprüft. Sie gibt202mitX-Progresszurück, solange der Auftrag aussteht oder ausgeführt wird, und200mit einem Manifest, sobald er abgeschlossen ist. Ein fehlgeschlagener Auftrag gibt 500 mitExport failed: ...zurück. -
Laden Sie jede Datei in der Liste
outputdes Manifests ({type, url, count}) mitGET /fhir/bulkdata/download/{exportId}/{Type}.ndjsonherunter. Für den Download wird auch der Organisationsheader benötigt. -
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.
| Option | Verhalten |
|---|---|
| Endpunkte | GET /fhir/$export (Systemebene) und GET /fhir/Patient/$export (Patientenebene) |
_type | Kommagetrennte Ressourcentypen |
_since | RFC-3339-Zeitstempel, angewendet als _lastUpdated >= value. Ein ungültiger Wert gibt 400 Invalid _since parameter zurück. |
Nr _type | Alle 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.
| Standard | Status |
|---|---|
| HL7 v2-Analyse, ADT A01/A03/A08, ORU^R01, ORA^R41 | GA |
| HL7 v2 ORM, SIU, VXU, BAR, Apotheke | GA |
| MLLP-Zuhörer und Klient | GA |
| HL7 v2 zu FHIR-Transformation | GA. 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 Fehlern | GA |
| FHIR R4 Strukturvalidierung | GA |
| FHIR R4 Touchstone-Zertifizierung | GA |
| 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üche | GA |
| X12 835, 270/271, 276/277, 278, 834, 820 | GA |
| IHE PCD (Gerätedaten) | GA |
| IHE XDS.b und MHD (CDA-zu-MHD-Brücke) | GA |
| IHE ATNA-Audit | GA |
| IHE PIXm, PDQm | GA |
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,_containedoder_revinclude:iterate. - Beim Massenexport ist nur
GETmöglich, als einzige Filter stehen_typeund_sincezur Verfügung. - Der eigenständige Header
If-None-Existwird bei Ressourcenendpunkten nicht verarbeitet; verwenden Sie Bundle-Einträge.If-Matchwird nur beiPUTverarbeitet. - Im Code wurde keine IPS-Generierung (International Patient Summary) gefunden.
Häufige Fehler
| Antwort | Ursache | Fix |
|---|---|---|
400 Prefer header must be 'respond-async'... | Fehlende Prefer bei $export | Füge Prefer: respond-async hinzu |
400 Accept header must include 'application/fhir+ndjson' | Falsche Accept auf $export | Verwenden Sie application/fhir+ndjson oder */* |
401 Missing X-Organization-ID header | Aufruf des Dienstes ohne Gateway | Gehe durch /api/v1/fhir oder sende den Header |
| 404 "... ist kein Ressourcentyp in FHIR R4; FHIR R5 definiert ihn." | Falsche Version des Endpunkts | Verwenden Sie den in der Nachricht genannten Endpunkt. |
| 406 | Nicht unterstützt oder widersprüchlich fhirVersion | Verwenden Sie 4.0 oder 5.0, entsprechend dem Pfad |
Etwas unklar? Senden Sie Feedback zur Dokumentation per E-Mail..