EHR API Nutzung: Eine Anleitung

TL;DR

EHR-APIs greifen auf Patientenakten zu, die in Systemen wie Epic, Cerner und Athenahealth gespeichert sind. Die meisten modernen EHRs unterstützen FHIR (Fast Healthcare Interoperability Resources), ein Standardformat für Gesundheitsdaten. Die Authentifizierung verwendet OAuth 2.0 mit SMART on FHIR-Erweiterungen. Verwenden Sie für Tests Apidog, um FHIR-Ressourcen zu validieren, gegen Sandboxes zu testen und sicherzustellen, dass Ihre Integration Patientendaten korrekt verarbeitet, bevor Sie eine Verbindung zu Produktionssystemen herstellen.

Einleitung

Elektronische Gesundheitsakten enthalten alles über die Patientenversorgung: Diagnosen, Medikamente, Laborergebnisse, Allergien und Behandlungspläne. Krankenhäuser, Kliniken und Gesundheitssysteme speichern diese Daten in EHR-Plattformen wie Epic, Cerner und Athenahealth.

Der Aufbau von Gesundheitsanwendungen bedeutet die Anbindung an diese Systeme. Sie können Krankenhäuser nicht bitten, CSV-Dateien zu exportieren. Sie benötigen APIs. Aber Gesundheits-APIs unterscheiden sich von typischen Web-APIs. Sie verarbeiten geschützte Gesundheitsinformationen (PHI) und müssen die Vorschriften wie HIPAA in den USA einhalten.

Die gute Nachricht: Die meisten EHR-Anbieter unterstützen jetzt FHIR, ein Standard-API-Format. Die herausfordernde Nachricht: Authentifizierung, Autorisierung und Datenmapping bleiben komplex.

Wenn Sie Gesundheitsintegrationen erstellen, hilft Ihnen Apidog, FHIR-Ressourcen zu testen, Datenstrukturen zu validieren und sicherzustellen, dass Ihre Anwendung Patientendaten korrekt verarbeitet. Sie können gegen öffentliche Sandboxes testen, bevor Sie mit realen Krankenhaussystemen arbeiten.

Testen Sie FHIR-APIs mit Apidog - kostenlos

Am Ende dieses Leitfadens werden Sie in der Lage sein:

FHIR-Ressourcentypen und -Struktur zu verstehen
Sich mit SMART on FHIR zu authentifizieren
Patientendemografie und klinische Daten abzufragen
Patientenressourcen zu erstellen und zu aktualisieren
Mit EHR-Sandboxes zu testen

FHIR verstehen

FHIR (Fast Healthcare Interoperability Resources) ist der moderne Standard für Gesundheits-APIs. Es definiert:

Ressourcen: Datentypen für Gesundheitskonzepte (Patient, Observation, Medication)
REST-API: Standardoperationen auf Ressourcen
Formate: JSON- und XML-Darstellungen

Basis-URL-Struktur

https://ehr.example.com/fhir/r4/{resource-type}/{id}

Beispiel:

GET https://ehr.example.com/fhir/r4/Patient/123

FHIR-Version

Die meisten EHRs verwenden FHIR R4 (Release 4). Einige ältere Systeme verwenden DSTU2. Dieser Leitfaden behandelt R4.

Ressourcentypen

Ressource	Zweck
Patient	Demografische und administrative Daten
Practitioner	Gesundheitsdienstleister
Organization	Krankenhäuser, Kliniken
Observation	Laborergebnisse, Vitalwerte
MedicationRequest	Verschreibungen
Condition	Diagnosen, Probleme
Encounter	Besuche, Aufnahmen
DocumentReference	Klinische Dokumente
AllergyIntolerance	Allergien und unerwünschte Reaktionen

FHIR-Ressourcenstruktur

Beispiel für Patientenressource

{
  "resourceType": "Patient",
  "id": "123",
  "active": true,
  "name": [
    {
      "use": "official",
      "family": "Smith",
      "given": ["John", "Michael"]
    }
  ],
  "gender": "male",
  "birthDate": "1985-03-15",
  "address": [
    {
      "use": "home",
      "line": ["123 Main St"],
      "city": "Boston",
      "state": "MA",
      "postalCode": "02101",
      "country": "USA"
    }
  ],
  "telecom": [
    {
      "system": "phone",
      "value": "555-123-4567",
      "use": "home"
    },
    {
      "system": "email",
      "value": "john.smith@example.com"
    }
  ],
  "identifier": [
    {
      "system": "http://hospital.example.org/mrn",
      "value": "MRN-123456"
    }
  ]
}

