# Як інтегрувати клінічні системи з FHIR бекендом

> Посібник: підключення ЕМР клініки до FHIR записів пацієнтів R4 — каталог лікарів, зіставлення за номером запису, візит як одна транзакція з лікарем як автором, лабораторні звіти, дані інших провайдерів та вебхуки.

Source: https://developers.anpheros.com/uk/guides/integrate-clinic-systems-fhir

**Цей посібник підключає програмне забезпечення клініки (ЕМР, систему управління практикою або інструмент бронювання) до записів пацієнтів HL7 FHIR R4 в Anpheros: клініка та її лікарі реєструються в каталозі, пацієнти зіставляються за номером запису клініки, візит записується як одна транзакція з лікарем, зазначеним як автор, і клініка дізнається про дані, додані іншими провайдерами.** Кожен запит `curl` до безкоштовного пісочниці, а відповіді є власними відповідями платформи.

Інтеграція працює на сервері клініки, з ключем API проекту для пацієнтів, яких реєструє клініка, і, для людей, які вже мають запис Anpheros, з дозволом OAuth, який вони схвалюють.

## Що чому відповідає

| У клінічній системі | У FHIR R4 |
|---|---|
| клініка, її відділення | `Organization` |
| лікар або медсестра | `Practitioner` |
| ця особа, яка працює в цій клініці, зі спеціалізацією | `PractitionerRole` |
| медична карта пацієнта та її номер | `Patient` з `identifier` у системі клініки |
| візит | `Encounter` |
| життєві показники, результати, виміряні під час візиту | `Observation` пов'язані з `Encounter` |
| діагноз | `Condition` (ICD-10), з `verificationStatus` попереднім або підтвердженим |
| рецепт, поточне лікування | `MedicationStatement` (ATC) |
| лист, виписка з лікарні, скан | `DocumentReference` з файлом |
| результати лабораторних досліджень | [лабораторний конектор](https://developers.anpheros.com/uk/guides/lab-connector), у `Observation` |

## Крок 1: реєстрація клініки та її лікарів

Ресурси каталогу не містять пацієнтів. Інші проєкти в тому ж середовищі можуть їх читати, тому інші постачальники пацієнта бачать, хто що написав, але тільки ваш проєкт може їх змінювати.

```bash
export BASE=https://platform.anpheros.com/fhir/R4
export KEY=sk_test_…
H=(-H "Authorization: Bearer $KEY" -H "Content-Type: application/fhir+json")

curl -X POST $BASE/Organization "${H[@]}" -d '{"resourceType": "Organization", "active": true, "name": "Clinica Cardio Nord",
  "identifier": [{"system": "https://clinic.example/org", "value": "CCN"}]}'

curl -X POST $BASE/Practitioner "${H[@]}" -d '{"resourceType": "Practitioner", "active": true,
  "name": [{"family": "Popescu", "given": ["Ana"], "prefix": ["Dr."]}]}'

curl -X POST $BASE/PractitionerRole "${H[@]}" -d '{"resourceType": "PractitionerRole", "active": true,
  "practitioner": {"reference": "Practitioner/'$PRACTITIONER'"},
  "organization": {"reference": "Organization/'$ORG'"},
  "code": [{"text": "Cardiologist"}]}'
```

Зберігайте повернуті ідентифікатори поруч із записами вашого персоналу. Коли хтось звільняється, встановіть його `PractitionerRole` на `"active": false`; його минулі записи зберігають його ім'я, і він більше не може діяти через вашу систему.

## Крок 2: зіставлення пацієнтів

Для пацієнтів, яких реєструє клініка, створіть `Patient` з номером запису клініки як ідентифікатором:

```bash
curl -X POST $BASE/Patient "${H[@]}" -d '{"resourceType": "Patient",
  "identifier": [{"system": "https://clinic.example/mrn", "value": "MRN-20981"}],
  "name": [{"family": "Dinu", "given": ["Andrei"]}], "gender": "male", "birthDate": "1968-11-05"}'
```

З цього моменту шукайте пацієнта за цим номером, ніколи за іменем та датою народження:

```bash
curl "$BASE/Patient?identifier=https://clinic.example/mrn|MRN-20981" -H "Authorization: Bearer $KEY"
```

**Якщо особа вже має запис в Anpheros**, зі свого власного додатку або від іншого постачальника, клініка не створює другий. Вона запитує у особи доступ за допомогою OAuth, з планшета на стійці реєстрації або за посиланням, надісланим перед візитом, використовуючи **конфіденційний** додаток (сервер клініки зберігає секрет). Особа обирає свій запис та термін, протягом якого клініка може отримати до нього доступ. Кроки описані в [Як реалізувати згоду пацієнта з SMART on FHIR](https://developers.anpheros.com/uk/guides/smart-on-fhir-backend); поле `patient` токена є id для зберігання у вашому файлі.

## Крок 3: Запис візиту як однієї транзакції

Візит створює кілька ресурсів, які належать разом. Надішліть їх як `transaction`, щоб вони зберігалися одночасно або не зберігалися взагалі, і вкажіть, хто працює: `X-Anpheros-Acting-As` визначає роль лікаря. Вона стає автором у Provenance, записується до журналу доступу та відображається пацієнту за іменем.

```bash
curl -X POST $BASE "${H[@]}" \
  -H "X-Anpheros-Acting-As: PractitionerRole/$ROLE" \
  -H "X-Anpheros-Author-Type: practitioner" \
  -H "X-Anpheros-Source-System: ccn-emr" -d '{
  "resourceType": "Bundle", "type": "transaction",
  "entry": [
    {"fullUrl": "urn:uuid:aa000000-0000-4000-8000-000000000001",
     "resource": {"resourceType": "Encounter", "status": "finished",
       "class": {"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode", "code": "AMB", "display": "ambulatory"},
       "subject": {"reference": "Patient/'$PID'"},
       "serviceProvider": {"reference": "Organization/'$ORG'"},
       "participant": [{"individual": {"reference": "PractitionerRole/'$ROLE'"}}],
       "period": {"start": "2026-10-09T10:00:00Z", "end": "2026-10-09T10:30:00Z"}},
     "request": {"method": "POST", "url": "Encounter"}},
    {"resource": {"resourceType": "Observation", "status": "final",
       "category": [{"coding": [{"system": "http://terminology.hl7.org/CodeSystem/observation-category", "code": "vital-signs"}]}],
       "code": {"coding": [{"system": "http://loinc.org", "code": "8867-4", "display": "Heart rate"}]},
       "subject": {"reference": "Patient/'$PID'"},
       "encounter": {"reference": "urn:uuid:aa000000-0000-4000-8000-000000000001"},
       "effectiveDateTime": "2026-10-09T10:10:00Z",
       "valueQuantity": {"value": 92, "unit": "/min", "system": "http://unitsofmeasure.org", "code": "/min"}},
     "request": {"method": "POST", "url": "Observation"}},
    {"resource": {"resourceType": "Condition",
       "subject": {"reference": "Patient/'$PID'"},
       "encounter": {"reference": "urn:uuid:aa000000-0000-4000-8000-000000000001"},
       "clinicalStatus": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/condition-clinical", "code": "active"}]},
       "verificationStatus": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/condition-ver-status", "code": "provisional"}]},
       "code": {"coding": [{"system": "http://hl7.org/fhir/sid/icd-10", "code": "I48.0", "display": "Paroxysmal atrial fibrillation"}]}},
     "request": {"method": "POST", "url": "Condition"}}
  ]}'
```

`transaction-response` містить `201 Created` для Encounter, Observation та Condition. Observation та Condition тепер вказують на реальний `Encounter/0ca25459-…`. Provenance кожного визначає роль лікаря, клініку та вихідну систему:

```json
"agent": [{"who": {"reference": "PractitionerRole/e6d8c227-…",
                   "identifier": {"system": "https://anpheros.com/fhir/CodeSystem/author-type", "value": "practitioner"}},
           "onBehalfOf": {"reference": "Organization/c3a56a4b-…", "display": "Clinica Cardio Nord"}}],
"entity": [{"role": "source", "what": {"identifier": {"system": "ccn-emr"}}}]
```

Діагноз є `provisional` до його підтвердження. Оновіть його до `confirmed` пізніше, і історія збереже обидва. Що означає кожне поле, пояснюється в [Пояснення походження медичних даних](https://developers.anpheros.com/uk/guides/medical-data-provenance).

## Крок 4: лабораторні результати та документи

Результати з власної лабораторії клініки або звіти, які приносить пацієнт, проходять через лабораторний конектор одним запитом на звіт:

```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 "X-Anpheros-Source-System: ccn-lab" --data-binary @oru.hl7
```

Листи та виписки є документами: створіть `DocumentReference` через `/v1/patients/{id}/documents` та завантажте PDF. Оригінальний файл ніколи не змінюється, а значення, витягнуті з нього, посилаються на нього. Див. [Як імпортувати лабораторні результати до запису FHIR](https://developers.anpheros.com/uk/guides/import-lab-results-fhir) та [API медичних даних](https://developers.anpheros.com/uk/guides/medical-data-api).

## Крок 5: читайте, що написали інші провайдери, і дотримуйтесь своєї компетенції

За згодою пацієнта клініка читає весь запис у межах своїх областей, включаючи те, що додали інші клініки, лабораторії та сам пацієнт. Вона може змінювати лише те, що написала сама. Оновлення або видалення ресурсу іншої організації призведе до відповіді `403`, а оригінал залишиться незмінним. Щоб виправити щось, написане іншим провайдером, створіть власний ресурс (наприклад, новий `Condition` з вашою оцінкою) і дозвольте запису відображати обидва, кожен зі своїм автором.

Перед візитом `GET $BASE/Patient/$PID/$summary` надає Міжнародний резюме пацієнта (International Patient Summary) запису: проблеми, ліки, алергії та останні життєві показники з кожного джерела.

## Крок 6: дізнатися про нові дані

Зареєструйте webhook один раз для проєкту клініки:

```bash
curl -X POST https://platform.anpheros.com/v1/webhooks -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
     -d '{"url": "https://ccn.example/anpheros/hook", "events": ["resource.created", "resource.updated", "consent.revoked"]}'
```

Коли інший проєкт записує дані до запису, до якого ваша клініка має доступ, подія повідомляє про це за допомогою `data.external: true` та джерела, тому ваша EMR може відображати "нові результати з іншої лабораторії" без опитування. Подія `consent.revoked` означає, що особа відкликала доступ клініки: припиніть синхронізацію цього запису. Підписи, повторні спроби та корисне навантаження розглядаються в розділі [Webhooks](https://developers.anpheros.com/uk/guides/webhooks).

## Що бачить пацієнт

Пацієнт бачить візит, пульс та попередній діагноз у своєму записі, кожен з яких позначений як доданий доктором Аною Попеску з клініки Cardio Nord. У своїх підключеннях додаток клініки перелічує кожен доступ, із зазначенням імені, коли діяв практикуючий лікар. Саме така прозорість спонукає пацієнтів надавати доступ наступній клініці.

## Чекліст для запуску в експлуатацію

- [ ] Організації, Практики та Ролі Практиків зареєстровані; особи, що пішли, встановлені як неактивні
- [ ] Пацієнти зіставляються за ідентифікатором клініки, ніколи за іменем
- [ ] Існуючі записи досягаються через згоду OAuth, не дублюються
- [ ] Кожен запит від клінічного персоналу містить `X-Anpheros-Acting-As`
- [ ] Візити записуються як транзакції; діагнози з правильним статусом верифікації
- [ ] Системне джерело встановлено при кожному записі; лабораторні звіти через конектор
- [ ] Кінцева точка Webhook перевіряє підписи; `consent.revoked` оброблено
- [ ] Проект для продакшену з підписаним DPA (ключі `sk_live_…`); див. [Ціни](https://developers.anpheros.com/uk/guides/pricing)

## Часті запитання

### Чи має Anpheros готовий конектор для моєї EMR?
Ні. Готових конекторів до конкретних EMR або лабораторних систем немає; інтеграція будується на основі FHIR R4 та REST API, зазвичай як невеликий сервіс поруч з EMR. Лабораторні повідомлення HL7 v2 приймаються як є.

### Чи може лікар працювати у двох клініках?
Так. Один `Practitioner` може мати `PractitionerRole` у кожній організації. Роль, зазначена в `X-Anpheros-Acting-As`, визначає, для якої клініки записується кожен запис.

### Що відбувається, коли пацієнт відкликає доступ клініки?
Запити клініки до цього запису повертають `401`, і надсилається webhook `consent.revoked`. Те, що клініка записала, залишається в записі пацієнта з його походженням; клініка просто більше не може його читати чи змінювати.

## Пов'язане

- [Інтеграції в галузі охорони здоров'я](https://developers.anpheros.com/uk/guides/healthcare-integrations): усі шаблони інтеграції з першого погляду
- [Пояснення походження медичних даних](https://developers.anpheros.com/uk/guides/medical-data-provenance)
- [Як реалізувати згоду пацієнта за допомогою SMART on FHIR](https://developers.anpheros.com/uk/guides/smart-on-fhir-backend)
- [Як імпортувати результати лабораторних досліджень до запису FHIR](https://developers.anpheros.com/uk/guides/import-lab-results-fhir)
- [Сумісність медичних даних](https://developers.anpheros.com/uk/guides/interoperability)