# Healthcare API: що це таке і як це працює

> Що таке медичний API, як працює один виклик, на що звернути увагу, а також безкоштовний медичний API FHIR R4 з дозволом пацієнта, походженням даних та хостингом в ЄС — з прикладами та FAQ.

Source: https://developers.anpheros.com/uk/guides/healthcare-api

**Медичний API — це програмний інтерфейс, через який програмне забезпечення читає та записує медичні дані — записи пацієнтів, спостереження, діагнози, ліки, документи — і через який авторизується доступ до цих даних.** Anpheros Platform API — це медичний API, що працює поверх HL7 FHIR R4 запису під контролем пацієнта: програми використовують його для зберігання та отримання медичних даних, отримання згоди пацієнта та сповіщення про зміни.

<!-- visual: hapi-hero -->

## Як працює виклик медичного API

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

<!-- visual: hapi-request -->

## Типи медичних API

| Тип | Що обмінюється | Типове використання |
|---|---|---|
| FHIR REST API | Ресурси FHIR через HTTP (`GET /Observation?patient=…`) | сучасний стандарт для обміну клінічними даними |
| SMART on FHIR / OAuth | авторизація для FHIR API | надання стороннім додаткам доступу до запису з дозволу користувача |
| HL7 v2 messaging | повідомлення, розділені символом "|" (`ORU^R01` для результатів, `ADT` для госпіталізацій) | лабораторні та лікарняні системи, часто через інтерфейси, а не HTTP |
| Обмін документами | клінічні документи (PDF, CDA, пакети документів FHIR) | резюме, виписні листи, направлення |
| Пропрієтарні REST API | JSON, специфічний для постачальника | власний мобільний додаток або інтеграції одного продукту |

Anpheros поєднує перші два як свою основу, приймає лабораторні результати HL7 v2 як вхідні дані, зберігає документи з їх оригіналами та створює пакети документів FHIR (International Patient Summary). Він також пропонує простіший REST API на основі тих самих даних для розробників, які не хочуть працювати безпосередньо з FHIR.

## На що звернути увагу в медичному API

<!-- visual:hapi-checklist:replace -->

- **Стандартна модель даних**, щоб дані могли переміщуватися між системами без власного мапінгу.
- **Авторизація, яку контролює пацієнт**, а не лише облікові дані, які контролює додаток.
- **Походження (Provenance)**: хто записав кожне значення, від чийого імені, з якої системи.
- **Історія (History)**: версії замість тихого перезапису.
- **Аудитоздатність (Auditability)** читань, а не лише записів.
- **Безпечні повторні спроби (Safe retries)** (ідемпотентність) та **передбачувані помилки (predictable errors)**, оскільки медичні дані не повинні дублюватися або втрачатися.
- **Ізоляція (Isolation)** між додатками, які спільно використовують ту саму інфраструктуру.
- **Резиденція даних (Data residency)**, що відповідає місцю перебування пацієнтів.

Решта цієї сторінки показує, як кожен із цих пунктів представлений в Anpheros API.

## Огляд API Anpheros

| Поверхня | Базовий шлях | Призначення |
|---|---|---|
| FHIR R4 | `/fhir/R4` | 26 типів ресурсів; читання, пошук, створення, оновлення, видалення, історія, транзакції, `$everything`, `$summary`, `$validate` |
| REST v1 | `/v1` | пацієнти, спостереження, стани, ліки, документи, хронологія, походження, контекст ШІ, імпорт лабораторних даних, термінологія, вебхуки |
| OAuth 2.1 | `/oauth` | сторінка згоди, токени (PKCE), відкликання, ключі OpenID Connect |
| Сторона пацієнта | `/me` | власні записи особи, хто має доступ, журнал доступу, відкликати |
| Виявлення | `/fhir/R4/metadata`, `/fhir/R4/.well-known/smart-configuration`, `/openapi.json` | машинно-читабельні описи API |

Базовий URL: `https://platform.anpheros.com`. Пісочниця та продакшн використовують його спільно; ключ визначає площину даних.

### Автентифікація

- **API ключі** (`sk_test_…`, `sk_live_…`) для ваших серверів; вони бачать пацієнтів, створених вашим проєктом.
- **OAuth токени доступу** (`at_…`) для програми, що діє від імені одного пацієнта за згодою.

```bash
curl https://platform.anpheros.com/v1/patients -H "Authorization: Bearer $KEY"
```

### Безпечне записування

Запити `POST` приймають `Idempotency-Key`: повторний запит з тим самим ключем повертає оригінальну відповідь і нічого не створює. Кожне записування отримує `Provenance`; тип автора надсилається в тілі (`author_type`) або в заголовках, таких як `X-Anpheros-Author-Type`, `X-Anpheros-Source-System`, `X-Anpheros-Origin-Id` та `X-Anpheros-On-Behalf-Of`.

