Початок роботи з 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; це приклад схеми, а не адреса вашого отримувача.

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

У разі деяких помилок мережі або відповідей сервера виконуються повторні спроби. Зробіть обробник готовим до повторного отримання повідомлення. Після створення підписки перевірте її на тестовій події та переконайтеся, що ваш сервер отримав запит і повернув успішну відповідь. Повідомлення можуть містити дані пацієнтів — захищайте їх і доступ до них.