Beispiel für Beobachtungsressource

{
  "resourceType": "Observation",
  "id": "obs-123",
  "status": "final",
  "category": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/observation-category",
          "code": "vital-signs",
          "display": "Vital Signs"
        }
      ]
    }
  ],
  "code": {
    "coding": [
      {
        "system": "http://loinc.org",
        "code": "8480-6",
        "display": "Systolic blood pressure"
      }
    ]
  },
  "subject": {
    "reference": "Patient/123"
  },
  "effectiveDateTime": "2026-03-24T09:30:00Z",
  "valueQuantity": {
    "value": 120,
    "unit": "mmHg",
    "system": "http://unitsofmeasure.org",
    "code": "mm[Hg]"
  }
}

Authentifizierung mit SMART on FHIR

SMART on FHIR erweitert OAuth 2.0 für das Gesundheitswesen. Es verarbeitet Patientenkontext und EHR-spezifische Scopes.

OAuth-Flow für Patientenzugriff

Schritt 1: Autorisierungs-URL abrufen

GET https://ehr.example.com/fhir/r4/.well-known/smart-configuration

Antwort beinhaltet:

{
  "authorization_endpoint": "https://ehr.example.com/oauth2/authorize",
  "token_endpoint": "https://ehr.example.com/oauth2/token",
  "scopes_supported": [
    "patient/*.read",
    "patient/*.write",
    "user/*.read",
    "launch/patient"
  ]
}

Schritt 2: Benutzer zur Autorisierung umleiten

