# 환자 장기 데이터 API

> 클리닉, 실험실, 앱 및 기기에서 얻은 한 환자의 시간 경과에 따른 기록: 장기 기록에 필요한 것과 이를 읽는 네 가지 방법 — 타임라인, $everything, IPS 및 AI 컨텍스트.

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

**환자 장기 데이터 API는 한 사람의 건강 기록을 시간 경과에 따라 — 진단, 처방약, 검사 결과, 활력 징후, 예방 접종 및 모든 출처의 방문 기록 — 제공하며, 개별 제공업체별 문서가 아닌 하나의 순서화된 기록으로 반환합니다.** Anpheros는 클리닉, 실험실, 앱 및 기기에서 작성된 환자별 단일 HL7 FHIR R4 기록으로 해당 기록을 유지하며, 모든 버전과 모든 작성자를 보존합니다. 개발자는 네 가지 방법으로 이 데이터를 읽을 수 있습니다: 연대순 타임라인, `Patient/$everything`을 포함한 전체 FHIR 기록, 국제 환자 요약 또는 AI 모델을 위한 간결한 컨텍스트.

<!-- visual:longitudinal-sources -->

## "Longitudinal"에 필요한 사항

결과 목록만으로는 Longitudinal Record가 되지 않습니다. 애플리케이션이 수년간 여러 제공업체에 걸친 기록을 신뢰하려면 각 항목은 다음을 포함해야 합니다.

| 요구 사항 | 중요성 | Anpheros 저장 방식 |
|---|---|---|
| 코딩된 의미 | 서로 다른 실험실의 값이 비교 가능해야 함 | 결과의 경우 LOINC, 질병의 경우 ICD-10, 약물의 경우 ATC |
| 임상 날짜 | 업로드 시점이 아닌 발생 시점으로 정렬 | 각 리소스의 `effective`, `onset`, `occurrence` 날짜 |
| 작성자 | 의사의 진단과 환자의 메모는 같지 않음 | 모든 쓰기에 대한 Provenance: 작성자 유형, 사람, 조직, 소스 시스템 |
| 모든 버전 | 수정 시 이전 정보를 삭제해서는 안 됨 | 모든 리소스의 버전 기록 (`_history`) |
| 동의 | 해당 개인이 동의해야만 다른 애플리케이션에서 기록을 볼 수 있음 | 범위, 만료 및 액세스 로그가 포함된 OAuth 권한 부여 |

## 하나의 레코드, 여러 작성자

<!-- visual:longitudinal-timeline -->

## 기록을 읽는 네 가지 방법

| 필요 사항 | 엔드포인트 | 얻는 정보 |
|---|---|---|
| 화면을 위한 연대순 피드 | `GET /v1/patients/{id}/timeline` | 8가지 유형(관찰, 상태, 약물, 문서, 진료, 예약, 예방 접종, 에피소드)의 항목과 날짜, 제목, 요약 및 FHIR 참조; `from`, `to`, `types`로 필터링 |
| FHIR 형식의 전체 기록 | `GET /fhir/R4/Patient/{id}/$everything` | searchset Bundle; `_since`, `_type`, `_count` 및 `_offset` 지원 |
| 공유 가능한 임상 요약 | `GET /fhir/R4/Patient/{id}/$summary` | International Patient Summary (IPS) 문서 |
| AI 모델 입력 | `POST /v1/context` | 토큰 예산 내의 섹션, 각 사실은 출처와 함께 레이블 지정 |

TypeScript SDK를 사용한 타임라인:

```ts
import { Anpheros, apiKey } from '@anpheros/sdk';

const anpheros = new Anpheros({ auth: apiKey(process.env.ANPHEROS_KEY!) });   // a sandbox key, sk_test_…
const { data: patients } = await anpheros.patients.list();
const page = await anpheros.timeline.list(patients[0].id, {
  from: '2025-01-01',
  types: 'condition,medication,observation',
  limit: 50,
});
for (const item of page.data) console.log(item.date, item.type, item.title);
```

