EHR API 사용법

요약

EHR API는 Epic, Cerner, Athenahealth와 같은 시스템에 저장된 환자 건강 기록에 접근합니다. 대부분의 최신 EHR은 의료 데이터의 표준 형식인 FHIR(Fast Healthcare Interoperability Resources)을 지원합니다. 인증은 SMART on FHIR 확장 기능을 사용하는 OAuth 2.0을 활용합니다. 테스트를 위해 Apidog를 사용하여 FHIR 리소스를 검증하고, 샌드박스를 대상으로 테스트하며, 프로덕션 시스템에 연결하기 전에 통합 기능이 환자 데이터를 올바르게 처리하는지 확인하십시오.

서론

전자의무기록(EHR)에는 진단, 약물, 검사 결과, 알레르기, 치료 계획 등 환자 진료에 관한 모든 정보가 담겨 있습니다. 병원, 의원, 의료 시스템은 이 데이터를 Epic, Cerner, Athenahealth와 같은 EHR 플랫폼에 저장합니다.

의료 애플리케이션을 구축한다는 것은 이러한 시스템에 연결하는 것을 의미합니다. 병원에 CSV 파일 내보내기를 요청할 수는 없습니다. API가 필요합니다. 하지만 의료 API는 일반적인 웹 API와 다릅니다. 이들은 보호 대상 건강 정보(PHI)를 처리하며, 미국 HIPAA와 같은 규정을 준수해야 합니다.

좋은 소식은 대부분의 EHR 공급업체가 이제 표준 API 형식인 FHIR을 지원한다는 것입니다. 어려운 소식은 인증, 권한 부여, 데이터 매핑이 여전히 복잡하다는 것입니다.

의료 통합을 구축하는 경우, Apidog는 FHIR 리소스를 테스트하고 데이터 구조를 검증하며 애플리케이션이 환자 데이터를 올바르게 처리하는지 확인하는 데 도움을 줍니다. 실제 병원 시스템과 작업하기 전에 공용 샌드박스를 대상으로 테스트할 수 있습니다.

Apidog로 FHIR API를 무료로 테스트하세요.

이 가이드를 마치면 다음을 할 수 있습니다.

FHIR 리소스 유형 및 구조 이해
SMART on FHIR로 인증
환자 인구 통계 및 임상 데이터 쿼리
환자 리소스 생성 및 업데이트
EHR 샌드박스로 테스트

FHIR 이해하기

FHIR (Fast Healthcare Interoperability Resources)은 의료 API의 최신 표준입니다. 다음을 정의합니다.

리소스: 의료 개념을 위한 데이터 유형 (환자, 관찰, 약물)
REST API: 리소스에 대한 표준 작업
형식: JSON 및 XML 표현

기본 URL 구조

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

예시:

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

FHIR 버전

대부분의 EHR은 FHIR R4(릴리스 4)를 사용합니다. 일부 오래된 시스템은 DSTU2를 사용합니다. 이 가이드에서는 R4를 다룹니다.

리소스 유형

리소스	목적
Patient	인구 통계 및 관리 데이터
Practitioner	의료 제공자
Organization	병원, 의원
Observation	검사 결과, 활력 징후
MedicationRequest	처방전
Condition	진단, 문제
Encounter	방문, 입원
DocumentReference	임상 문서
AllergyIntolerance	알레르기 및 부작용

FHIR 리소스 구조

환자 리소스 예시

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

관찰 리소스 예시

