# 검사 결과 API: HL7 v2, FHIR 및 LOINC

> 검사 결과가 HL7 v2 및 FHIR 데이터로 전송되는 방식, 하나의 결과에 포함되어야 하는 내용, FHIR 레코드로 검사 보고서를 수신하는 방법, 실제 예시 포함.

Source: https://developers.anpheros.com/ko/guides/lab-results-api

**검사 결과 API는 PDF 대신 구조화된 데이터(검사 코드, 값, 단위, 참조 범위, 상태 및 시간)로 검사 결과를 제공하므로 소프트웨어에서 저장, 비교, 차트 작성 및 공유할 수 있습니다.** 현재 해당 데이터는 세 가지 형식으로 전송됩니다. HL7 v2 ORU^R01 메시지(여전히 검사실과 병원 간의 백본), HL7 FHIR R4 `Observation` 및 `DiagnosticReport` 리소스(현대 API의 형식), 그리고 검사실별 CSV, JSON 또는 PDF 내보내기입니다. 이 페이지에서는 각 구성 요소가 어떻게 결합되는지, 좋은 검사 결과 API가 갖추어야 할 사항은 무엇인지, 그리고 Anpheros를 사용하여 환자의 FHIR 레코드로 검사 데이터를 수신하는 방법을 설명합니다.

## 누가 어떤 형식으로 검사를 주고받는가

| 발신 → 수신 | 현재 일반적인 형식 | 비고 |
|---|---|---|
| 검사실 → 병원 또는 클리닉 시스템 | HL7 v2 ORU^R01 (미국에서는 종종 HL7 v2.5.1 Laboratory Results Interface guide에 따름) | 주문은 ORM/OML 메시지로 반대 방향으로 전송됩니다. |
| 검사실 → 공중 보건 기관 | HL7 v2 전자 검사 보고, FHIR 증가 추세 | 보고 가능한 조건만 해당 |
| 클리닉 시스템 → 환자 앱 | 환자 액세스 API를 통한 FHIR R4 | 미국에서는 인증된 EHR이 FHIR(US Core)로 검사 결과를 노출합니다. EU에서는 European Health Data Space가 검사 결과를 우선순위 데이터 범주로 나열합니다. |
| 검사실 → 환자 | PDF 보고서, 포털, 때로는 CSV | 대부분의 환자가 실제로 받는 형식 |
| 앱 → AI 모델 | Observations에서 구축된 구조화된 컨텍스트 | 신뢰성을 위해서는 코드와 단위가 필요합니다. |

방향이 중요합니다. 검사실 정보 시스템(LIS)은 결과의 진실 공급원이며, 다운스트림의 모든 시스템은 복사본을 유지합니다. 복사본을 신뢰할 수 있게 만드는 것은 각 시스템이 값의 코드, 단위, 범위 및 출처를 유지한다는 것입니다.

## 하나의 검사 결과에 필요한 정보

"Glucose 126"이라고만 표시된 결과는 안전하게 해석할 수 없습니다. 완전한 결과에는 다음 정보가 포함되어야 합니다.

- **표준 코드.** LOINC는 분석물질, 검체 및 방법을 식별합니다: `2345-7`은 혈청 또는 혈장의 포도당, `2339-0`는 전혈의 포도당입니다. 실험실 자체 코드는 그 옆에 포함될 수 있습니다.
- **단위가 있는 값.** 이상적으로는 UCUM 단위(`mg/dL`, `mmol/L`, `10*3/uL`)를 사용하여 두 실험실의 값을 변환하고 비교할 수 있도록 합니다.
- 실험실에서 사용한 **참고 범위**와 실험실에서 제공하는 경우 **해석** 플래그(H, L, N 등)입니다.
- **상태:** 예비, 최종, 수정 또는 개정. 수정은 발생할 수 있습니다. API는 이전 버전을 잃지 않고 새 버전을 볼 수 있도록 해야 합니다.
- **시간:** 검체가 채취된 시간(`effectiveDateTime`)과 결과가 발표된 시간(`issued`)입니다.
- **출처:** 어떤 실험실에서 생성했으며 어떤 보고서 또는 주문에 속하는지입니다.