https://ehr.example.com/oauth2/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://yourapp.com/callback&
  scope=patient/*.read&
  state=random_state_value

Schritt 3: Code gegen Token austauschen

curl -X POST "https://ehr.example.com/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://yourapp.com/callback" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Antwort:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "patient/*.read",
  "patient": "123"
}

Das Feld patient liefert Ihnen den Patienten-ID-Kontext.

SMART-Scopes

Scope	Zugriff
`patient/*.read`	Alle Patientendaten lesen
`patient/Patient.read`	Nur Patientendemografie lesen
`patient/Observation.read`	Nur Beobachtungen lesen
`user/*.read`	Alle Daten für autorisierten Benutzer lesen
`launch/patient`	EHR startet Ihre App mit Patientenkontext

Patientendaten abfragen

Patientendemografie abrufen

curl -X GET "https://ehr.example.com/fhir/r4/Patient/123" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Nach Beobachtungen suchen

curl -X GET "https://ehr.example.com/fhir/r4/Observation?patient=123&category=vital-signs" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Die Antwort ist ein Bundle:

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 5,
  "entry": [
    {
      "resource": { ... Observation resource ... }
    }
  ]
}

Häufige Suchparameter

# Laborergebnisse nach Datumsbereich
GET /Observation?patient=123&category=laboratory&date=gt2026-01-01

# Spezifischer LOINC-Code
GET /Observation?patient=123&code=http://loinc.org|8480-6

# Medikamente
GET /MedicationRequest?patient=123&status=active

# Zustände (Diagnosen)
GET /Condition?patient=123&clinical-status=active

# Begegnungen
GET /Encounter?patient=123&type=AMB

Paginierung

Große Ergebnismengen werden paginiert:

GET /Observation?patient=123&_count=20

Die Antwort enthält Links:

{
  "link": [
    {
      "relation": "next",
      "url": "https://ehr.example.com/fhir/r4/Observation?patient=123&_count=20&page=2"
    }
  ]
}

Ressourcen erstellen und aktualisieren

Eine Beobachtung erstellen

curl -X POST "https://ehr.example.com/fhir/r4/Observation" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "resourceType": "Observation",
    "status": "final",
    "code": {
      "coding": [{
        "system": "http://loinc.org",
        "code": "8480-6",
        "display": "Systolic blood pressure"
      }]
    },
    "subject": {
      "reference": "Patient/123"
    },
    "effectiveDateTime": "2026-03-24T09:30:00Z",
    "valueQuantity": {
      "value": 118,
      "unit": "mmHg",
      "system": "http://unitsofmeasure.org",
      "code": "mm[Hg]"
    }
  }'

Einen Patienten aktualisieren

curl -X PUT "https://ehr.example.com/fhir/r4/Patient/123" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "resourceType": "Patient",
    "id": "123",
    "name": [{
      "family": "Smith",
      "given": ["John", "Michael"]
    }],
    "telecom": [{
      "system": "phone",
      "value": "555-999-8888",
      "use": "home"
    }]
  }'

EHR-Anbieterspezifika

Epic

Epics FHIR-API ist in den meisten großen Krankenhäusern verfügbar.

Basis-URL: https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4/
Sandbox: https://fhir.epic.com/test/api/FHIR/R4/
Dokumentation: https://fhir.epic.com

Epic erfordert eine App-Registrierung in ihrem App-Marktplatz für den Produktionszugriff.

Cerner

Cerner (Oracle Health) verwendet Standard-FHIR mit einigen Erweiterungen.

Basis-URL: https://fhir-myrecord.cerner.com/r4/{tenant-id}
Sandbox: https://fhir-deprecated.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d
Dokumentation: https://docs.oracle.com/en/health/health-cerner/

Athenahealth

Athenahealth bietet FHIR- und Legacy-APIs.

Basis-URL: https://api.platform.athenahealth.com/fhir/r4/{practice-id}
Sandbox: Verfügbar über das Entwicklerprogramm
Dokumentation: https://docs.athenahealth.com

Testen mit Apidog

Gesundheits-APIs erfordern sorgfältige Tests. Patientendaten sind sensibel.

1. Öffentliche Sandboxes nutzen

Testen Sie gegen öffentliche FHIR-Sandboxes:

# HAPI FHIR (Open Source)
https://hapi.fhir.org/baseR4

# SMART Health IT Sandbox
https://launch.smarthealthit.org

2. FHIR-Ressourcen validieren

pm.test('Resource is valid Patient', () => {
  const response = pm.response.json()
  pm.expect(response.resourceType).to.eql('Patient')
  pm.expect(response.id).to.exist
  pm.expect(response.name).to.be.an('array')
})

pm.test('Observation has required fields', () => {
  const resource = pm.response.json()
  pm.expect(resource.status).to.exist
  pm.expect(resource.code).to.exist
  pm.expect(resource.subject).to.exist
})

3. Authentifizierungs-Flow testen

SMART-Konfiguration als Umgebung speichern:

AUTHORIZATION_ENDPOINT: https://ehr.example.com/oauth2/authorize
TOKEN_ENDPOINT: https://ehr.example.com/oauth2/token
CLIENT_ID: your_client_id
CLIENT_SECRET: your_client_secret
SCOPE: patient/*.read

Testen Sie FHIR-APIs mit Apidog - kostenlos

Compliance-Aspekte

HIPAA

In den USA müssen Gesundheitsanwendungen HIPAA einhalten. Dies betrifft:

Datenübertragung: TLS 1.2+ verwenden
Datenspeicherung: Verschlüsselung im Ruhezustand
Zugriffskontrolle: Audit-Protokollierung, minimal notwendiger Zugriff
Business Associate Agreement: Erforderlich mit EHR-Anbietern

SMART on FHIR-Sicherheit

Tokens verfallen (typischerweise 1 Stunde)
Refresh-Tokens für längere Sitzungen verfügbar
Patientenkontext ist an den Token-Scope gebunden
Abmeldung erfordert Token-Widerruf

Datenminimierung

Fordern Sie nur die Scopes an, die Sie benötigen:

Gut: patient/Observation.read
Vermeiden: patient/*.read es sei denn, es ist notwendig

Häufige Fehler und Behebungen

401 Nicht autorisiert

Ursache: Token abgelaufen oder ungültig.

Behebung: Aktualisieren Sie das Token mit dem Refresh-Token aus der anfänglichen Autorisierung.

403 Verboten

Ursache: Scope beinhaltet nicht die angeforderte Ressource.

Behebung: Überprüfen Sie Ihre Scopes. Wenn Sie mehr Zugriff benötigen, fordern Sie zusätzliche Scopes während der Autorisierung an.

404 Nicht gefunden

Ursache: Patient oder Ressource existiert nicht.

Behebung: Überprüfen Sie die Ressourcen-ID. Stellen Sie sicher, dass der Patient mit dem Patientenkontext Ihres aktuellen Tokens zugänglich ist.

422 Unverarbeitbare Entität

Ursache: FHIR-Ressourcenvalidierung fehlgeschlagen.

Behebung: Überprüfen Sie erforderliche Felder und Terminologien:

{
  "resourceType": "OperationOutcome",
  "issue": [{
    "severity": "error",
    "code": "required",
    "details": {
      "text": "Observation.status is required"
    }
  }]
}

Alternativen und Vergleiche

Merkmal	Epic	Cerner	Athenahealth	OpenEMR
FHIR R4	✓	✓	✓	Teilweise
SMART on FHIR	✓	✓	✓	Nein
Sandbox-Zugriff	✓	✓	Begrenzt	Selbst gehostet
API-Dokumentation	Exzellent	Gut	Gut	Grundlegend
Marktanteil	Große Krankenhäuser	Gesundheitssysteme	Kleine Praxen	Open Source

Epic und Cerner dominieren große Gesundheitssysteme. Athenahealth bedient kleinere Praxen. OpenEMR ist Open Source, hat aber begrenzte API-Unterstützung.

Praktische Anwendungsfälle

Patientenportal. Ein Gesundheitssystem baut ein Patientenportal auf, das Daten von Epic abruft. Patienten sehen Laborergebnisse, Medikamente und anstehende Termine. Das Portal nutzt FHIR-APIs mit SMART on FHIR-Authentifizierung.

Klinische Forschung. Ein Pharmaunternehmen muss geeignete Patienten für klinische Studien identifizieren. Sie fragen FHIR-APIs über mehrere Krankenhaussysteme hinweg ab, um Patienten zu finden, die die Kriterien erfüllen, unter Beachtung des ordnungsgemäßen Einwilligungsmanagements.

Fernüberwachung. Ein Telemedizinunternehmen integriert vom Patienten gemeldete Vitalwerte in EHR-Systeme. Beobachtungen werden über die FHIR-API erstellt und sind sofort für Kliniker in Epic sichtbar.

Zusammenfassung

Das haben Sie gelernt:

FHIR ist der Standard für Gesundheits-APIs
Ressourcen repräsentieren Gesundheitskonzepte wie Patienten und Beobachtungen
SMART on FHIR handhabt OAuth mit Patientenkontext
Jeder EHR-Anbieter hat spezifische Implementierungsdetails
Vor der Produktion mit Sandboxes testen

Ihre nächsten Schritte:

Erkunden Sie die öffentliche HAPI FHIR Sandbox
Verstehen Sie FHIR-Ressourcentypen für Ihren Anwendungsfall
Registrieren Sie sich für EHR-Entwicklerprogramme
Testen Sie mit Apidog unter Verwendung von Mock-Patientendaten
Implementieren Sie HIPAA-konforme Datenverarbeitung

Testen Sie FHIR-APIs mit Apidog - kostenlos

App herunterladen

FAQ

Was ist der Unterschied zwischen FHIR und HL7 v2?HL7 v2 ist ein älterer Messaging-Standard, der in Krankenhausschnittstellen verwendet wird. FHIR ist ein moderner REST-API-Standard. Die meisten neuen Integrationen verwenden FHIR, aber HL7 v2 ist in Altsystemen immer noch verbreitet.

Benötige ich ein BAA, um EHR-APIs zu nutzen?Ja, wenn Sie PHI verarbeiten. Business Associate Agreements sind zwischen Covered Entities und Business Associates erforderlich. Wenden Sie sich an das Compliance-Team des EHR-Anbieters.

Wie erhalte ich Zugriff auf Epics FHIR-API?Registrieren Sie sich im App Orchard Marktplatz von Epic. Verwenden Sie für Sandbox-Tests deren öffentliche Sandbox. Produktionszugriff erfordert Krankenhausgenehmigung.

Was ist ein Patientenkontext?SMART on FHIR-Tokens enthalten eine Patienten-ID. Ihre API-Aufrufe sind auf die Daten dieses Patienten beschränkt. Dies stellt sicher, dass Apps nur auf Daten zugreifen können, die der Patient autorisiert hat.

Kann ich Daten in EHRs schreiben?Ja, aber mit Einschränkungen. Die meisten EHRs erlauben das Erstellen von Beobachtungen und das Aktualisieren von Patientendemografien. Das Schreiben von Diagnosen oder Medikationen erfordert in der Regel die Genehmigung durch die klinische Entscheidungsunterstützung.

Wie gehe ich mit Terminologie-Codes um?FHIR verwendet Standardterminologien:

LOINC für Labortests und Beobachtungen
SNOMED CT für klinische Konzepte
ICD-10 für Diagnosen
RxNorm für Medikationen

Verwenden Sie diese Systeme beim Erstellen von Ressourcen.

Was ist mit dem internationalen Gesundheitswesen?FHIR ist global. Jedes Land kann Implementierungsleitfäden haben. Die USA verwenden US Core-Profile. Überprüfen Sie die Spezifikationen Ihrer Region.