EHR API'leri Nasıl Kullanılır?

ÖZET

EHR API'leri, Epic, Cerner ve Athenahealth gibi sistemlerde depolanan hasta sağlık kayıtlarına erişir. Çoğu modern EHR, sağlık verileri için standart bir format olan FHIR'ı (Hızlı Sağlık Hizmetleri Birlikte Çalışabilirlik Kaynakları) destekler. Kimlik doğrulama, SMART on FHIR uzantılarıyla OAuth 2.0 kullanır. Test için Apidog'u kullanarak FHIR kaynaklarını doğrulayın, test ortamlarına karşı test edin ve entegrasyonunuzun üretim sistemlerine bağlanmadan önce hasta verilerini doğru şekilde işlediğinden emin olun.

Giriş

Elektronik Sağlık Kayıtları, hasta bakımıyla ilgili her şeyi içerir: teşhisler, ilaçlar, laboratuvar sonuçları, alerjiler ve tedavi planları. Hastaneler, klinikler ve sağlık sistemleri bu verileri Epic, Cerner ve Athenahealth gibi EHR platformlarında saklar.

Sağlık uygulamaları geliştirmek, bu sistemlere bağlanmak anlamına gelir. Hastanelerden CSV dosyalarını dışa aktarmalarını isteyemezsiniz. API'lere ihtiyacınız var. Ancak sağlık API'leri tipik web API'lerinden farklıdır. Korunan sağlık bilgilerini (PHI) işlerler ve ABD'deki HIPAA gibi düzenlemelere uymaları gerekir.

İyi haber: Çoğu EHR sağlayıcısı artık standart bir API formatı olan FHIR'ı destekliyor. Zorlayıcı haber: Kimlik doğrulama, yetkilendirme ve veri eşleme karmaşık kalmaya devam ediyor.

Sağlık entegrasyonları geliştiriyorsanız, Apidog FHIR kaynaklarını test etmenize, veri yapılarını doğrulamanıza ve uygulamanızın hasta verilerini doğru şekilde işlediğinden emin olmanıza yardımcı olur. Gerçek hastane sistemleriyle çalışmadan önce herkese açık test ortamlarına karşı test yapabilirsiniz.

Apidog ile FHIR API'lerini test edin - ücretsiz

Bu kılavuzun sonunda şunları yapabileceksiniz:

FHIR kaynak türlerini ve yapısını anlama
FHIR üzerinde SMART ile kimlik doğrulama
Hasta demografik ve klinik verilerini sorgulama
Hasta kaynakları oluşturma ve güncelleme
EHR test ortamlarıyla test etme

FHIR'ı Anlama

FHIR (Hızlı Sağlık Hizmetleri Birlikte Çalışabilirlik Kaynakları), sağlık hizmetleri API'leri için modern standarttır. Şunları tanımlar:

Kaynaklar: Sağlık hizmetleri kavramları için veri türleri (Hasta, Gözlem, İlaç)
REST API: Kaynaklar üzerinde standart işlemler
Formatlar: JSON ve XML gösterimleri

Temel URL yapısı

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

Örnek:

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

FHIR sürümü

Çoğu EHR, FHIR R4'ü (Sürüm 4) kullanır. Bazı eski sistemler DSTU2 kullanır. Bu kılavuz R4'ü kapsar.

Kaynak türleri

Kaynak	Amaç
Patient	Demografik ve idari veriler
Practitioner	Sağlık hizmeti sağlayıcıları
Organization	Hastaneler, klinikler
Observation	Laboratuvar sonuçları, yaşamsal belirtiler
MedicationRequest	Reçeteler
Condition	Teşhisler, sorunlar
Encounter	Ziyaretler, kabuller
DocumentReference	Klinik belgeler
AllergyIntolerance	Alerjiler ve ters reaksiyonlar

FHIR kaynak yapısı

Hasta kaynağı örneği

{
  "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"
    }
  ]
}

Gözlem kaynağı örneği

{
  "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]"
  }
}

SMART on FHIR ile Kimlik Doğrulama

SMART on FHIR, sağlık hizmetleri için OAuth 2.0'ı genişletir. Hasta bağlamını ve EHR'ye özgü kapsamları yönetir.

Hasta erişimi için OAuth akışı

Adım 1: Yetkilendirme URL'sini alın

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

Yanıt şunları içerir:

{
  "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"
  ]
}

Adım 2: Kullanıcıyı yetkilendirmeye yönlendirin

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

Adım 3: Kodu belirteçle (token) değiştirin

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"

Yanıt:

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

patient alanı size hasta kimliği bağlamını verir.

SMART kapsamları