```bash
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": "29463-7", "display": "Body weight", "category": "vital-signs",
          "value": 71.4, "unit": "kg", "effective_at": "2026-09-28T07:30:00Z", "author_type": "patient"}'
```

### Помилки та обмеження

FHIR кінцеві точки відповідають `OperationOutcome`; інші — `{"error": {"type", "message", "field"}}`. Кожна відповідь містить `Anpheros-Request-Id`. Стандартне обмеження становить 600 запитів на хвилину на ключ та на IP-адресу. [Помилки](https://developers.anpheros.com/uk/guides/errors) · [Обмеження](https://developers.anpheros.com/uk/guides/limits)

### Події

Підписані вебхуки для `resource.created`, `resource.updated`, `resource.deleted`, `consent.granted`, `consent.revoked`, `document.finalized` та `ping`. [Вебхуки](https://developers.anpheros.com/uk/guides/webhooks)

## Вибір між FHIR та REST v1

Використовуйте **FHIR**, коли ви вже працюєте з FHIR, потребуєте типів ресурсів, які `/v1` не охоплює (наприклад, `Immunization`, `Procedure` або `CarePlan`), або обмінюєтеся даними з іншими FHIR-системами. Використовуйте **REST v1** для коду додатків, який потребує плоского JSON для поширених випадків. Обидва варіанти читають і записують одні й ті самі ресурси з однаковими ідентифікаторами, тому проєкт може їх комбінувати. [Medical data API](https://developers.anpheros.com/uk/guides/medical-data-api) детально описує операції з даними.

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

### Що таке медичний API?
Програмний інтерфейс, за допомогою якого програмне забезпечення читає та записує медичні дані — записи пацієнтів, спостереження, діагнози, ліки та документи — і через який авторизується доступ до цих даних. Сучасні медичні API використовують HL7 FHIR R4 для даних та OAuth 2.0 або 2.1 із SMART on FHIR для авторизації.

### Яка різниця між медичним API та FHIR API?
FHIR — це один зі стандартів, якого може дотримуватися медичний API. FHIR API обмінюється ресурсами FHIR через REST; медичний API також може приймати повідомлення HL7 v2, документи або пропрієтарний JSON. Anpheros пропонує FHIR R4 API та простіший REST API для тих самих даних.

### Чи існує безкоштовний медичний API для розробників?
Так. Пісочниця Anpheros є безкоштовною та самообслуговуваною: увійдіть за допомогою Google, отримайте ключ API та працюйте з 30 синтетичними пацієнтами через FHIR R4 або REST. Виробництво починається від €99 на місяць, перший місяць безкоштовно.

### Як пацієнти надають згоду медичному API?
Через OAuth 2.1 із PKCE: програма надсилає особу на сторінку згоди зі SMART on FHIR scopes; особа обирає, чим ділитися і як довго, може бачити журнал доступу та може відкликати доступ у будь-який час.

### Де зберігаються дані?
У Європейському Союзі: сервіс та його бази даних працюють у Google Cloud `europe-west4` (Нідерланди).

### Який медичний API мені вибрати?
Порівняйте стандарт даних, хто авторизує доступ, походження та аудит, місцезнаходження даних, як поводяться повторні спроби та помилки, і чи можете ви безкоштовно тестувати з реалістичними даними. [Платформа медичного API: що вона включає та як вибрати](https://developers.anpheros.com/uk/guides/healthcare-api-platform) перетворює це на запитання, які слід поставити будь-якому постачальнику.

<!-- visual:cta-hapi -->

## Пов'язане

- [API медичних закладів та API медичних записів](https://developers.anpheros.com/uk/guides/ehr-api)
- [Платформа API для охорони здоров'я: що вона включає та як вибрати](https://developers.anpheros.com/uk/guides/healthcare-api-platform)
- [Як створити API для охорони здоров'я за допомогою TypeScript](https://developers.anpheros.com/uk/guides/healthcare-api-typescript): покроковий посібник з Express
- [Як зберігати медичні записи за допомогою FHIR R4](https://developers.anpheros.com/uk/guides/store-medical-records-fhir): покроковий посібник з curl
- [API для охорони здоров'я з дозволом пацієнта](https://developers.anpheros.com/uk/guides/healthcare-api-patient-consent)
- [Бекенд SMART on FHIR](https://developers.anpheros.com/uk/guides/smart-on-fhir-backend)
- [API медичних даних](https://developers.anpheros.com/uk/guides/medical-data-api)
- [Платформа FHIR](https://developers.anpheros.com/uk/guides/fhir)
- [Інтероперабельність медичних даних](https://developers.anpheros.com/uk/guides/interoperability)
- [Інтеграції в галузі охорони здоров'я](https://developers.anpheros.com/uk/guides/healthcare-integrations)
- [Довідник API (OpenAPI)](https://developers.anpheros.com/docs) · [Аутентифікація та OAuth](https://developers.anpheros.com/uk/guides/authentication)