# API для поздовжніх даних пацієнта

> Історія одного пацієнта з часом з клінік, лабораторій, додатків та пристроїв: що потрібно для поздовжнього запису та чотири способи його читання — часова шкала, $everything, IPS та контекст ШІ.

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

**API для поздовжніх даних пацієнта повертає історію здоров'я однієї особи з часом — діагнози, ліки, результати лабораторних досліджень, життєві показники, вакцинації та візити з кожного джерела — як один упорядкований запис замість окремих документів для кожного постачальника.** Anpheros зберігає цю історію як один запис HL7 FHIR R4 на пацієнта, створений клініками, лабораторіями, додатками та пристроями, зберігаючи кожну версію та кожного автора. Розробники читають його чотирма способами: хронологічна часова шкала, повний запис FHIR з `Patient/$everything`, Міжнародний підсумок пацієнта (International Patient Summary) або компактний контекст для моделей ШІ.

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

## Що вимагає "лонґітюдний" запис

Список результатів ще не є лонґітюдним записом. Щоб додаток міг довіряти історії, що охоплює роки та різних постачальників, кожен запис повинен містити:

| Вимога | Чому це важливо | Як Anpheros це зберігає |
|---|---|---|
| Кодоване значення | Значення з різних лабораторій повинні бути порівнянними | LOINC для результатів, ICD-10 для станів, ATC для медикаментів |
| Клінічна дата | Сортування за часом події, а не за часом завантаження | Дати `effective`, `onset`, `occurrence` на кожному ресурсі |
| Автор | Діагноз лікаря та примітка пацієнта — це не одне й те саме | Provenance при кожному записі: тип автора, особа, організація, вихідна система |
| Кожна версія | Виправлення не повинні стирати те, що було відомо раніше | Історія версій на кожному ресурсі (`_history`) |
| Згода | Інші додатки бачать історію лише за згодою особи | OAuth гранти зі скоупами, терміном дії та журналом доступу |

## Один запис, багато авторів

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

## Чотири способи читання історії

| Потреба | Кінцева точка (Endpoint) | Що ви отримуєте |
|---|---|---|
| Хронологічна стрічка для екрана | `GET /v1/patients/{id}/timeline` | Елементи восьми типів (observation, condition, medication, document, encounter, appointment, immunization, episode) з датою, заголовком, резюме та посиланням FHIR; фільтруйте за допомогою `from`, `to`, `types` |
| Повний запис у форматі FHIR | `GET /fhir/R4/Patient/{id}/$everything` | Bundle типу searchset; підтримуються `_since`, `_type`, `_count` та `_offset` |
| Документ клінічного резюме для спільного використання | `GET /fhir/R4/Patient/{id}/$summary` | Документ International Patient Summary (IPS) |
| Вхідні дані для моделі ШІ | `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` повертає записи з восьми типів ресурсів у хронологічному порядку, з пагінацією та фільтрами за датою та типом. Для повних даних FHIR використовуйте `Patient/$everything`.

### Чи зберігається історія у стандартному форматі?
Так. Кожен запис є ресурсом HL7 FHIR R4 зі стандартними кодами (LOINC, ICD-10, ATC, CVX, UCUM), а резюме є Міжнародним резюме пацієнта (International Patient Summary).

### Як дізнатися, хто створив кожен запис?
Кожне записування створює ресурс Provenance із типом автора (пацієнт, практикуючий лікар, пристрій, імпорт або ШІ), особою, організацією та вихідною системою.

### Чи можу я тестувати з реальними поздовжніми даними?
Так. Кожен проєкт пісочниці починається з 30 синтетичних пацієнтів із приблизно шестимісячними даними про стан здоров'я, ліки, лабораторні результати та життєві показники.

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

## Пов'язане

- [Додаток для особистого медичного запису (PHR) з FHIR](https://developers.anpheros.com/uk/guides/personal-health-record-app): хронологія в реальному додатку
- [Пояснення походження медичних даних](https://developers.anpheros.com/uk/guides/medical-data-provenance)
- [Платформа згоди пацієнта для медичних додатків](https://developers.anpheros.com/uk/guides/patient-consent-platform)
- [Як зберігати медичні записи за допомогою FHIR R4](https://developers.anpheros.com/uk/guides/store-medical-records-fhir)
- [AI-агенти та медичні дані](https://developers.anpheros.com/uk/guides/ai-agents-medical-data): кінцева точка контексту
- [Вебхуки](https://developers.anpheros.com/uk/guides/webhooks)