DEV Community

Cover image for EHR API Nutzung: Eine Anleitung
Emre Demir
Emre Demir

Posted on • Originally published at apidog.com

EHR API Nutzung: Eine Anleitung

#tutorial #testing #api

TL;DR

EHR-APIs ermöglichen den Zugriff auf Patientenakten in Systemen wie Epic, Cerner und Athenahealth. Moderne EHRs unterstützen FHIR (Fast Healthcare Interoperability Resources), ein Standardformat für Gesundheitsdaten. Die Authentifizierung erfolgt über OAuth 2.0 mit SMART on FHIR-Erweiterungen. Nutzen Sie für Entwicklung und Test Apidog, um FHIR-Ressourcen zu validieren, Sandboxes zu testen und Ihre Integration abzusichern, bevor Sie mit Produktionsdaten arbeiten.

Probiere Apidog heute aus

Einleitung

Elektronische Gesundheitsakten (EHRs) speichern alle relevanten Patientendaten: Diagnosen, Medikamente, Laborwerte, Allergien und Behandlungspläne. Anbieter wie Epic, Cerner und Athenahealth nutzen diese Systeme.

Für die Entwicklung von Gesundheitsanwendungen ist eine stabile API-Anbindung an diese Systeme unerlässlich. CSV-Exporte sind keine Option – APIs sind Standard. Gesundheits-APIs müssen jedoch den Schutz sensibler Daten (PHI) und regulatorische Vorgaben (z.B. HIPAA) gewährleisten.

Die meisten Anbieter unterstützen nun FHIR – ein standardisiertes API-Format. Herausforderungen bleiben: Authentifizierung, Autorisierung und Datenmapping.

Mit Apidog können Sie Ihre FHIR-Anbindung testen, Datenstrukturen validieren und Integrationen gegen öffentliche Sandboxes prüfen, bevor Sie mit echten Krankenhäusern arbeiten.

Am Ende dieses Guides können Sie:

  • Die FHIR-Ressourcentypen und deren Struktur verstehen
  • Authentifizieren mit SMART on FHIR
  • Patientendaten und klinische Ressourcen abfragen
  • Patientenressourcen erstellen und aktualisieren
  • Gegen EHR-Sandboxes testen

FHIR verstehen

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

  • Ressourcen: Datentypen für Gesundheitskonzepte (z.B. Patient, Observation, Medication)
  • REST-API: Standardisierte CRUD-Operationen auf Ressourcen
  • Formate: JSON und XML

Basis-URL-Struktur 

https://ehr.example.com/fhir/r4/{resource-type}/{id}
Enter fullscreen mode Exit fullscreen mode

Beispiel:

GET https://ehr.example.com/fhir/r4/Patient/123
Enter fullscreen mode Exit fullscreen mode

FHIR-Version

Die meisten Systeme nutzen FHIR R4 (Release 4). Ältere Systeme können DSTU2 verwenden. Dieser Leitfaden behandelt R4.

Ressourcentypen

Ressource Zweck
Patient Demografische/administrative Daten
Practitioner Gesundheitsdienstleister
Organization Einrichtungen (Krankenhaus, Klinik)
Observation Laborergebnisse, Vitalwerte
MedicationRequest Verschreibungen
Condition Diagnosen, Probleme
Encounter Besuche, Aufnahmen
DocumentReference Klinische Dokumente
AllergyIntolerance Allergien, unerwünschte Reaktionen

FHIR-Ressourcenstruktur

Beispiel: 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"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Beispiel: 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]"
  }
}
Enter fullscreen mode Exit fullscreen mode

Authentifizierung mit SMART on FHIR

SMART on FHIR erweitert OAuth 2.0 für den Healthcare-Bereich. Es unterstützt Patientenkontext und spezifische Scopes.

OAuth-Flow für Patientenzugriff

Schritt 1: Autorisierungs-URL abrufen

GET https://ehr.example.com/fhir/r4/.well-known/smart-configuration
Enter fullscreen mode Exit fullscreen mode

Antwort:

{
  "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"
  ]
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Schritt 3: Code gegen Token tauschen

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"
Enter fullscreen mode Exit fullscreen mode

Antwort:

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

Das Feld patient gibt die Patienten-ID für den Kontext zurück.

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 App mit Patientenkontext starten

Patientendaten abfragen

Patientendemografie abrufen 

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

Nach Beobachtungen suchen 

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

Antwort (Bundle):

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

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

# Diagnosen
GET /Condition?patient=123&clinical-status=active

# Begegnungen
GET /Encounter?patient=123&type=AMB
Enter fullscreen mode Exit fullscreen mode

Paginierung

Bei großen Ergebnismengen:

GET /Observation?patient=123&_count=20
Enter fullscreen mode Exit fullscreen mode

Antwort enthält Links zur nächsten Seite:

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

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]"
    }
  }'
Enter fullscreen mode Exit fullscreen mode

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"
    }]
  }'
Enter fullscreen mode Exit fullscreen mode

EHR-Anbieterspezifika

Epic

  • 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

App-Registrierung im Epic-Marktplatz für Produktionszugang erforderlich.

Cerner

Athenahealth

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

Testen mit Apidog

Gesundheits-APIs erfordern präzise Tests – Patientendaten sind sensibel.

FHIR Testing mit Apidog

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
Enter fullscreen mode Exit fullscreen mode

2. FHIR-Ressourcen validieren