{
  "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을 이용한 인증

SMART on FHIR은 의료 분야를 위한 OAuth 2.0을 확장한 것입니다. 이는 환자 컨텍스트와 EHR 특정 스코프를 처리합니다.

환자 접근을 위한 OAuth 흐름

1단계: 인가(Authorization) URL 가져오기

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

응답에는 다음이 포함됩니다.

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

2단계: 사용자에게 인가 요청 리디렉션

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

3단계: 코드를 토큰으로 교환

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"

응답:

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

patient 필드는 환자 ID 컨텍스트를 제공합니다.

SMART 스코프

스코프	접근 권한
`patient/*.read`	모든 환자 데이터 읽기
`patient/Patient.read`	환자 인구 통계만 읽기
`patient/Observation.read`	관찰 데이터만 읽기
`user/*.read`	승인된 사용자의 모든 데이터 읽기
`launch/patient`	EHR이 환자 컨텍스트로 앱 실행

환자 데이터 쿼리

환자 인구 통계 가져오기

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

관찰 데이터 검색

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

응답은 번들(Bundle)입니다.

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

일반적인 검색 매개변수

# 날짜 범위별 검사 결과
GET /Observation?patient=123&category=laboratory&date=gt2026-01-01

# 특정 LOINC 코드
GET /Observation?patient=123&code=http://loinc.org|8480-6

# 약물
GET /MedicationRequest?patient=123&status=active

# 상태 (진단)
GET /Condition?patient=123&clinical-status=active

# 진료
GET /Encounter?patient=123&type=AMB

페이지 매김

큰 결과 세트는 페이지를 나눕니다.

GET /Observation?patient=123&_count=20

응답에는 링크가 포함됩니다.

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

리소스 생성 및 업데이트

관찰 생성

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

환자 업데이트

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 공급업체별 세부 사항

Epic

Epic의 FHIR API는 대부분의 대형 병원에서 사용할 수 있습니다.

기본 URL: https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4/
샌드박스: https://fhir.epic.com/test/api/FHIR/R4/
문서: https://fhir.epic.com

Epic은 프로덕션 접근을 위해 앱 마켓플레이스에 앱 등록을 요구합니다.

Cerner

Cerner (Oracle Health)는 일부 확장 기능을 포함한 표준 FHIR을 사용합니다.

기본 URL: https://fhir-myrecord.cerner.com/r4/{tenant-id}
샌드박스: https://fhir-deprecated.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d
문서: https://docs.oracle.com/en/health/health-cerner/

Athenahealth

Athenahealth는 FHIR 및 레거시 API를 제공합니다.

기본 URL: https://api.platform.athenahealth.com/fhir/r4/{practice-id}
샌드박스: 개발자 프로그램을 통해 이용 가능
문서: https://docs.athenahealth.com

Apidog로 테스트하기

의료 API는 신중한 테스트가 필요합니다. 환자 데이터는 민감합니다.

1. 공개 샌드박스 사용

공개 FHIR 샌드박스를 대상으로 테스트하세요.

# HAPI FHIR (오픈 소스)
https://hapi.fhir.org/baseR4

# SMART Health IT 샌드박스
https://launch.smarthealthit.org

2. 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. 인증 흐름 테스트

SMART 설정을 환경으로 저장:

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로 FHIR API를 무료로 테스트하세요.

규정 준수 고려사항

HIPAA

미국에서 의료 애플리케이션은 HIPAA를 준수해야 합니다. 이는 다음에 영향을 미칩니다.

데이터 전송: TLS 1.2 이상 사용
데이터 저장: 미사용 데이터 암호화
접근 제어: 감사 로깅, 최소 필수 접근
사업 제휴 계약(Business Associate Agreement): EHR 공급업체와 필수

SMART on FHIR 보안

토큰 만료 (일반적으로 1시간)
연장된 세션을 위한 새로 고침 토큰 사용 가능
환자 컨텍스트는 토큰 스코프에 바인딩됩니다.
로그아웃 시 토큰 폐기가 필요합니다.

데이터 최소화

필요한 스코프만 요청하십시오.

좋음: patient/Observation.read
피해야 할 것: patient/*.read (필요하지 않은 경우)

일반적인 오류 및 해결 방법

401 권한 없음

원인: 토큰이 만료되었거나 유효하지 않습니다.

해결: 초기 인가 시 받은 새로 고침 토큰을 사용하여 토큰을 새로 고치십시오.

403 금지됨

원인: 스코프에 요청된 리소스가 포함되어 있지 않습니다.

해결: 스코프를 확인하십시오. 더 많은 접근이 필요한 경우, 인가 시 추가 스코프를 요청하십시오.

404 찾을 수 없음

원인: 환자 또는 리소스가 존재하지 않습니다.

해결: 리소스 ID를 확인하십시오. 현재 토큰의 환자 컨텍스트로 해당 환자에게 접근 가능한지 확인하십시오.

422 처리할 수 없는 엔티티

원인: FHIR 리소스 유효성 검사에 실패했습니다.

해결: 필수 필드 및 용어를 확인하십시오.

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

대안 및 비교

기능	Epic	Cerner	Athenahealth	OpenEMR
FHIR R4	✓	✓	✓	부분적
SMART on FHIR	✓	✓	✓	아니오
샌드박스 접근	✓	✓	제한적	자체 호스팅
API 문서	우수	좋음	좋음	기본
시장 점유율	대형 병원	의료 시스템	소규모 병원	오픈 소스

Epic과 Cerner는 대규모 의료 시스템을 지배합니다. Athenahealth는 소규모 병원을 대상으로 합니다. OpenEMR은 오픈 소스이지만 API 지원이 제한적입니다.

실제 사용 사례

환자 포털. 한 의료 시스템이 Epic에서 데이터를 가져오는 환자 포털을 구축합니다. 환자는 검사 결과, 약물, 예정된 진료 일정을 볼 수 있습니다. 이 포털은 SMART on FHIR 인증과 함께 FHIR API를 사용합니다.

임상 연구. 제약 회사는 임상 시험에 적합한 환자를 식별해야 합니다. 이들은 적절한 동의 관리를 통해 여러 병원 시스템의 FHIR API를 쿼리하여 기준에 맞는 환자를 찾습니다.

원격 모니터링. 원격 의료 회사가 환자가 보고한 활력 징후를 EHR 시스템과 통합합니다. 관찰 데이터는 FHIR API를 통해 생성되며 Epic에서 임상의에게 즉시 표시됩니다.

마무리

다음은 학습한 내용입니다.

FHIR은 의료 API의 표준입니다.
리소스는 환자 및 관찰과 같은 의료 개념을 나타냅니다.
SMART on FHIR은 환자 컨텍스트를 사용하여 OAuth를 처리합니다.
각 EHR 공급업체에는 특정 구현 세부 사항이 있습니다.
프로덕션 전에 샌드박스로 테스트하십시오.

다음 단계:

HAPI FHIR 공개 샌드박스를 탐색하십시오.
사용 사례에 맞는 FHIR 리소스 유형을 이해하십시오.
EHR 개발자 프로그램에 등록하십시오.
모의 환자 데이터를 사용하여 Apidog로 테스트하십시오.
HIPAA 준수 데이터 처리를 구현하십시오.

Apidog로 FHIR API를 무료로 테스트하세요.

버튼

자주 묻는 질문

FHIR과 HL7 v2의 차이점은 무엇인가요? HL7 v2는 병원 인터페이스에 사용되는 오래된 메시징 표준입니다. FHIR은 최신 REST API 표준입니다. 대부분의 새로운 통합은 FHIR을 사용하지만, HL7 v2는 레거시 시스템에서 여전히 흔합니다.

EHR API를 사용하려면 BAA가 필요한가요? 네, PHI를 처리하는 경우 필요합니다. 사업 제휴 계약(Business Associate Agreements)은 Covered Entity와 Business Associate 간에 필수입니다. EHR 공급업체의 규정 준수 팀에 확인하십시오.

Epic의 FHIR API에 어떻게 접근할 수 있나요? Epic의 App Orchard 마켓플레이스에 등록하십시오. 샌드박스 테스트를 위해서는 공개 샌드박스를 사용하십시오. 프로덕션 접근은 병원의 승인이 필요합니다.

환자 컨텍스트란 무엇인가요? SMART on FHIR 토큰에는 환자 ID가 포함됩니다. API 호출은 해당 환자의 데이터로 제한됩니다. 이는 앱이 환자가 승인한 데이터에만 접근할 수 있도록 보장합니다.

EHR에 데이터를 쓸 수 있나요? 네, 하지만 제한이 있습니다. 대부분의 EHR은 관찰 데이터를 생성하고 환자 인구 통계를 업데이트할 수 있도록 합니다. 진단이나 약물 기록은 일반적으로 임상 의사 결정 지원 승인이 필요합니다.

용어 코드는 어떻게 처리하나요? FHIR은 표준 용어를 사용합니다.

검사 및 관찰을 위한 LOINC
임상 개념을 위한 SNOMED CT
진단을 위한 ICD-10
약물을 위한 RxNorm

리소스를 생성할 때 이러한 시스템을 사용하십시오.

국제 의료 분야에서는 어떤가요? FHIR은 전 세계적입니다. 각 국가마다 구현 가이드가 있을 수 있습니다. 미국은 US Core 프로파일을 사용합니다. 해당 지역의 사양을 확인하십시오.