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.

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.

Kabar baiknya: sebagian besar vendor EHR sekarang mendukung FHIR, format API standar. Kabar menantangnya: 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.

Uji API FHIR dengan Apidog - gratis

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. Ini 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}

Contoh:

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

Versi FHIR

Sebagian besar EHR menggunakan FHIR R4 (Rilis 4). Beberapa sistem yang lebih lama menggunakan DSTU2. Panduan ini mencakup 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"
    }
  ]
}

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

Autentikasi dengan SMART on FHIR

SMART on FHIR memperluas OAuth 2.0 untuk layanan kesehatan. Ini menangani konteks pasien dan cakupan khusus EHR.

Alur OAuth untuk akses pasien

Langkah 1: Dapatkan URL otorisasi

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

Respons mencakup:

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

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

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"

Respons:

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

Bidang patient memberikan Anda 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"

Cari observasi

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

Respons adalah Bundle:

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

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

Paginasi

Set hasil yang besar menggunakan paginasi:

GET /Observation?patient=123&_count=20

Respons mencakup tautan:

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

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

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

Spesifik vendor EHR

Epic

API FHIR Epic tersedia di sebagian besar rumah sakit besar.

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

Epic mewajibkan pendaftaran aplikasi di marketplace aplikasi mereka untuk akses produksi.

Cerner

Cerner (Oracle Health) menggunakan FHIR standar dengan beberapa ekstensi.

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

Athenahealth

Athenahealth menyediakan FHIR dan API lama.

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

Pengujian dengan Apidog

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

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

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
})

3. Uji alur autentikasi

Simpan konfigurasi SMART sebagai lingkungan:

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

Uji API FHIR dengan Apidog - gratis

Pertimbangan Kepatuhan

HIPAA

Di AS, aplikasi layanan kesehatan harus mematuhi HIPAA. Ini memengaruhi:

Transmisi Data: Gunakan TLS 1.2+
Penyimpanan Data: Enkripsi saat tidak aktif
Kontrol Akses: Pencatatan audit, akses minimum yang diperlukan
Perjanjian Asosiasi Bisnis (Business Associate Agreement): Diperlukan dengan vendor EHR

Keamanan SMART on FHIR

Token kedaluwarsa (biasanya 1 jam)
Token refresh tersedia untuk sesi yang diperpanjang
Konteks pasien terikat pada cakupan token
Logout memerlukan pencabutan token

Minimalisasi data

Hanya minta cakupan yang Anda butuhkan:

Baik: patient/Observation.read
Hindari: patient/*.read kecuali jika diperlukan

Kesalahan umum dan perbaikan

401 Tidak Sah (Unauthorized)

Penyebab: Token kedaluwarsa atau tidak valid.

Perbaikan: Segarkan token menggunakan token refresh dari otorisasi awal.

403 Terlarang (Forbidden)

Penyebab: Cakupan tidak menyertakan sumber daya yang diminta.

Perbaikan: Periksa cakupan Anda. Jika Anda memerlukan akses lebih, minta cakupan tambahan selama otorisasi.

404 Tidak Ditemukan (Not Found)

Penyebab: Pasien atau sumber daya tidak ada.

Perbaikan: Verifikasi ID sumber daya. Pastikan pasien dapat diakses dengan konteks pasien dari token Anda saat ini.

422 Entitas Tidak Dapat Diproses (Unprocessable Entity)

Penyebab: Validasi sumber daya FHIR gagal.

Perbaikan: Periksa bidang yang wajib diisi dan terminologi:

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

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	Rumah sakit besar	Sistem kesehatan	Praktik kecil	Open source

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

Kasus penggunaan dunia nyata

Portal pasien. Sebuah sistem kesehatan membangun portal pasien yang menarik data dari Epic. Pasien melihat hasil lab, obat-obatan, dan janji temu yang akan datang. Portal tersebut menggunakan API FHIR dengan autentikasi SMART on FHIR.

Penelitian klinis. Perusahaan farmasi perlu mengidentifikasi pasien yang memenuhi syarat untuk uji klinis. Mereka mengkueri API FHIR di berbagai sistem rumah sakit untuk menemukan pasien yang cocok dengan kriteria, dengan manajemen persetujuan yang tepat.

Pemantauan jarak jauh. Perusahaan telehealth mengintegrasikan tanda vital yang dilaporkan pasien dengan sistem EHR. Observasi dibuat melalui API FHIR dan segera terlihat oleh klinisi di Epic.

Penutup

Berikut adalah apa yang telah Anda pelajari:

FHIR adalah standar untuk API layanan kesehatan
Sumber daya merepresentasikan konsep layanan kesehatan seperti pasien dan observasi
SMART on FHIR menangani OAuth dengan konteks pasien
Setiap vendor EHR memiliki detail implementasi spesifik
Uji dengan sandbox sebelum produksi

Langkah Anda selanjutnya:

Jelajahi sandbox publik HAPI FHIR
Pahami jenis sumber daya FHIR untuk kasus penggunaan Anda
Daftar untuk program pengembang EHR
Uji dengan Apidog menggunakan data pasien tiruan
Implementasikan penanganan data yang sesuai HIPAA

Uji API FHIR dengan Apidog - gratis

button

FAQ

Apa perbedaan antara FHIR dan HL7 v2?HL7 v2 adalah standar pesan yang lebih lama yang digunakan dalam antarmuka rumah sakit. FHIR adalah standar API REST modern. Sebagian besar integrasi baru menggunakan FHIR, tetapi HL7 v2 masih umum di sistem lama.

Apakah saya memerlukan BAA untuk menggunakan API EHR?Ya, jika Anda menangani PHI. Perjanjian Asosiasi Bisnis (Business Associate Agreements) diperlukan antara entitas tertanggung dan rekan bisnis. Periksa dengan tim kepatuhan vendor EHR.

Bagaimana cara mendapatkan akses ke API FHIR Epic?Daftar di marketplace App Orchard Epic. Untuk pengujian sandbox, gunakan sandbox publik mereka. Akses produksi memerlukan persetujuan rumah sakit.

Apa itu konteks pasien?Token SMART on FHIR menyertakan ID pasien. Panggilan API Anda terbatas pada data pasien tersebut. Ini memastikan aplikasi hanya dapat mengakses data yang diotorisasi pasien.

Bisakah saya menulis data ke EHR?Ya, tetapi dengan batasan. Sebagian besar EHR memungkinkan pembuatan observasi dan pembaruan demografi pasien. Menulis diagnosis atau obat-obatan biasanya memerlukan persetujuan dukungan keputusan klinis.

Bagaimana cara menangani kode terminologi?FHIR menggunakan terminologi standar:

LOINC untuk tes lab dan observasi
SNOMED CT untuk konsep klinis
ICD-10 untuk diagnosis
RxNorm untuk obat-obatan

Gunakan sistem-sistem ini saat membuat sumber daya.

Bagaimana dengan layanan kesehatan internasional?FHIR bersifat global. Setiap negara mungkin memiliki panduan implementasi. AS menggunakan profil US Core. Periksa spesifikasi wilayah Anda.