Forem

Cover image for Cara Menggunakan API EHR: Panduan Lengkap
Walse
Walse

Posted on • Originally published at apidog.com

Cara Menggunakan API EHR: Panduan Lengkap

TL;DR

API EHR mengakses catatan kesehatan pasien yang disimpan di sistem seperti Epic, Cerner, dan Athenahealth. Sebagian besar EHR modern mendukung FHIR (Fast Healthcare Interoperability Resources), sebuah format standar untuk data layanan kesehatan. Autentikasi menggunakan OAuth 2.0 dengan ekstensi SMART on FHIR. Untuk pengujian, gunakan Apidog untuk memvalidasi sumber daya FHIR, menguji terhadap sandbox, dan memastikan integrasi Anda menangani data pasien dengan benar sebelum terhubung ke sistem produksi.

Coba Apidog hari ini

Pendahuluan

Rekam Medis Elektronik (Electronic Health Records) berisi segala sesuatu tentang perawatan pasien: diagnosis, obat-obatan, hasil lab, alergi, dan rencana perawatan. Rumah sakit, klinik, dan sistem kesehatan menyimpan data ini di platform EHR seperti Epic, Cerner, dan Athenahealth.

Membangun aplikasi layanan kesehatan berarti terhubung ke sistem-sistem ini. Anda tidak bisa meminta rumah sakit untuk mengekspor file CSV. Anda membutuhkan API. Namun, API layanan kesehatan berbeda dari API web pada umumnya. Mereka menangani informasi kesehatan yang dilindungi (PHI) dan harus mematuhi peraturan seperti HIPAA di AS.

Sebagian besar vendor EHR sekarang mendukung FHIR, format API standar. Namun, autentikasi, otorisasi, dan pemetaan data tetap kompleks.

Jika Anda membangun integrasi layanan kesehatan, Apidog membantu Anda menguji sumber daya FHIR, memvalidasi struktur data, dan memastikan aplikasi Anda menangani data pasien dengan benar. Anda dapat menguji terhadap sandbox publik sebelum bekerja dengan sistem rumah sakit yang sesungguhnya.

Pada akhir panduan ini, Anda akan dapat:

  • Memahami jenis dan struktur sumber daya FHIR
  • Mengautentikasi dengan SMART on FHIR
  • Melakukan kueri data demografi dan klinis pasien
  • Membuat dan memperbarui sumber daya pasien
  • Menguji dengan sandbox EHR

Memahami FHIR

FHIR (Fast Healthcare Interoperability Resources) adalah standar modern untuk API layanan kesehatan. FHIR mendefinisikan:

  • Sumber Daya (Resources): Tipe data untuk konsep layanan kesehatan (Pasien, Observasi, Obat)
  • API REST: Operasi standar pada sumber daya
  • Format: Representasi JSON dan XML

Struktur URL Dasar 

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

Contoh:

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

Versi FHIR

Sebagian besar EHR menggunakan FHIR R4 (Rilis 4). Beberapa sistem yang lebih lama menggunakan DSTU2. Panduan ini fokus pada R4.

Jenis Sumber Daya

Sumber Daya Tujuan
Patient Data demografi dan administratif
Practitioner Penyedia layanan kesehatan
Organization Rumah sakit, klinik
Observation Hasil lab, tanda vital
MedicationRequest Resep
Condition Diagnosis, masalah
Encounter Kunjungan, rawat inap
DocumentReference Dokumen klinis
AllergyIntolerance Alergi dan reaksi merugikan

Struktur sumber daya FHIR

Contoh sumber daya Pasien 

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

Contoh sumber daya Observasi 

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

Autentikasi dengan SMART on FHIR

SMART on FHIR memperluas OAuth 2.0 untuk layanan kesehatan. Prosesnya:

Alur OAuth untuk akses pasien

Langkah 1: Dapatkan URL otorisasi

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

Respons:

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

