# 의료 데이터 API

> Anpheros API에서 각 종류의 의료 데이터가 어디에 저장되는지, 어떻게 코딩되는지, 그리고 작성, 필터링, 추적, 수정 및 삭제하는 방법에 대한 작업 예시입니다.

Source: https://developers.anpheros.com/ko/guides/medical-data-api

**의료 데이터 API는 소프트웨어에 환자 기록의 내용을 구조화된 방식으로 접근할 수 있도록 합니다: 환자 생성, 혈압 기록, 활성 약물 목록 조회, 검사 결과 첨부, 누가 무엇을 작성했는지 추적합니다.** 이 페이지는 Anpheros API의 데이터 작업에 대해 설명합니다. 즉, 어떤 종류의 의료 데이터가 어디로 가는지, 어떻게 코딩되는지, 그리고 어떻게 다시 읽어오는지에 대한 내용이며, 샌드박스에서 작동하는 예시를 포함합니다.

애플리케이션은 이러한 작업을 사용하여 Anpheros를 제품의 의료 데이터베이스로 취급합니다. 환자 기록은 플랫폼의 HL7 FHIR R4 저장소에 저장되며, 애플리케이션은 자체 의료 데이터 테이블을 유지하는 대신 API를 통해 읽고 씁니다.

더 넓은 그림(인증, 동의, 이벤트)은 [Healthcare API](https://developers.anpheros.com/ko/guides/healthcare-api)를 참조하십시오.

## 각 종류의 의료 데이터가 저장되는 위치

| 의료 데이터 | REST v1 | FHIR 리소스 | 코딩 |
|---|---|---|---|
| 환자 정보 | `POST /v1/patients` | `Patient` | 이름, 생년월일, 성별, 식별자 |
| 활력 징후, 검사 결과, 증상, 활동, 설문 조사 | `/v1/patients/{id}/observations` | `Observation` | LOINC (증상: ICD-10 챕터 R); UCUM 단위 |
| 진단 및 문제 | `/v1/patients/{id}/conditions` | `Condition` | ICD-10 |
| 약물 | `/v1/patients/{id}/medications` | `MedicationStatement` | ATC, 제품명은 텍스트로 유지 |
| 문서 (PDF, 이미지) | `/v1/patients/{id}/documents` | `DocumentReference` | LOINC 문서 종류 |
| 전체 검사 보고서 | `POST /v1/patients/{id}/labs/import` | `Observation` (laboratory) | LOINC (알려진 경우), 그렇지 않으면 해당 실험실 자체 코드 |
| 복용 또는 건너뛴 용량, 예방 접종, 알레르기, 시술, 보고서, 치료 계획, 목표, 의뢰, 방문, 예약, 치료 팀, 가족력, 설문지 | `/fhir/R4/{type}` | `MedicationAdministration`, `Immunization`, `AllergyIntolerance`, `Procedure`, `DiagnosticReport`, `CarePlan`, `Goal`, `ServiceRequest`, `Encounter`, `Appointment`, `CareTeam`, `FamilyMemberHistory`, `QuestionnaireResponse` | [FHIR 코드 시스템](https://developers.anpheros.com/ko/guides/fhir-code-systems)에 따름 |

REST v1 객체와 FHIR 리소스는 동일한 ID를 가진 동일한 레코드이며, 모든 v1 객체는 `fhir` 참조를 포함합니다.

## 의료 데이터 작성

```bash
# a lab result with its reference range, linked to the report it came from
curl -X POST https://platform.anpheros.com/v1/patients/$PID/observations \
     -H "Authorization: Bearer $KEY" -H 'content-type: application/json' -H "Idempotency-Key: $(uuidgen)" -d '{
  "code": "4548-4", "display": "Hemoglobin A1c", "category": "laboratory",
  "value": 6.4, "unit": "%", "effective_at": "2026-09-01T08:00:00Z",
  "reference_range": {"low": 4.0, "high": 5.6},
  "derived_from": ["DocumentReference/'$DOC'"], "author_type": "import"
}'
```

- **Observation 카테고리:** `vital-signs`, `laboratory`, `symptom`, `activity`, `survey`, `exam`, `imaging`, `social-history`.
- **복합 측정값** (예: 혈압)은 `components` (패널 `85354-9` 내의 수축기 `8480-6`, 이완기 `8462-4`)을 사용합니다.
- **Author 유형:** `patient`, `practitioner`, `device`, `import`, `ai`. 이 중 하나가 없으면 플랫폼은 `import`을 기록합니다.
- **암기하기 어려운 코드:** `GET /v1/terminology/loinc?q=hba1c`은 번들된 LOINC 하위 집합을 검색하고 `GET /v1/search?q=metformin`은 증상, 질병 및 의약품 카탈로그를 검색합니다. 표시 이름 없이 작성된 관찰은 자동으로 LOINC 이름을 갖게 됩니다.

## 의료 데이터 읽기

```bash
curl "https://platform.anpheros.com/v1/patients/$PID/observations?category=laboratory&code=4548-4&from=2026-01-01" -H "Authorization: Bearer $KEY"
curl "https://platform.anpheros.com/v1/patients/$PID/conditions?clinical_status=active" -H "Authorization: Bearer $KEY"
curl "https://platform.anpheros.com/v1/patients/$PID/medications?status=active" -H "Authorization: Bearer $KEY"
curl "https://platform.anpheros.com/v1/patients/$PID/timeline?from=2026-06-01" -H "Authorization: Bearer $KEY"
```

| 엔드포인트 | 필터 |
|---|---|
| observations | `category`, `code`, `from`, `to` |
| conditions | `clinical_status` |
| medications | `status` |
| documents | `kind` |
| timeline | `from`, `to`, `types` |

목록은 `limit` 및 `cursor`로 페이지 매김됩니다. **timeline**은 관찰, 상태, 약물, 문서, 방문, 예약, 예방 접종 및 치료 에피소드를 하나의 연대순 목록으로 병합합니다. 이는 환자 기록 화면에 대한 자연스러운 입력입니다.

REST 필터가 다루지 않는 모든 항목에 대해서는 FHIR 검색을 사용하십시오: `GET /fhir/R4/Observation?patient=$PID&code=http://loinc.org|4548-4&_sort=-date` ([FHIR 플랫폼](https://developers.anpheros.com/ko/guides/fhir)).

## 데이터 추적 및 수정

- **작성자:** `GET /v1/patients/{id}/provenance/{type}/{resourceId}` — 버전별로 작성자 유형, 프로젝트, 조직 및 소스 시스템에 대한 항목이 하나씩 있습니다.
- **모든 버전:** `GET /fhir/R4/{type}/{id}/_history`; 다른 사람의 변경 사항을 덮어쓰지 않도록 `If-Match`로 업데이트하십시오.
- **소유권:** 동의하면 다른 조직에서 작성한 내용을 읽을 수 있지만, 자신의 프로젝트에서 작성한 내용만 변경하거나 삭제할 수 있습니다(그렇지 않으면 `403`).
- **삭제:** `DELETE /v1/{observations|conditions|medications}/{id}`; `Patient`를 삭제하면 전체 레코드가 삭제됩니다.

## 문서

문서(업로드 대상)를 생성하고, 플랫폼을 통해 또는 스토리지에 직접 바이트를 업로드한 후, 최종 확정합니다. 최종 확정 후에는 원본이 변경 불가능하며, SHA-256 해시와 크기가 기록됩니다. 파일당 최대 25MiB입니다.

## 관련 항목

- [의료 데이터 정규화 방법](https://developers.anpheros.com/ko/guides/normalize-medical-data): 코드, 단위, 날짜, 중복, 유효성 검사
- [의료 데이터 출처 설명](https://developers.anpheros.com/ko/guides/medical-data-provenance): 누가 무엇을 작성했는지, 그리고 기록 방법
- [Healthcare API](https://developers.anpheros.com/ko/guides/healthcare-api)
- [환자 의료 기록](https://developers.anpheros.com/ko/guides/patient-medical-record)
- [헬스케어 앱 구축](https://developers.anpheros.com/guides/build-a-healthcare-app)
- [API 레퍼런스 (OpenAPI)](https://developers.anpheros.com/docs) · [시작하기](https://developers.anpheros.com/ko/guides/getting-started)