그리고 날짜 이후 변경된 내용으로 제한된 FHIR 형식의 동일한 기록:

```bash
curl -H "Authorization: Bearer $ANPHEROS_KEY" \
  "https://platform.anpheros.com/fhir/R4/Patient/$PATIENT/\$everything?_since=2026-01-01&_type=Observation,Condition"
```

## 복사본 동기화 유지

애플리케이션이 자체적으로 기록의 히스토리를 관리하는 경우, `resource.created`, `resource.updated` 및 `resource.deleted` 웹훅을 구독하십시오. 다른 프로젝트가 액세스 가능한 레코드에 기록할 때도 이 웹훅이 트리거되며, `data.external: true` 및 `data.source`의 작성자 정보가 포함되므로 폴링 없이 다른 클리닉의 데이터가 전달됩니다.

## 알아두면 좋은 제한 사항

- 레코드는 기록된 내용을 그대로 보유합니다. Anpheros는 병원이나 국가 네트워크에서 자체적으로 기록을 가져오지 않으며, 클리닉, 실험실, 앱 및 개인이 기록합니다.
- 26개의 FHIR R4 리소스 유형이 저장됩니다. Claim 및 ExplanationOfBenefit과 같은 청구 리소스는 저장되지 않습니다.
- 다른 애플리케이션은 해당 개인의 동의 하에만 개인의 기록을 읽을 수 있습니다. 프로젝트 자체 키는 생성한 환자를 볼 수 있습니다.

## 자주 묻는 질문

### 종단 환자 데이터란 무엇인가요?
진단, 약물, 검사 결과, 활력 징후, 예방 접종 및 방문 기록 등 시간 경과에 따라 여러 진료 환경에서 수집된 개인의 건강 정보로, 하나의 연속적인 기록으로 읽을 수 있도록 보관됩니다.

### 환자 기록의 연대기적 보기를 제공하는 API는 무엇인가요?
Anpheros에서는 `GET /v1/patients/{id}/timeline`가 페이징 및 날짜/유형 필터를 사용하여 8가지 리소스 유형의 항목을 날짜순으로 반환합니다. 전체 FHIR 데이터는 `Patient/$everything`를 사용하십시오.

### 기록이 표준 형식으로 저장되나요?
예. 모든 항목은 표준 코드(LOINC, ICD-10, ATC, CVX, UCUM)를 포함하는 HL7 FHIR R4 리소스이며, 요약은 International Patient Summary입니다.

### 각 항목을 누가 작성했는지 어떻게 알 수 있나요?
모든 쓰기는 작성자 유형(환자, 의료인, 장치, 가져오기 또는 AI), 해당 개인, 조직 및 소스 시스템을 포함하는 Provenance 리소스를 생성합니다.

### 현실적인 종단 데이터를 사용하여 테스트할 수 있나요?
예. 모든 샌드박스 프로젝트는 약 6개월 분량의 질병, 약물, 실험실 검사 결과 및 활력 징후를 가진 30명의 합성 환자로 시작합니다.

<!-- visual:cta-longitudinal -->

## 관련 자료

- [FHIR을 이용한 개인 건강 기록(PHR) 앱](https://developers.anpheros.com/ko/guides/personal-health-record-app): 실제 앱에서의 타임라인
- [의료 데이터 출처 설명](https://developers.anpheros.com/ko/guides/medical-data-provenance)
- [건강 앱을 위한 환자 동의 플랫폼](https://developers.anpheros.com/ko/guides/patient-consent-platform)
- [FHIR R4를 사용하여 의료 기록을 저장하는 방법](https://developers.anpheros.com/ko/guides/store-medical-records-fhir)
- [AI 에이전트와 의료 데이터](https://developers.anpheros.com/ko/guides/ai-agents-medical-data): 컨텍스트 엔드포인트
- [웹훅](https://developers.anpheros.com/ko/guides/webhooks)