Nutzen Sie Tests, um die Struktur zu prüfen:

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
})
Enter fullscreen mode Exit fullscreen mode

3. Authentifizierungs-Flow testen

SMART-Konfigurationsvariablen 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
Enter fullscreen mode Exit fullscreen mode

Compliance-Aspekte

HIPAA

Für US-Healthcare-Apps ist HIPAA-Compliance Pflicht:

  • Datenübertragung: Verwenden Sie TLS 1.2 oder höher
  • Datenspeicherung: Verschlüsselung (at rest)
  • Zugriffskontrolle: Audit-Logs, minimaler Zugriff
  • Business Associate Agreement (BAA): Mit EHR-Anbietern abschließen

SMART on FHIR-Sicherheit

  • Tokens laufen ab (typisch: 1 Stunde)
  • Refresh-Tokens für längere Sitzungen verwenden
  • Patientenkontext ist im Token-Scope verankert
  • Abmeldung erfordert Token-Widerruf

Datenminimierung

Fordern Sie nur notwendige Scopes an:

  • Empfohlen: patient/Observation.read
  • Vermeiden Sie patient/*.read, falls nicht erforderlich

Häufige Fehler und Behebungen

401 Nicht autorisiert

Ursache: Token abgelaufen/ungültig

Lösung: Token mit Refresh-Token aktualisieren.

403 Verboten

Ursache: Angeforderte Ressource nicht im Scope

Lösung: Scopes überprüfen und ggf. erweitern.

404 Nicht gefunden

Ursache: Patient/Ressource existiert nicht

Lösung: Ressourcen-ID kontrollieren, Patientenkontext prüfen.

422 Unverarbeitbare Entität

Ursache: FHIR-Ressourcenvalidierung fehlgeschlagen

Lösung: Pflichtfelder und Terminologien prüfen:

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

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 KHs Gesundheitssys Kleine Praxen Open Source

Epic und Cerner dominieren große Systeme. Athenahealth ist für kleinere Praxen. OpenEMR ist Open Source, aber API-Support eingeschränkt.

Praktische Anwendungsfälle

  • Patientenportal: Patienten erhalten Live-Zugriff auf Laborergebnisse, Medikamente und Termine aus Epic. FHIR-APIs und SMART on FHIR steuern Authentifizierung und Datenfluss.
  • Klinische Forschung: Pharmaunternehmen suchen gezielt Patienten für Studien. FHIR-APIs filtern geeignete Kandidaten über mehrere EHRs hinweg – stets mit Einwilligungsmanagement.
  • Fernüberwachung: Telemedizin-Anbieter übermitteln Vitaldaten direkt an EHR-Systeme. Beobachtungen werden via FHIR-API erstellt und sind für Ärzte sofort sichtbar.

Zusammenfassung

Das haben Sie gelernt:

  • FHIR ist der Standard für moderne Gesundheits-APIs
  • Ressourcen repräsentieren medizinische Konzepte (Patient, Observation, usw.)
  • SMART on FHIR ergänzt OAuth um Patientenkontext
  • Jeder EHR-Anbieter erfordert eigene Implementierungsdetails
  • Testen Sie Integrationen zuerst in Sandboxes

Nächste Schritte:

  1. Nutzen Sie die HAPI FHIR Sandbox für eigene Tests
  2. Analysieren Sie FHIR-Ressourcentypen für Ihre Anforderungen
  3. Melden Sie sich für EHR-Entwicklerprogramme an
  4. Testen Sie mit Apidog und Mock-Daten
  5. Beachten Sie HIPAA-Compliance für Datenverarbeitung

Video: API-Dokumentation mit Apidog

FAQ

Was ist der Unterschied zwischen FHIR und HL7 v2?

HL7 v2 ist ein älterer Messaging-Standard, v.a. für Schnittstellen. FHIR ist ein moderner REST-API-Standard. Neue Integrationen nutzen meist FHIR; HL7 v2 bleibt in Legacy-Systemen verbreitet.

Brauche ich ein BAA für EHR-APIs?

Ja, wenn Sie PHI verarbeiten. Ein Business Associate Agreement ist Voraussetzung – sprechen Sie mit dem Compliance-Team des EHR-Anbieters.

Wie bekomme ich Zugriff auf Epics FHIR-API?

Registrieren Sie Ihre Anwendung im Epic App Orchard. Für Sandbox-Tests nutzen Sie die öffentliche FHIR-Sandbox. Produktionszugriff erfordert Genehmigung durch das betreffende Krankenhaus.

Was ist Patientenkontext?

SMART on FHIR-Tokens enthalten eine Patienten-ID. Damit sind API-Calls auf diesen Patienten beschränkt – das schützt die Autonomie und Privatsphäre.

Kann ich Daten in EHRs schreiben?

Mit Einschränkungen: Beobachtungen und Patientendaten lassen sich meist schreiben. Für Diagnosen/Medikationen ist oft eine klinische Freigabe notwendig.

Wie gehe ich mit Terminologie-Codes um?

FHIR nutzt Standard-Terminologien:

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

Nutzen Sie diese Codes konsequent in Ihren Ressourcen.

Internationales Gesundheitswesen?

FHIR ist weltweit im Einsatz. Jedes Land kann eigene Implementierungsleitfäden haben. In den USA ist das US Core-Profil Standard. Prüfen Sie die Spezifikationen Ihrer Zielregion.

Top comments (0)