Kapsam	Erişim
`patient/*.read`	Tüm hasta verilerini oku
`patient/Patient.read`	Yalnızca hasta demografik bilgilerini oku
`patient/Observation.read`	Yalnızca gözlemleri oku
`user/*.read`	Yetkili kullanıcı için tüm verileri oku
`launch/patient`	EHR, uygulamanızı hasta bağlamıyla başlatır

Hasta verilerini sorgulama

Hasta demografik bilgilerini alın

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

Gözlemleri arayın

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

Yanıt bir "Bundle"dır:

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

Yaygın arama parametreleri

# Tarih aralığına göre laboratuvar sonuçları
GET /Observation?patient=123&category=laboratory&date=gt2026-01-01

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

# İlaçlar
GET /MedicationRequest?patient=123&status=active

# Durumlar (teşhisler)
GET /Condition?patient=123&clinical-status=active

# Karşılaşmalar
GET /Encounter?patient=123&type=AMB

Sayfalandırma

Büyük sonuç kümeleri sayfalandırılır:

GET /Observation?patient=123&_count=20

Yanıt bağlantılar içerir:

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

Kaynak oluşturma ve güncelleme

Bir gözlem oluşturun

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]"
    }
  }'

Bir hastayı güncelleyin

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 sağlayıcısına özel detaylar

Epic

Epic'in FHIR API'si çoğu büyük hastanede mevcuttur.

Temel URL: https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4/
Test Ortamı: https://fhir.epic.com/test/api/FHIR/R4/
Belgeler: https://fhir.epic.com

Epic, üretim erişimi için uygulama pazar yerlerinde uygulama kaydı gerektirir.

Cerner

Cerner (Oracle Health), bazı uzantılarla standart FHIR kullanır.

Temel URL: https://fhir-myrecord.cerner.com/r4/{tenant-id}
Test Ortamı: https://fhir-deprecated.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d
Belgeler: https://docs.oracle.com/en/health/health-cerner/

Athenahealth

Athenahealth, FHIR ve eski API'ler sağlar.

Temel URL: https://api.platform.athenahealth.com/fhir/r4/{practice-id}
Test Ortamı: Geliştirici programı aracılığıyla erişilebilir
Belgeler: https://docs.athenahealth.com

Apidog ile Test Etme

Sağlık hizmetleri API'leri dikkatli test gerektirir. Hasta verileri hassastır.

1. Herkese açık test ortamlarını kullanın

Herkese açık FHIR test ortamlarına karşı test edin:

# HAPI FHIR (açık kaynak)
https://hapi.fhir.org/baseR4

# SMART Sağlık Bilişimi test ortamı
https://launch.smarthealthit.org

2. FHIR kaynaklarını doğrulayın

