Начало работы с Webhook

Что такое Webhook

Webhook позволяет другой системе получать сообщения о событиях в МИС Clinica Web. Когда происходит событие, на которое вы подписались, Clinica Web отправляет HTTP POST с JSON на адрес вашего сервера. Например, можно получать сообщения о создании или изменении предварительной записи.

Перед началом работы

1. Согласуйте интеграцию с медицинским учреждением и получите данные доступа к API (client_id и client_secret). Если доступ уже есть, при необходимости обратитесь за расширением прав.
2. Получите access_token со scope gambit:webhooks. Передавайте его в заголовке Authorization: Bearer <access_token> при управлении подписками.
3. Подготовьте доступный для Clinica Web адрес вашего обработчика. Рекомендуем HTTPS. Обработчик должен принимать POST с JSON, проверять секретный заголовок, если он настроен, и возвращать код успеха HTTP 2xx после принятия сообщения.

Полезные материалы (статьи приведены на украинском языке):

• Начало интеграции с Clinica Web (укр.)
• Получение данных для авторизации и доступа к scope (укр.)
• Получение access token и его использование (укр.)
• Swagger: методы Webhook — пример документации тестовой среды. Для реальной интеграции используйте адрес Clinica Web вашего учреждения и проверяйте доступные события в Swagger соответствующей среды.
• Описание объекта Webhook (укр.) — прежде всего о данных предварительной записи; полные актуальные схемы смотрите в Swagger.
• API назначений и вебхуки (укр.) — подробнее о назначениях лекарств, услуг и мониторинга.

Пример подписки

Запрос ниже создаёт подписку на PrerecordCreated — создание предварительной записи. Замените адрес учреждения, адрес получателя, токен и секрет на собственные значения.

POST https://clinic.example/api/webhooks
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "Uri": "https://example.org/webhooks/clinica",
  "Triggers": [0],
  "SecretToken": "<ваш-секрет>"
}

• Uri — адрес вашего обработчика, а не адрес API Clinica Web.
• Triggers — числовые коды нужных событий. Можно указать несколько кодов в одном массиве.
• SecretToken — необязательный секрет для проверки отправителя. Если он задан, Clinica Web передаёт его в заголовке X-ClinicaWeb-Token. Это отдельное значение, не access_token; храните его в секрете и проверяйте на стороне получателя.

Успешный ответ — HTTP 200 с идентификатором подписки (GUID). Сохраните его. GET /api/webhooks возвращает подписки вашего API-клиента; GET /api/webhooks/{id} — отдельную подписку; PUT /api/webhooks/{id} изменяет её, а DELETE /api/webhooks/{id} удаляет. Применение изменений может занять до 5 минут.

Доступные события

В запросе на подписку используйте числовой код из списка. Фактическая доступность событий зависит от версии вашей среды.

Предварительная запись и пациент

• 0 — PrerecordCreated: создана предварительная запись.
• 1 — PrerecordDeleted: удалена предварительная запись.
• 2 — PrerecordUpdated: изменена предварительная запись.
• 3 — PatientCreated: создан пациент.
• 4 — PatientUpdated: обновлены данные пациента.

Заказы, фискализация и протокол

• 5 — OrderAdded: оформлен заказ.
• 6 — OrderUpdated: обновлён оформленный заказ.
• 7 — OrderDeleted: удалены оформленные услуги. В проверенной реализации удаление обрабатывается как OrderUpdated (6), поэтому не полагайтесь только на подписку на код 7.
• 8 — Fiscalization: выполнена фискализация или возврат чека.
• 9 — ProtocolUpdated: сохранены изменения протокола.

Сообщения по заказу и фискализации отправляются, когда в них есть позиции.

Рекомендованные услуги и назначения в протоколе

• 10 — ReferralSalepackPackageCreated: добавлена рекомендованная услуга.
• 11 — ReferralSalepackPackageDeleted: удалена рекомендованная услуга.
• 12 — ReferralSalepackPackageUpdated: изменена рекомендованная услуга.
• 13 — ProtocolDrugCreated: добавлено назначение препарата.
• 14 — ProtocolDrugDeleted: удалено назначение препарата.
• 15 — ProtocolDrugUpdated: изменено назначение препарата.
• 16 — ProtocolMonitoringAssignmentCreated: добавлено назначение мониторинга показателя.
• 17 — ProtocolMonitoringAssignmentDeleted: удалено назначение мониторинга показателя.
• 18 — ProtocolMonitoringAssignmentUpdated: изменено назначение мониторинга показателя.

События 13–18 охватывают операции с назначениями через ERP API; изменения через устаревшие механизмы или OData и изменения справочника показателей не порождают эти события.

Что получает ваш сервер

В JSON поле Trigger содержит код события, а соответствующее поле — данные объекта: Prerecord, Patient, Order, Protocol, ReferralSalepackPackage, ProtocolDrug или ProtocolMonitoringAssignment. Поля, не связанные с событием, могут отсутствовать. Схему запроса можно посмотреть в Swagger в операции POST /api/webhooks/dummy; это пример схемы, а не адрес вашего получателя.

Для части событий данные считываются в фоновом режиме и могут отражать состояние на момент обработки, а не точное состояние в момент события. Для удаления рекомендованной услуги, препарата или мониторинга может передаваться удалённая запись с соответствующим признаком удаления.

При некоторых сетевых ошибках или ответах сервера выполняются повторные попытки. Подготовьте обработчик к повторному получению сообщения. После создания подписки проверьте её на тестовом событии и убедитесь, что ваш сервер получил запрос и вернул успешный ответ. Сообщения могут содержать данные пациентов — защищайте их и доступ к ним.