# 실험실 커넥터

> 전체 실험실 보고서를 CSV, HL7 v2 ORU^R01 또는 JSON 형식으로 전송하고 LOINC 코드 및 참조 범위가 포함된 실험실 관찰 결과를 받으세요.

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

실험실(또는 실험실 보고서를 보유한 모든 사람)은 단일 요청으로 전체 보고서를 전송하며,
플랫폼은 모든 결과를 환자의 실험실 `Observation`로 변환합니다.

```
POST /v1/patients/{patient_id}/labs/import
Authorization: Bearer <project key>
Content-Type: text/csv | x-application/hl7-v2+er7 | application/json
X-Anpheros-Source-System: labx        (optional; recorded in Provenance)
Idempotency-Key: <report id>          (optional; a retry returns the same answer)
```

## 형식

**CSV** 헤더 행 포함; 구분 기호 `,` `;` 또는 탭, 소수점 쉼표 허용, 날짜 ISO,
`DD.MM.YYYY` 또는 `DD/MM/YYYY`. 인식되는 열 (루마니아어 또는 영어): 마커
(`analiza`, `test`, `marker`, `name`) — 또는 LOINC `code` 열만 있는 경우 LOINC 이름이 마커가 됩니다 —
값 (`rezultat`, `valoare`, `value`, `result`), 단위 (`um`, `unitate`, `unit`),
참조 범위 (`interval`, `referinta`: `70-100`, `<5`, `>3.5`) 또는 `ref_low`/`ref_high`,
날짜 (`data`, `recoltare`), 선택적 LOINC (`loinc`, `code`), 참고.

```
Analiza;Rezultat;UM;Interval de referinta;Data
Hemoglobina glicozilata (HbA1c);6,4;%;4,0-5,6;01.09.2026
TSH;2,1;mUI/L;0,4-4,0;01.09.2026
```

**HL7 v2 ORU^R01** (ER7 텍스트, 세그먼트 CR 또는 LF로 구분): `OBX-3` 식별자 (`code^text^LN`
은 LOINC; 로컬 코드 (`^L`, `^99zzz`) 또는 기타 코딩 시스템은 `urn:anpheros:lab-code` 아래 실험실 자체 코드로 유지됩니다),
`OBX-5` 값 (`NM`, `SN` 또는 텍스트),
`OBX-6` 단위, `OBX-7` 참조 범위, `OBX-8` 비정상 플래그 → `interpretation`, `OBX-11` 상태,
`OBX-14` 또는 `OBR-7` 날짜; `OBR-3`/`MSH-10`는 Provenance의 보고서 ID가 됩니다.

**실험실.** 각 결과는 `performer`에서 누가 생성했는지 이름을 지정하며, HL7 Europe Laboratory Report 2.1.0
에서 요구하는 대로: 귀하가 활동하는 기관 (`X-Anpheros-Acting-As`), 그렇지 않으면 HL7의 경우 `MSH-4` (보내는 시설), 또는
JSON의 `laboratory` (최상위 또는 항목별). CSV는 실험실을 포함하지 않습니다. 이러한 결과는 누락된
수행자로 유효성 검사되며, 이는 사실입니다.

**텍스트 보고서, 문서 및 누락된 날짜.** 텍스트 보고서가 OBX당 한 줄씩 전송되는 경우 (`TX`/`FT`, 동일한 `OBX-3`)
줄이 연결된 하나의 결과가 됩니다. `OBX-5`의 전체 문서 (`ED` 또는 `Base64`로 인코딩된 모든 값)는
결과로 저장되지 않습니다. 응답은 경고하며 문서는 `/documents`에 속합니다. `OBR-7`이 없으면 결과는
`OBR-14` (검체 수령)로 날짜가 지정되며 경고가 표시됩니다.

**시간 및 시간대.** 시간대가 없는 v2 시간은 UTC가 아닌 발신자의 현지 시간입니다. `OBX-14`/`OBR-7` (`20260901081000+0300`)과 함께 전송된 오프셋은
유지됩니다 (`2026-09-01T08:10:00+03:00`). 오프셋이 없으면 `MSH-7`의 오프셋이
사용되며 경고가 표시됩니다. 오프셋이 전혀 없으면 결과는 날짜만 유지되며 이 또한 경고가 표시됩니다. CSV 시간
(`01.09.2026 08:10`)은 시간대를 포함하지 않으므로 날짜로만 저장됩니다. 2026년 10월 17일까지 이러한 시간은
UTC로 레이블이 지정되었습니다. 해당 시점에 가져온 결과는 식별자를 유지하며 보고서가 다시 전송될 때 인식됩니다.

아직 보류 중 (OBX-11 `I`), 얻을 수 없음 (`X`), 삭제됨 (`D`) 또는 잘못됨 (`W`)인 HL7 결과 및 값이 없는 OBX 세그먼트는
관찰 항목이 되지 않습니다. 각 항목은 `warnings`에 이름이 지정됩니다.