Langkah 2: Alihkan pengguna untuk otorisasi

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

Langkah 3: Tukar kode dengan token

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

Respons:

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

patient memberikan konteks ID pasien.

Cakupan SMART

Cakupan Akses
patient/*.read Membaca semua data pasien
patient/Patient.read Hanya membaca data demografi pasien
patient/Observation.read Hanya membaca observasi
user/*.read Membaca semua data untuk pengguna yang diotorisasi
launch/patient EHR meluncurkan aplikasi Anda dengan konteks pasien

Mengkueri data pasien

Dapatkan demografi pasien 

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

Cari observasi 

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

Respons adalah Bundle:

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

Parameter pencarian umum 

# Hasil lab berdasarkan rentang tanggal
GET /Observation?patient=123&category=laboratory&date=gt2026-01-01

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

# Obat-obatan
GET /MedicationRequest?patient=123&status=active

# Kondisi (diagnosis)
GET /Condition?patient=123&clinical-status=active

# Encounter (Kunjungan)
GET /Encounter?patient=123&type=AMB
Enter fullscreen mode Exit fullscreen mode

Paginasi

Untuk set hasil besar, gunakan paginasi:

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

Respons menyertakan tautan:

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

Membuat dan memperbarui sumber daya

Buat observasi 

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

Perbarui pasien 

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

Spesifik vendor EHR

Epic

  • Base URL: https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4/
  • Sandbox: https://fhir.epic.com/test/api/FHIR/R4/
  • Dokumentasi: https://fhir.epic.com

Pendaftaran aplikasi di marketplace Epic diperlukan untuk akses produksi.

Cerner

Athenahealth

  • Base URL: https://api.platform.athenahealth.com/fhir/r4/{practice-id}
  • Sandbox: Tersedia melalui program pengembang
  • Dokumentasi: https://docs.athenahealth.com

Pengujian dengan Apidog

API layanan kesehatan memerlukan pengujian yang cermat. Data pasien sangat sensitif.

Apidog FHIR Test

1. Gunakan sandbox publik

Uji terhadap sandbox FHIR publik:

# HAPI FHIR (open source)
https://hapi.fhir.org/baseR4

# SMART Health IT sandbox
https://launch.smarthealthit.org
Enter fullscreen mode Exit fullscreen mode

2. Validasi sumber daya FHIR 

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. Uji alur autentikasi

Simpan konfigurasi SMART sebagai environment:

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

Pertimbangan Kepatuhan

HIPAA

Di AS, aplikasi layanan kesehatan harus mematuhi HIPAA. Perhatikan:

  • Transmisi Data: Gunakan TLS 1.2+
  • Penyimpanan Data: Enkripsi saat tidak aktif
  • Kontrol Akses: Audit log, akses minimum yang diperlukan
  • Business Associate Agreement (BAA): Diperlukan dengan vendor EHR

Keamanan SMART on FHIR

  • Token kadaluarsa (umumnya 1 jam)
  • Token refresh tersedia untuk sesi panjang
  • Konteks pasien terikat pada scope token
  • Logout membutuhkan pencabutan token

Minimalisasi data

Minta hanya scope yang diperlukan:

  • Baik: patient/Observation.read
  • Hindari: patient/*.read kecuali benar-benar diperlukan

Kesalahan umum dan perbaikan

401 Tidak Sah (Unauthorized)

Penyebab: Token kedaluwarsa atau tidak valid.

Perbaikan: Refresh token menggunakan refresh token dari otorisasi awal.

403 Terlarang (Forbidden)

Penyebab: Scope tidak menyertakan resource yang diminta.

Perbaikan: Periksa scope. Jika perlu akses lebih, minta scope tambahan saat otorisasi.

404 Tidak Ditemukan (Not Found)

Penyebab: Pasien atau resource tidak ada.

Perbaikan: Verifikasi ID resource. Pastikan konteks pasien pada token Anda sudah benar.

422 Entitas Tidak Dapat Diproses (Unprocessable Entity)

Penyebab: Validasi resource FHIR gagal.

Perbaikan: Cek field wajib dan terminologi:

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

Alternatif dan perbandingan

Fitur Epic Cerner Athenahealth OpenEMR
FHIR R4 ✓ ✓ ✓ Parsial
SMART on FHIR ✓ ✓ ✓ Tidak
Akses Sandbox ✓ ✓ Terbatas Self-host
Dokumentasi API Sangat Baik Baik Baik Dasar
Pangsa pasar RS besar Sistem kesehatan Praktik kecil Open source

Epic dan Cerner mendominasi sistem layanan kesehatan besar. Athenahealth melayani praktik yang lebih kecil. OpenEMR adalah open source namun dukungan API terbatas.

Kasus penggunaan dunia nyata

Portal pasien: Sistem kesehatan membangun portal pasien yang menarik data dari Epic menggunakan API FHIR dan autentikasi SMART on FHIR. Pasien dapat melihat hasil lab, obat, dan janji temu.

Penelitian klinis: Perusahaan farmasi mengkueri API FHIR di berbagai rumah sakit untuk menemukan pasien yang cocok untuk uji klinis, dengan persetujuan yang sesuai.

Pemantauan jarak jauh: Perusahaan telehealth mengintegrasikan tanda vital pasien ke EHR. Observasi dibuat via API FHIR dan langsung terlihat oleh klinisi di Epic.

Penutup

Yang sudah Anda pelajari:

  • FHIR adalah standar API layanan kesehatan
  • Resource merepresentasikan konsep layanan kesehatan (pasien, observasi, dll)
  • SMART on FHIR menangani OAuth dengan konteks pasien
  • Setiap vendor EHR punya detail implementasi spesifik
  • Uji di sandbox sebelum ke produksi

Langkah berikutnya:

  1. Jelajahi sandbox publik HAPI FHIR
  2. Pahami jenis resource FHIR yang relevan untuk kasus Anda
  3. Daftar ke program developer EHR
  4. Uji dengan Apidog menggunakan data pasien tiruan
  5. Terapkan penanganan data sesuai HIPAA

FAQ

Apa perbedaan antara FHIR dan HL7 v2?

HL7 v2 adalah standar pesan lama yang digunakan untuk antarmuka rumah sakit. FHIR adalah standar API REST modern. Sebagian besar integrasi baru memakai FHIR, namun HL7 v2 masih banyak digunakan di sistem lama.

Apakah saya memerlukan BAA untuk menggunakan API EHR?

Ya, jika Anda menangani PHI. Business Associate Agreement (BAA) diperlukan antara entitas tertanggung dan partner. Cek dengan tim compliance vendor EHR.

Bagaimana cara mendapatkan akses ke API FHIR Epic?

Daftar di marketplace App Orchard Epic. Untuk pengujian, gunakan sandbox publik Epic. Akses produksi perlu persetujuan rumah sakit.

Apa itu konteks pasien?

Token SMART on FHIR menyertakan ID pasien. Panggilan API Anda hanya bisa mengakses data pasien tersebut, sesuai otorisasi.

Bisakah saya menulis data ke EHR?

Bisa, dengan batasan. EHR umumnya mengizinkan pembuatan observasi dan update demografi pasien. Menulis diagnosis atau resep biasanya butuh persetujuan tambahan.

Bagaimana cara menangani kode terminologi?

FHIR memakai terminologi standar:

  • LOINC untuk tes lab/observasi
  • SNOMED CT untuk konsep klinis
  • ICD-10 untuk diagnosis
  • RxNorm untuk obat

Gunakan sistem tersebut saat membuat resource.

Bagaimana dengan layanan kesehatan internasional?

FHIR bersifat global. Setiap negara bisa punya panduan implementasi. AS memakai US Core. Cek spesifikasi wilayah Anda.

Top comments (0)