# HL7 v2를 FHIR로 매핑

> HL7 v2 ORU^R01에서 FHIR R4로의 세그먼트 대 리소스 및 OBX 필드별 매핑, 통합을 방해하는 함정, 그리고 HTTPS를 통해 호출할 수 있는 컨버터.

Source: https://developers.anpheros.com/ko/guides/hl7-v2-to-fhir-mapping

**HL7 v2를 FHIR로 매핑한다는 것은 파이프 구분 v2 메시지의 각 세그먼트를 FHIR R4 리소스로 변환하는 것을 의미합니다. PID는 Patient로, OBR은 DiagnosticReport(또는 ServiceRequest)로, 각 OBX는 Observation으로 변환되며, 코드, 단위, 범위 및 시간은 필드별로 전달됩니다.** HL7은 일반적인 세그먼트에 대한 개념 맵을 포함하는 공식 [V2-to-FHIR 구현 가이드](https://hl7.org/fhir/uv/v2mappings/)를 게시합니다. 이 페이지에서는 실험실 결과(ORU^R01)에 대한 실제 매핑, 실제 통합을 방해하는 함정, 그리고 HTTPS를 통해 호출할 수 있는 컨버터인 Anpheros lab connector에 대해 설명합니다.

<!-- visual:v2map-flow -->

## 세그먼트를 리소스로 변환

| HL7 v2 세그먼트 | 전달 내용 | FHIR R4 리소스 | Anpheros 랩 커넥터에서의 처리 |
|---|---|---|---|
| MSH | 구분자, 전송 시스템, 메시지 유형, 메시지 ID | `MessageHeader` (또는 provenance) | MSH에서 구분자 읽기; ORU^R01에 대한 유형 확인; 추적성을 위해 메시지 ID 유지 |
| PID | 환자 식별자, 이름, 생년월일, 성별 | `Patient` | 사용 안 함: 환자는 요청 URL에 있는 환자이므로, 메시지가 잘못된 레코드에 기록될 수 없음 |
| PV1 | 방문 정보 | `Encounter` | 사용 안 함 |
| ORC / OBR | 주문 및 보고: filler/placer ID, 날짜 | `ServiceRequest`, `DiagnosticReport` | OBR-3 (또는 OBR-2)는 보고서 ID, OBR-7은 기본 날짜 |
| OBX | 단일 결과 | `Observation` | OBX당 하나의 실험실 관찰(Observation) |
| NTE | 자유 텍스트 메모 | `Observation.note` | 사용 안 함 |

## OBX 필드별 설명

| OBX 필드 | FHIR Observation 요소 | 비고 |
|---|---|---|
| OBX-2 value type (NM, SN, ST, CWE) | `value[x]` 선택 | NM 및 SN은 `valueQuantity`으로 변환되며, 텍스트는 그대로 유지됩니다. |
| OBX-3 identifier `code^text^system` | `code.coding` | OBX-3.3의 `LN`은 LOINC를 의미하며, 다른 시스템은 해당 실험실의 로컬 코드입니다. |
| OBX-5 value, OBX-6 unit | `valueQuantity.value`, `.unit` / `.code` (UCUM) | `<5` 및 `6,4`은 의도적으로 파싱해야 합니다. |
| OBX-7 reference range | `referenceRange.low` / `.high` | `3.5-5.1`, `<200`, `>40` |
| OBX-8 abnormal flag | `interpretation` | H, L, HH, LL, A, N |
| OBX-11 result status | `status` | F → final, C → amended, P → preliminary, I → registered |
| OBX-14 observation time | `effectiveDateTime` | v2 시간 정보에는 종종 시간대가 누락되어 있습니다. FHIR는 시간대를 요구합니다. |

## 하나의 요청으로 메시지 변환

```bash
curl -X POST "https://platform.anpheros.com/v1/patients/$PID/labs/import" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: x-application/hl7-v2+er7" \
  -H "Idempotency-Key: $(uuidgen)" \
  --data-binary @oru_r01.hl7
```

응답은 생성된 Observation 수, 이미 가져온 것으로 건너뛴 수, 매핑할 수 없었던 마커, 그리고 코드와 함께 새로 생성된 Observation을 나열합니다. 각 Observation은 보고서, 테스트, 시간 및 값에서 파생된 안정적인 식별자를 받으므로, 동일한 메시지를 다시 보내는 실험실은 중복을 생성하지 않습니다.

## 실제 통합을 방해하는 함정

1.  **시간대.** `20261002074500`에는 오프셋이 없습니다. 발신자의 시간대를 명시적으로 결정하십시오.
2.  **로컬 코드.** LOINC가 없는 경우 실험실 자체 코드를 유지하십시오. 절대 삭제하지 마십시오.
3.  **재전송.** 결과당 안정적인 식별자가 없으면 재시도가 중복이 됩니다.
4.  **수정.** OBX-11 `C`은 수정입니다. 대체할지 추가할지 결정하고 이전 결과를 표시하십시오.
5.  **비수치 값.** `positive`, `<5`, `6,4`은 추측이 아닌 명시적인 규칙이 필요합니다.

## 커넥터의 기능 범위

이 커넥터는 HTTPS를 통해 ORU^R01 형식의 검사 결과를 수신합니다. ADT 또는 오더 메시지는 수신하지 않으며, TCP를 통한 MLLP 통신(앞단의 인터페이스 엔진이 전달 가능)을 지원하지 않습니다. DiagnosticReport를 생성하지 않으며, PID를 통한 환자 매칭도 수행하지 않습니다.

## 자주 묻는 질문

### HL7 v2를 FHIR로 어떻게 매핑하나요?
세그먼트별로 매핑합니다: PID는 Patient, PV1은 Encounter, ORC/OBR은 ServiceRequest 및 DiagnosticReport, OBX는 Observation, NTE는 notes에 해당합니다. HL7의 V2-to-FHIR 구현 가이드에서 필드 수준 개념 매핑을 정의합니다.

### HL7 v2를 FHIR로 변환하는 도구가 있나요?
네. 인터페이스 엔진과 오픈 소스 라이브러리가 메시지를 변환합니다. 실험실 결과의 경우, Anpheros 실험실 커넥터는 ORU^R01 메시지를 하나의 HTTPS 요청으로 FHIR R4 Observations로 변환하여 환자의 기록에 저장합니다.

### Anpheros는 어떤 HL7 v2 메시지 유형을 지원하나요?
ORU^R01 실험실 결과. 다른 유형의 메시지는 경고가 표시되며 OBX 세그먼트만 읽습니다. ADT, 주문 및 기타 메시지는 지원되지 않습니다.

### HL7 v2 비정상 플래그는 FHIR에서 어떻게 표현되나요?
OBX-8은 HL7 ObservationInterpretation 코드(H, L, HH, LL, A, N)를 사용하여 `Observation.interpretation`로 변환됩니다.

<!-- visual:cta-v2map -->

## 관련 자료

- [검사 결과 API: HL7 v2, FHIR 및 LOINC](https://developers.anpheros.com/ko/guides/lab-results-api)
- [FHIR 대 HL7 v2: 실제적인 차이점](https://developers.anpheros.com/ko/guides/fhir-vs-hl7-v2)
- [FHIR 레코드에 검사 결과 가져오는 방법](https://developers.anpheros.com/ko/guides/import-lab-results-fhir)
- [임상 대시보드를 위한 HL7 v2 및 FHIR](https://developers.anpheros.com/ko/guides/clinical-dashboard-hl7-fhir)
- [검사 결과 커넥터](https://developers.anpheros.com/ko/guides/lab-connector)