**JSON**: `{"date": "2026-09-01", "origin": "report-77", "laboratory": "Synevo", "items": [{"marker": "TSH", "value": 2.1, "unit": "mUI/L", "ref_low": 0.4, "ref_high": 4.0, "date": "2026-09-01", "code": "3016-3"}]}`.

## 반환되는 항목

```json
{"created": 3, "skipped": 0, "unmapped": ["Marker foarte rar"], "warnings": [],
 "observations": [{"id": "…", "marker": "TSH", "code": "3016-3", "system": "http://loinc.org", "value": 2.1, "unit": "mUI/L", "date": "2026-09-01"}]}
```

- 마커는 보고서에서 LOINC 코드를 제공하거나 플랫폼 용어(루마니아어 및 영어 이름, 일반 별칭)와 일치하는 경우 **LOINC**에 매핑됩니다. 다른 항목은 `urn:anpheros:lab-code` 아래에 실험실 자체 코드를 유지하고 보고서의 정확한 텍스트를 사용하며, `unmapped`에 나열되어 사용자가 직접 매핑을 개선할 수 있도록 합니다. 실험실 자체 코드는 해당 실험실과 함께 있을 때만 고유합니다. 소스 시스템은 각 관찰의 Provenance(`X-Anpheros-Source-System`)에 기록됩니다.
- 이름은 LOINC 이름 및 동의어(*Hemoglobin A1c*, *Glycated hemoglobin*, *HDL cholesterol*, *LDL-C* 등)와 일치합니다. 여러 개념과 일치하거나 개념에 없는 한정자(*urine*, *non-HDL*, *free*, *ratio* 등)를 포함하는 이름은 추측되지 않습니다. 실험실 자체 코드를 유지하고 `unmapped`에 나열됩니다. 시스템에 LOINC 코드가 있는 경우 항상 보내주세요.
- Urea와 urea nitrogen(BUN)은 다른 측정값입니다. *Uree* / *Urea*는 urea(LOINC `3091-6` 또는 mmol/L 기준 `22664-7`)에 매핑되고, *BUN* / *Urea nitrogen* / *Azot ureic*는 urea nitrogen(`3094-0` 또는 mmol/L 기준 `14937-7`)에 매핑됩니다. 값은 절대 변환되지 않습니다.
- LDL 콜레스테롤: 메서드가 없는 이름은 `2089-1`에 매핑됩니다. *calculated* / *calculat* / *Friedewald*는 계산된 LDL(`13457-7`)에 매핑됩니다. *direct*는 직접 분석(`18262-6`)에 매핑됩니다. 메서드는 *Bilirubina directa*의 *direct*와 같은 한정자이며, 총 빌리루빈이 아니므로 실험실 자체 코드를 유지합니다.
- 포도당: 실험실 보고서의 단순한 "Glicemie" / "Glucose"는 혈청 또는 혈장(LOINC `2345-7`)에 매핑됩니다. 모세혈관, 손가락 채혈 또는 전혈("capilar", "sânge integral")을 나타내는 이름은 전혈(`2339-0`)에 매핑됩니다. 보고서의 LOINC 코드는 항상 우선합니다.
- 각 행에는 보고서 내용(보고서 ID, 보고서의 이름 및 코드, 날짜, 값 및 단위)으로 구성된 안정적인 식별자(`urn:anpheros:lab-import:v2`)가 부여됩니다. 플랫폼이 선택한 LOINC 코드가 아닌 보고서 내용으로 구성되므로, **동일한 보고서를 다시 보내도 이미 가져온 행은 건너뜁니다**(`skipped`). 매핑이 개선된 후에도 마찬가지입니다. 이러한 항목 중 하나라도 다른 항목(다른 보고서, 다른 채취 시간, 다른 값)은 별도로 유지됩니다. 2026년 10월 14일 이전에 가져온 결과는 원래 식별자를 유지하며 이름, 날짜, 값, 단위 및 보고서 ID로 인식됩니다. 보고서 ID가 없는 경우(CSV) 이러한 일치는 `warnings`에 보고됩니다. 보고서 ID(HL7 `OBR-3`/`MSH-10`, JSON `origin`)를 보내 별도의 보고서를 구분하세요.
- 모든 관찰에는 `author_type = import`, 소스 시스템 및 보고서 ID가 포함된 Provenance가 포함됩니다. 웹훅은 관찰당 `resource.created`번 발생합니다. 환자는 앱에서 결과를 확인하며, 동의한 모든 앱에서 해당 결과를 읽을 수 있습니다.
- 요청당 최대 500행.

두 SDK 모두: `labs.importCsv`, `labs.importHl7`, `labs.importItems`.

CSV 및 HL7 v2 보고서에서 FHIR 관찰로의 작업 예시, 매핑되지 않은 마커 및 재전송된 보고서 포함: [FHIR 레코드에 실험실 결과 가져오기](https://developers.anpheros.com/ko/guides/import-lab-results-fhir).

실험실 데이터가 실험실, 클리닉, 앱 및 AI 간에 이동하는 방법과 실험실 결과 API에서 찾아야 할 사항: [실험실 결과 API](https://developers.anpheros.com/ko/guides/lab-results-api).