FHIR R4에서 각 결과는 `Observation`이며 `category = laboratory`을 포함하고, 이를 그룹화하는 보고서는 `result`의 관찰 목록을 나열하는 `DiagnosticReport`입니다. 검증기가 가장 자주 보고하는 오류가 포함된 두 가지 모두의 유효한 예는 [FHIR R4 JSON 예제](https://developers.anpheros.com/tools/fhir-examples/observation-lab-result)에서 확인할 수 있습니다. [DiagnosticReport 예제](https://developers.anpheros.com/tools/fhir-examples/diagnostic-report)도 참조하십시오.

## HL7 v2와 FHIR 비교

오늘날 대부분의 실험실에서 보내는 방식과 API가 저장해야 하는 방식 그대로의 동일한 지질 패널 결과:

```
OBX|1|NM|2093-3^Cholesterol^LN||212|mg/dL|<200|H|||F|||20261002074500
```

| HL7 v2 필드 | 의미 | FHIR R4 Observation 요소 |
|---|---|---|
| OBX-3 `2093-3^Cholesterol^LN` | LOINC로 코딩된 검사 | `code.coding` (시스템 `http://loinc.org`) |
| OBX-5 `212`, OBX-2 `NM` | 숫자 값 | `valueQuantity.value` |
| OBX-6 `mg/dL` | 단위 | `valueQuantity.unit` |
| OBX-7 `<200` | 참조 범위 | `referenceRange.high` |
| OBX-8 `H` | 비정상 플래그 | `interpretation` |
| OBX-11 `F` | 최종 결과 | `status = final` |
| OBX-14 | 관찰 시간 | `effectiveDateTime` |

두 형식 간의 변환은 대부분 필드 매핑입니다. 어려운 부분은 다른 곳에 있습니다. LOINC 대신 자체 코드를 보내는 실험실, 텍스트로 작성된 숫자(`"6,4"`, `"<5"`), 여러 표기법의 범위, 타임아웃 후 다시 전송되는 보고서 등이 있습니다. [의료 데이터 정규화 방법](https://developers.anpheros.com/ko/guides/normalize-medical-data)에서 이러한 내용을 자세히 다룹니다.

## Anpheros를 사용하여 FHIR 레코드로 검사 결과 수신

Anpheros는 각 환자의 기록을 HL7 FHIR R4로 저장하며 [검사 커넥터](https://developers.anpheros.com/ko/guides/lab-connector)를 제공합니다. 이 커넥터는 HL7 v2, CSV 또는 JSON 형식의 전체 보고서를 한 번의 요청으로 받아 LOINC 코드, 참조 범위, 해석 및 출처 정보가 포함된 실험실 관찰(Observation)을 반환합니다.

```bash
curl -s -X POST "https://platform.anpheros.com/v1/patients/$PID/labs/import" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: x-application/hl7-v2+er7" \
  -H "X-Anpheros-Source-System: springfield-lis" \
  --data-binary @lipid-panel.hl7
```

세 줄짜리 지질 패널(콜레스테롤, HDL, 트리글리세라이드)의 경우, 플랫폼의 로컬 실행 결과는 다음과 같습니다.

```json
{
  "created": 3, "skipped": 0, "unmapped": [], "warnings": [],
  "observations": [
    {"id": "26ed9219-…", "marker": "Cholesterol", "code": "2093-3", "system": "http://loinc.org",
     "value": 212.0, "unit": "mg/dL", "date": "2026-10-02T07:45:00Z"},
    {"id": "2633d1d4-…", "marker": "HDL cholesterol", "code": "2085-9", "system": "http://loinc.org",
     "value": 48.0, "unit": "mg/dL", "date": "2026-10-02T07:45:00Z"},
    {"id": "a02520bb-…", "marker": "Triglyceride", "code": "2571-8", "system": "http://loinc.org",
     "value": 165.0, "unit": "mg/dL", "date": "2026-10-02T07:45:00Z"}
  ]
}
```

저장된 각 결과는 표준 FHIR R4 관찰(Observation)이며, 모든 FHIR 클라이언트에서 읽을 수 있습니다.

```json
{
  "resourceType": "Observation",
  "status": "final",
  "category": [{"coding": [{"system": "http://terminology.hl7.org/CodeSystem/observation-category", "code": "laboratory"}]}],
  "code": {"coding": [{"system": "http://loinc.org", "code": "2093-3",
                        "display": "Cholesterol [Mass/volume] in Serum or Plasma"}], "text": "Cholesterol"},
  "subject": {"reference": "Patient/4c3062d9-…"},
  "effectiveDateTime": "2026-10-02T07:45:00Z",
  "valueQuantity": {"value": 212.0, "unit": "mg/dL"},
  "interpretation": [{"coding": [{"system": "http://terminology.hl7.org/CodeSystem/v3-ObservationInterpretation", "code": "H"}]}],
  "referenceRange": [{"high": {"value": 200.0, "unit": "mg/dL"}}]
}
```

동일한 메시지를 다시 보내도 새로운 내용은 생성되지 않습니다 (`"created": 0, "skipped": 3`). 각 행은 보고서 ID, 코드, 날짜 및 값을 기반으로 안정적인 식별자를 받습니다. 플랫폼에서 LOINC로 매핑할 수 없는 마커는 검사 기관의 코드를 유지하고 `unmapped`에 반환되므로, 원본에서 매핑을 수정할 수 있습니다.

결과를 다시 읽는 것은 표준 FHIR 검색입니다.

```bash
curl -s "https://platform.anpheros.com/fhir/R4/Observation?patient=$PID&category=laboratory&code=http://loinc.org|2093-3" \
  -H "Authorization: Bearer $KEY"
```

동일한 데이터를 입력하고 출력하는 다른 방법:

- **FHIR 직접 연동:** `POST /fhir/R4/Observation` 또는 `DiagnosticReport`와 해당 관찰(Observation)을 함께 포함하는 트랜잭션 번들(transaction Bundle).
- **이벤트:** 관찰(Observation)당 `resource.created` [웹훅](https://developers.anpheros.com/ko/guides/webhooks)을 통해, 검사 결과가 도착하면 병원이나 앱에서 반응할 수 있습니다.
- **사람 및 AI용:** 환자는 앱에서 결과를 확인하고, 동의한 애플리케이션이 결과를 읽을 수 있습니다. `POST /v1/context`은 AI 모델에 최근 검사 값을 포함하는 출처 레이블이 지정된 요약을 제공합니다.
- **출처(Provenance):** 가져온 각 결과는 `author_type = import`, 출처 시스템 및 보고서 ID([의료 데이터 출처](https://developers.anpheros.com/ko/guides/medical-data-provenance))를 기록합니다.

CSV 보고서, HL7 v2 메시지, 매핑되지 않은 마커 및 합성 환자에 대한 재전송 보고서를 포함한 전체 단계별 안내는 튜토리얼 [FHIR 레코드로 검사 결과 가져오기](https://developers.anpheros.com/ko/guides/import-lab-results-fhir)에서 확인할 수 있습니다.

## 전송 전 결과 확인

무료 [FHIR R4 validator](https://developers.anpheros.com/tools/fhir-validator)는 Observation의 구조와 필수 값 세트를 확인하며, `eu-lab` 프로파일과 함께 실험실 결과에 포함되어야 하는 항목들(`laboratory` 카테고리, LOINC 코드, 대상, 최종 유형 상태, 시간, 값, UCUM 단위 및 참조 범위)도 확인합니다. 동일한 검사가 `POST /fhir/R4/Observation/$validate?profile=eu-lab`를 통해 플랫폼에서도 실행됩니다.

## 실험실 결과 API 선택: 체크리스트

- 결과를 FHIR R4 Observations (LOINC 코드 포함) 또는 자체 스키마의 행으로 저장하나요?
- 실험실에서 실제로 보내는 형식(대부분 병원에서는 HL7 v2, 소규모 실험실에서는 CSV 또는 PDF)을 수락할 수 있나요?
- 매핑할 수 없는 마커는 어떻게 처리되나요? 거부되거나, 삭제되거나, 실험실 자체 코드로 유지되나요?
- 재시도가 안전한가요, 아니면 재전송된 보고서가 중복을 생성하나요?
- 수정된 결과는 버전 관리되며, 이전 값은 여전히 읽을 수 있나요?
- 모든 값의 출처가 기록되고 환자에게 표시되나요?
- 누가 결과를 읽을 수 있으며, 이는 환자의 동의에 의해 결정되나요?

## Anpheros의 기능 범위

Anpheros는 실험실 정보 시스템이 아니며 상용 실험실 네트워크에 연결되지 않습니다. 보고서는 실험실, 클리닉 또는 환자의 앱에서 전송됩니다. Anpheros는 실험실 주문을 라우팅하지 않으며, 이 API를 통해 PDF 보고서를 읽지 않습니다 (Anpheros Daily 앱은 환자 측의 사진 및 PDF에서 결과를 추출합니다). 또한 임상적으로 결과를 해석하지 않습니다. 단위는 실험실에서 전송된 그대로 저장됩니다. UCUM 코드로 변환하는 것은 [의료 데이터 정규화 방법](https://developers.anpheros.com/ko/guides/normalize-medical-data)에 설명된 대로 발신자의 책임입니다.

## 자주 묻는 질문

### 랩 결과 API란 무엇인가요?
코드로 지정된 검사, 단위가 있는 값, 참조 범위, 상태 및 시간과 같은 구조화된 데이터로 실험실 결과를 문서가 아닌 인터페이스를 통해 소프트웨어에서 주고받을 수 있게 해주는 인터페이스입니다. 최신 랩 결과 API는 HL7 FHIR R4 Observation 및 DiagnosticReport 리소스를 사용하며, 대부분의 실험실은 여전히 HL7 v2 ORU^R01 메시지를 내보냅니다.

### 랩 검사를 식별하는 코드 시스템은 무엇인가요?
LOINC입니다. 각 LOINC 코드는 분석물질, 검체, 그리고 종종 방법을 명명하므로, `2345-7` (혈청 또는 혈장의 포도당)과 `2339-0` (전혈의 포도당)은 다른 결과입니다. 단위는 UCUM으로 표현하는 것이 가장 좋습니다.

### Observation과 DiagnosticReport의 차이점은 무엇인가요?
Observation은 콜레스테롤 212 mg/dL과 같은 단일 결과입니다. DiagnosticReport는 전체 보고서 — 주문된 패널, 발행자 및 발행 시점 — 이며, `result`에 Observation 목록을 포함합니다.

### HL7 v2 랩 메시지를 FHIR 서버로 가져올 수 있나요?
예. 각 OBX 세그먼트는 하나의 Observation으로 매핑됩니다 (OBX-3은 `code`로, OBX-5 및 OBX-6은 `valueQuantity`으로, OBX-7은 `referenceRange`로, OBX-8은 `interpretation`로). Anpheros 랩 커넥터는 이를 한 번의 요청으로 처리하고 Provenance에 실험실의 보고서 ID를 유지합니다.

### 보고서가 재전송될 때 중복 랩 결과를 어떻게 피할 수 있나요?
보고서, 검사, 시간 및 값에서 파생된 안정적인 식별자를 각 결과에 부여하고, 이미 식별자가 존재하는 행은 건너뜁니다. Anpheros 랩 커넥터는 이를 자동으로 수행하며 `skipped`으로 개수를 보고합니다.

## 관련 자료

- [HL7 v2를 FHIR로 매핑](https://developers.anpheros.com/ko/guides/hl7-v2-to-fhir-mapping): 모든 세그먼트 및 OBX 필드
- [FHIR 레코드에 검사 결과 가져오기](https://developers.anpheros.com/ko/guides/import-lab-results-fhir): 단계별 튜토리얼
- [Lab connector](https://developers.anpheros.com/ko/guides/lab-connector): 엔드포인트 참조
- [의료 데이터 정규화 방법](https://developers.anpheros.com/ko/guides/normalize-medical-data): LOINC, UCUM, 날짜, 범위 및 중복
- [의료 데이터 출처 설명](https://developers.anpheros.com/ko/guides/medical-data-provenance)
- [FHIR 코드 시스템](https://developers.anpheros.com/ko/guides/fhir-code-systems)
- [FHIR 백엔드와 클리닉 시스템 통합 방법](https://developers.anpheros.com/ko/guides/integrate-clinic-systems-fhir)
- [FHIR vs HL7 v2: 실제 차이점](https://developers.anpheros.com/ko/guides/fhir-vs-hl7-v2)
- [임상 대시보드를 위한 HL7 v2 및 FHIR](https://developers.anpheros.com/ko/guides/clinical-dashboard-hl7-fhir): 검사 메시지에서 대시보드 타일까지