pm.test('Kaynak geçerli bir Hasta', () => {
  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('Gözlemde gerekli alanlar var', () => {
  const resource = pm.response.json()
  pm.expect(resource.status).to.exist
  pm.expect(resource.code).to.exist
  pm.expect(resource.subject).to.exist
})

3. Kimlik doğrulama akışını test edin

SMART yapılandırmasını ortam olarak kaydedin:

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

Apidog ile FHIR API'lerini test edin - ücretsiz

Uyumluluk hususları

HIPAA

ABD'de, sağlık uygulamaları HIPAA'ya uymalıdır. Bu şunları etkiler:

Veri aktarımı: TLS 1.2+ kullanın
Veri depolama: Beklemedeki verileri şifreleyin
Erişim kontrolü: Denetim kaydı, gerekli minimum erişim
İş Ortağı Anlaşması (Business Associate Agreement): EHR sağlayıcılarıyla gereklidir

FHIR üzerinde SMART güvenliği

Belirteçler süresi dolar (genellikle 1 saat)
Uzatılmış oturumlar için yenileme belirteçleri mevcuttur
Hasta bağlamı belirteç kapsamına bağlıdır
Oturum kapatma, belirteç iptali gerektirir

Veri minimizasyonu

Yalnızca ihtiyacınız olan kapsamları isteyin:

İyi: patient/Observation.read
Kaçının: Gerekmedikçe patient/*.read

Yaygın hatalar ve düzeltmeler

401 Yetkisiz

Neden: Belirteç süresi dolmuş veya geçersiz.

Düzeltme: Başlangıçtaki yetkilendirmeden gelen yenileme belirtecini kullanarak belirteci yenileyin.

403 Yasak

Neden: Kapsam, istenen kaynağı içermiyor.

Düzeltme: Kapsamlarınızı kontrol edin. Daha fazla erişime ihtiyacınız varsa, yetkilendirme sırasında ek kapsamlar isteyin.

404 Bulunamadı

Neden: Hasta veya kaynak mevcut değil.

Düzeltme: Kaynak kimliğini doğrulayın. Mevcut belirtecinizin hasta bağlamı ile hastanın erişilebilir olduğundan emin olun.

422 İşlenemeyen Varlık

Neden: FHIR kaynak doğrulama başarısız oldu.

Düzeltme: Gerekli alanları ve terminolojileri kontrol edin:

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

Alternatifler ve karşılaştırmalar

Özellik	Epic	Cerner	Athenahealth	OpenEMR
FHIR R4	✓	✓	✓	Kısmi
SMART on FHIR	✓	✓	✓	Hayır
Test ortamı erişimi	✓	✓	Sınırlı	Kendi kendine barındırma
API belgeleri	Mükemmel	İyi	İyi	Temel
Pazar payı	Büyük hastaneler	Sağlık sistemleri	Küçük uygulamalar	Açık kaynak

Epic ve Cerner, büyük sağlık sistemlerine hakimdir. Athenahealth, daha küçük uygulamalara hizmet verir. OpenEMR açık kaynaklıdır ancak sınırlı API desteğine sahiptir.

Gerçek dünya kullanım örnekleri

Hasta portalı. Bir sağlık sistemi, Epic'ten veri çeken bir hasta portalı oluşturur. Hastalar laboratuvar sonuçlarını, ilaçları ve yaklaşan randevuları görüntüler. Portal, SMART on FHIR kimlik doğrulamasıyla FHIR API'lerini kullanır.

Klinik araştırma. Bir ilaç şirketi, klinik deneyler için uygun hastaları belirlemesi gerekir. Birden fazla hastane sistemindeki FHIR API'lerini sorgulayarak kriterlere uyan hastaları uygun onay yönetimi ile bulurlar.

Uzaktan izleme. Bir teletıp şirketi, hastanın bildirdiği yaşamsal belirtileri EHR sistemleriyle entegre eder. Gözlemler FHIR API aracılığıyla oluşturulur ve Epic'teki klinisyenler tarafından anında görülebilir.

Özetleme

İşte öğrendikleriniz:

FHIR, sağlık hizmetleri API'leri için standarttır
Kaynaklar, hasta ve gözlemler gibi sağlık hizmetleri kavramlarını temsil eder
SMART on FHIR, hasta bağlamıyla OAuth'u yönetir
Her EHR sağlayıcısının belirli uygulama detayları vardır
Üretimden önce test ortamlarıyla test edin

Sonraki adımlarınız:

HAPI FHIR herkese açık test ortamını keşfedin
Kullanım durumunuz için FHIR kaynak türlerini anlayın
EHR geliştirici programlarına kaydolun
Sahte hasta verilerini kullanarak Apidog ile test edin
HIPAA uyumlu veri işlemeyi uygulayın

Apidog ile FHIR API'lerini test edin - ücretsiz

Düğme

SSS

FHIR ve HL7 v2 arasındaki fark nedir?HL7 v2, hastane arayüzlerinde kullanılan eski bir mesajlaşma standardıdır. FHIR, modern bir REST API standardıdır. Çoğu yeni entegrasyon FHIR kullanır, ancak HL7 v2 eski sistemlerde hala yaygındır.

EHR API'lerini kullanmak için BAA'ya ihtiyacım var mı?Evet, PHI işliyorsanız. Kapsanan kuruluşlar ve iş ortakları arasında İş Ortağı Anlaşmaları (Business Associate Agreements) gereklidir. EHR sağlayıcısının uyumluluk ekibiyle kontrol edin.

Epic'in FHIR API'sine nasıl erişirim?Epic'in App Orchard pazar yerine kaydolun. Test ortamı testleri için herkese açık test ortamlarını kullanın. Üretim erişimi hastane onayını gerektirir.

Hasta bağlamı nedir?SMART on FHIR belirteçleri bir hasta kimliği içerir. API çağrılarınız o hastanın verileriyle sınırlıdır. Bu, uygulamaların yalnızca hastanın yetkilendirdiği verilere erişebilmesini sağlar.

EHR'lere veri yazabilir miyim?Evet, ancak sınırlamalarla. Çoğu EHR, gözlemler oluşturmaya ve hasta demografik bilgilerini güncellemeye izin verir. Teşhis veya ilaç yazmak genellikle klinik karar desteği onayını gerektirir.

Terminoloji kodlarını nasıl işlerim?FHIR standart terminolojiler kullanır:

Laboratuvar testleri ve gözlemler için LOINC
Klinik kavramlar için SNOMED CT
Teşhisler için ICD-10
İlaçlar için RxNorm

Kaynak oluştururken bu sistemleri kullanın.

Uluslararası sağlık hizmetleri ne olacak?FHIR küreseldir. Her ülkenin uygulama kılavuzları olabilir. ABD, US Core profillerini kullanır. Bölgenizin özelliklerini kontrol edin.