# Healthcare API: что это и как это работает

> Что такое healthcare API, как работает один вызов, на что обратить внимание, а также бесплатный healthcare API FHIR R4 с согласием пациента, происхождением данных и размещением в ЕС — с примерами и часто задаваемыми вопросами.

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

**Healthcare API — это программный интерфейс, через который программное обеспечение читает и записывает медицинские данные — записи пациентов, наблюдения, диагнозы, лекарства, документы — и через который авторизуется доступ к этим данным.** Anpheros Platform API — это healthcare 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)**: версии вместо тихих перезаписей.
- **Аудируемость** операций чтения, а не только записи.
- **Безопасные повторные попытки (idempotency)** и **предсказуемые ошибки**, поскольку медицинские данные не должны дублироваться или теряться.
- **Изоляция** между приложениями, использующими одну и ту же инфраструктуру.
- **Резидентность данных**, соответствующая местоположению пациентов.

Далее на этой странице показано, как каждый из этих пунктов реализован в API Anpheros.

## Обзор 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/ru/guides/errors) · [Лимиты](https://developers.anpheros.com/ru/guides/limits)

### События

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

## Выбор между FHIR и REST v1

Используйте **FHIR**, если вы уже работаете с FHIR, вам нужны типы ресурсов, которые `/v1` не охватывает (например, `Immunization`, `Procedure` или `CarePlan`), или вы обмениваетесь данными с другими FHIR-системами. Используйте **REST v1** для кода приложения, которому нужен плоский JSON для распространенных случаев. Оба варианта читают и записывают одни и те же ресурсы с одинаковыми идентификаторами, поэтому проект может использовать их совместно. [Medical data API](https://developers.anpheros.com/ru/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 предлагает API FHIR R4 и более простой REST API поверх одних и тех же данных.

### Существует ли бесплатный API для здравоохранения для разработчиков?
Да. Песочница Anpheros бесплатна и работает в режиме самообслуживания: войдите через Google, получите API-ключ и работайте с 30 синтетическими пациентами через FHIR R4 или REST. Производственное использование начинается от €99 в месяц, первый месяц бесплатно.

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

### Где хранятся данные?
В Европейском Союзе: сервис и его базы данных работают в Google Cloud `europe-west4` (Нидерланды).

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

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

## Связанные материалы

- [API для ЭМК и API медицинских записей](https://developers.anpheros.com/ru/guides/ehr-api)
- [Платформа API для здравоохранения: что входит в состав и как выбрать](https://developers.anpheros.com/ru/guides/healthcare-api-platform)
- [Как создать API для здравоохранения с использованием TypeScript](https://developers.anpheros.com/ru/guides/healthcare-api-typescript): пошаговое руководство с Express
- [Как хранить медицинские записи с использованием FHIR R4](https://developers.anpheros.com/ru/guides/store-medical-records-fhir): пошаговое руководство с curl
- [API для здравоохранения с согласием пациента](https://developers.anpheros.com/ru/guides/healthcare-api-patient-consent)
- [Бэкенд SMART on FHIR](https://developers.anpheros.com/ru/guides/smart-on-fhir-backend)
- [API медицинских данных](https://developers.anpheros.com/ru/guides/medical-data-api)
- [Платформа FHIR](https://developers.anpheros.com/ru/guides/fhir)
- [Интероперабельность данных здравоохранения](https://developers.anpheros.com/ru/guides/interoperability)
- [Интеграции в сфере здравоохранения](https://developers.anpheros.com/ru/guides/healthcare-integrations)
- [Справочник по API (OpenAPI)](https://developers.anpheros.com/docs) · [Аутентификация и OAuth](https://developers.anpheros.com/ru/guides/authentication)