API призначень та вебхуки

Публічне API Clinica Web для роботи з призначеннями у протоколі пацієнта: ліками, послугами та моніторингом. REST API дає змогу читати, створювати, змінювати й видаляти призначення; вебхуки повідомляють зовнішню систему про збережені зміни.

Swagger: усі методи · схема вхідного вебхука · OpenAPI JSON.

Зміст

• Підключення та формат даних
• Призначення ліків
• Призначення послуг
• Призначення моніторингу
• Розклад ліків і моніторингу
• Довідники для заповнення полів
• Вебхуки призначень
• Помилки та практичний порядок інтеграції

Підключення та формат даних

Приклади використовують базову адресу https://{client}.medakadem.com.ua.  Ідентифікатори пацієнтів, протоколів, послуг і призначень належать базі цього екземпляра.

Для зовнішніх викликів передавайте Authorization: Bearer <access_token>. Запити з тілом мають Content-Type: application/json. Отримання й використання токена описані в інструкціях отримання токена та використання токена, на які посилається Swagger.

Scope	Для чого потрібен
gambit:public:patient:read	Читання призначень ліків, послуг і моніторингу у протоколі; читання моніторингу пацієнта.
gambit:public:patient:write	Створення, зміна та видалення призначень у протоколі.
gambit:webhooks	Керування підписками на вебхуки та виклик демонстраційного методу.
gambit:static_data	Довідник показників моніторингу, пошук ліків і довідники форм та одиниць.
gambit:erp:packages	Отримання каталогу послуг.
gambit:erp	Додаткові методи читання направлення за ID і направлень пацієнта.

У шляхах нижче patientId — ID пацієнта, protocolId — ID протоколу, protocolDrugId — ID призначення ліків, assignmentId — ID призначення моніторингу, referralSalepackPackageId — ID призначеної послуги. Це цілі числа. Для створення протокол має існувати та належати зазначеному пацієнту. ID підписки на вебхук має формат UUID.

Регістр JSON є частиною контракту. Ліки та вкладені об’єкти ліків використовують camelCase. Послуги, моніторинг, підписки та оболонка вебхука використовують PascalCase. Усередині ProtocolDrug у вебхуку зберігається camelCase.

Переліки значень. Для розкладу, зв’язку з їжею, правил нагадування, додаткових умов і PackageType використовуйте рядкові назви, наведені далі. Для Trigger, Triggers, AssuranceAproveState, Status і removeReasonId використовуйте числові коди.

Дата з часом передається в ISO 8601, наприклад 2026-11-02T09:00:00+02:00; локальний час нагадування — як 08:00:00. Значення null і пропуск поля не означають часткове оновлення: правила конкретного PUT наведені в розділах нижче.

Призначення ліків

Основний шлях: /api/erp/v1/patients/{patientId}/protocol/{protocolId}/drugs. Методи читання потребують gambit:public:patient:read, зміни — gambit:public:patient:write.

HTTP і суфікс шляху	Результат	Swagger
GET без суфікса	200: масив ERPProtocolDrugDto; 404, якщо протокол не належить пацієнту або відсутній.	GetProtocolDrugs
POST без суфікса	201: створене призначення ERPProtocolDrugDto і заголовок Location; 400, 404.	CreateProtocolDrug
PUT /{protocolDrugId}	200 без тіла; 400, 404.	UpdateProtocolDrug
DELETE /{protocolDrugId}	204 без тіла; 404.	DeleteProtocolDrug

Поля запиту на створення

Поле	Тип і обов’язковість	Опис
drug	object, обов’язкове	Ліки з локального довідника або дані для створення локального запису. Поля наведені нижче.
description	string або null	Коментар до призначення, до 500 символів.
assignmentDetails	object, обов’язкове	Дозування та розклад.

Поле drug	Тип	Опис і значення
id	integer	ID локального запису ліків.
pharmacyId	UUID	Ідентифікатор каталогу ліків.
name	string, обов’язкове	Назва ліків, непорожня, до 300 символів; потрібна й при передаванні ID.
component	string або null	Діюча речовина або склад.
atxCode	string або null	ATC/АТХ-код. Назва JSON-поля саме atxCode.
dosage	string або null	Текстове дозування препарату в довіднику.
dosageUnit	string або null	Одиниця дозування препарату в довіднику.
medicationForm	string або null	Форма препарату в довіднику.
manufacture	string або null	Виробник. Назва JSON-поля саме manufacture.

Якщо ліки за вибраним ідентифікатором не знайдено, сервіс створює запис із переданих даних drug. Для повторного використання ліків передавайте відомий id або pharmacyId; не використовуйте пошук за невідомим ID як перевірку існування.

Дозування та розклад ліків

Поле assignmentDetails	Тип і обов’язковість	Опис і обмеження
medicationForm	string або null	Код форми з MEDICATION_FORM, до 100 символів.
dosageAmount	number або null	Кількість на прийом; якщо задана, має бути > 0.
dosageUnit	string або null	Код одиниці з MEDICATION_UNIT, до 100 символів. Обов’язкова непорожня одиниця, якщо задано dosageAmount.
mealRelation	string enum або null	Unspecified, BeforeMeal, WithMeal, AfterMeal, Irrelevant; значення розшифровані в розділі переліків.
schedule	object, обов’язкове	Розклад. У ліків усі його поля мають camelCase; повний перелік наведений у спільному розділі розкладу.

Зміна та відповідь API

PUT приймає description, обов’язковий assignmentDetails та необов’язковий drugName. description і assignmentDetails замінюють поточні значення; для зміни лише назви також передайте актуальний розклад. drugName: null або пропуск поля залишає назву без змін. Непорожня назва до 300 символів перейменовує локальні ліки після обрізання пробілів. Каталожні ліки з ненульовим pharmacyId не перейменовуються: сервер повертає 400 з кодом catalog_drug_rename. Якщо локальні ліки використовуються іншими призначеннями, створюється окрема копія для цього призначення.

Поле ERPProtocolDrugDto	Тип	Опис
id	integer	ID призначення; відрізняється від drug.id.
patientId	integer	ID пацієнта.
protocolId	integer	ID протоколу.
del	boolean	Ознака логічного видалення. REST-список приховує видалені призначення; вебхук видалення містить true.
drug	object	Об’єкт ліків із наведеними вище полями.
description	string або null	Збережений коментар.
assignmentDetails	object або null	Дозування та розклад; у старих записів можуть бути відсутні структуровані деталі.
daysCount, perDayCount	integer	Поля сумісності для тривалості та кількості прийомів. Нові запити їх не приймають; використовуйте assignmentDetails.schedule.
dose	string або null	Текстове дозування для сумісності. Нові запити його не приймають; використовуйте структуровані поля дозування.

Приклад створення ліків

POST /api/erp/v1/patients/7/protocol/42/drugs. Ідентифікатори та назва нижче демонстраційні.

{
  "drug": {
    "id": 0,
    "pharmacyId": "00000000-0000-0000-0000-000000000000",
    "name": "Демонстраційний препарат",
    "component": null,
    "atxCode": null,
    "dosage": null,
    "dosageUnit": null,
    "medicationForm": null,
    "manufacture": null
  },
  "description": "Демонстраційний коментар",
  "assignmentDetails": {
    "medicationForm": null,
    "dosageAmount": 1,
    "dosageUnit": "PIECE",
    "mealRelation": "AfterMeal",
    "schedule": {
      "frequency": "Daily",
      "weekdays": [],
      "intervalValue": null,
      "intervalUnit": null,
      "cycleActiveDays": null,
      "cyclePauseDays": null,
      "multiplicity": "Twice",
      "everyHours": null,
      "reminders": [
        {
          "time": "08:00:00",
          "dosageAmount": 1,
          "dosageUnit": "PIECE"
        },
        {
          "time": "20:00:00",
          "dosageAmount": 1,
          "dosageUnit": "PIECE"
        }
      ],
      "durationDays": 7
    }
  }
}

Призначення послуг

Основний шлях: /api/erp/v1/patients/{patientId}/protocol/{protocolId}/referralSalepackPackages. Методи читання потребують gambit:public:patient:read, зміни — gambit:public:patient:write. Послуга прив’язується до вихідної замовленої послуги протоколу.

HTTP і суфікс шляху	Результат	Swagger
GET без суфікса	200: масив повних ERPReferralSalepackPackage; Swagger також декларує 404.	GetProtocolServices
POST без суфікса	201: SavedERPReferralSalepackPackage і Location; 400, 404.	CreateProtocolService
PUT /{referralSalepackPackageId}	200: SavedERPReferralSalepackPackage; 400, 404.	UpdateProtocolService
DELETE /{referralSalepackPackageId}	204 без тіла; необов’язковий query-параметр removeReasonId; 400, 404.	DeleteProtocolService

Поля створення та зміни послуги

Поле	Тип і обов’язковість	Опис і значення
ProtocolId	integer, обов’язкове, > 0	Має точно збігатися з protocolId у шляху. Незбіг дає 400 з помилкою ProtocolId.
PackageId	integer, обов’язкове, > 0	ID доступної послуги з каталогу. При створенні недоступна послуга дає 400. PUT не змінює послугу на іншу: передавайте поточний ID; для іншої послуги створіть нове призначення.
AssuranceAproveState	integer enum	Стан погодження страховою: 0 NONE, 1 REJECTED, 2 APROVED, 3 PARTIALLY. Якщо пропущено, значення 0.
TargetDate	date-time або null	Планова дата послуги; не є датою нагадування.
RecommendationDetails	object або null	Умови рекомендації та нагадування. При PUT null або пропуск зберігає наявні деталі; переданий об’єкт замінює їх.

Поле RecommendationDetails	Тип	Опис і умови
ReminderRule	string enum	SpecificDate, DaysAfterMedication, NoDate, TreatmentDay. Типове значення при пропуску в об’єкті — NoDate; Unspecified не допускається валідатором.
ReminderDate	date-time або null	Обов’язкове для SpecificDate.
DaysAfterMedication	integer або null	Кількість днів після приймання ліків; обов’язкове > 0 для DaysAfterMedication.
TreatmentDay	integer або null	День лікування; обов’язкове > 0 для TreatmentDay.
AdditionalCondition	string enum або null	Fasting, OneHourBeforeMeal, OneHourAfterMeal, WithMeal, Other; Unspecified не допускається.
AdditionalConditionText	string або null	Непорожній текст для умови Other; під час збереження обрізаються пробіли.
Recipient	string або null	Адресат рекомендації; під час збереження обрізаються пробіли.

Зберігається лише дата або числовий параметр, що відповідає вибраному ReminderRule; решта скидається в null. AdditionalConditionText зберігається лише для Other. У PUT надсилайте актуальні ProtocolId, PackageId, AssuranceAproveState і TargetDate: пропущений TargetDate стає null, а пропущений стан погодження — 0.

removeReasonId передається в query при DELETE: 0 — CorrectionOfAppointments (корекція призначень), 1 — PatientRefusal (відмова пацієнта), 2 — AlreadyDone (вже виконано). Причину можна не передавати.

Поля відповіді послуги

Відповіді POST і PUT мають тип SavedERPReferralSalepackPackage: усі поля редагування та Id — ID збереженого призначення. GET і вебхуки повертають повний ERPReferralSalepackPackage, який додатково містить наведені нижче поля.

Додаткове поле	Тип	Опис
PackageCode	string або null	Код послуги з каталогу.
PackageName	string або null	Назва послуги.
PackageType	string enum	Group, Protocol, Analize, MaterialSale.
Status	integer enum	0 None, 1 PatientRefusal, 2 AlreadyDone, 3 RemindedLater, 4 NotReachedByPhone.
PatientId	integer	ID пацієнта.
SourceDiscoveryId	integer	ID лікаря або користувача, який видав направлення.
SourcePrerecordId	integer або null	ID вихідного запису на прийом, під час якого виникла рекомендація.
SourceSalepackId	integer	ID вихідної замовленої послуги.
SourceSalepackCreatedAt	date-time	Дата створення вихідної замовленої послуги.
CreatedAt	date-time	Дата створення призначення.
PrerecordId	integer або null	ID запису на прийом, створеного на підставі призначення.
SalepackIds	array of integer	ID замовлених послуг, створених на підставі призначення.

Приклад створення послуги

POST /api/erp/v1/patients/7/protocol/42/referralSalepackPackages. PackageId потрібно замінити на реальний ID каталогу.

{
  "ProtocolId": 42,
  "PackageId": 101,
  "AssuranceAproveState": 0,
  "TargetDate": "2026-11-02T09:00:00+02:00",
  "RecommendationDetails": {
    "ReminderRule": "SpecificDate",
    "ReminderDate": "2026-11-01T10:00:00+02:00",
    "DaysAfterMedication": null,
    "TreatmentDay": null,
    "AdditionalCondition": "Other",
    "AdditionalConditionText": "Демонстраційна умова",
    "Recipient": "Пацієнт"
  }
}

Додаткове читання направлень

Метод і шлях	Відповідь та доступ	Swagger
GET /api/erp/v1/referral-salepack-package/{id}	Повний ERPReferralSalepackPackage; scope gambit:erp.	GetReferral
GET /api/public/v1/patients/{id}/referral-salepack-packages	Масив повних направлень пацієнта; scope gambit:erp.	GetPatientReferrals

Призначення моніторингу

Основний шлях: /api/erp/v1/patients/{patientId}/protocol/{protocolId}/monitoring-assignments. Читання потребує gambit:public:patient:read, зміни — gambit:public:patient:write. Призначення визначає показник і розклад спостереження; збереження розкладу саме по собі не надсилає пацієнту нагадування.

HTTP і суфікс шляху	Результат	Swagger
GET без суфікса	200: масив ERPProtocolMonitoringAssignment.	GetProtocolMonitoringAssignments
GET /{assignmentId}	200: одне призначення; 404.	GetProtocolMonitoringAssignment
POST без суфікса	201: створене призначення і Location; 400, 404.	CreateProtocolMonitoringAssignment
PUT /{assignmentId}	200 без тіла; 400, 404.	UpdateProtocolMonitoringAssignment
DELETE /{assignmentId}	204 без тіла; 404.	DeleteProtocolMonitoringAssignment
GET /api/erp/v1/patients/{patientId}/monitoring-assignments — повний шлях	200: масив призначень пацієнта з різних протоколів.	GetPatientMonitoringAssignments

Поля моніторингу

Поле запиту	Тип і обов’язковість	Опис
MonitoringIndicatorId	integer, обов’язкове для POST, > 0	ID показника з довідника моніторингу. У PUT цього поля немає; PUT змінює лише розклад.
ScheduleDetails	object, обов’язкове для POST і PUT	Розклад із полями PascalCase, описаними далі. PUT повністю замінює розклад.

Поле відповіді	Тип	Опис
Id	integer	ID призначення моніторингу.
PatientId	integer	ID пацієнта.
ProtocolId	integer	ID протоколу.
Del	boolean	Ознака логічного видалення. Видалені записи приховані в REST-читанні; вебхук видалення містить true.
MonitoringIndicatorId	integer	ID показника.
MonitoringIndicatorName	string або null	Назва показника.
MonitoringIndicatorUnit	string або null	Код одиниці показника з eHealth/ucum/units, до 255 символів. Використовується для відображення.
ScheduleDetails	object	Збережений розклад. Нагадування містять лише час, без дозування.

Приклад створення моніторингу

POST /api/erp/v1/patients/7/protocol/42/monitoring-assignments. MonitoringIndicatorId потрібно замінити на реальний ID показника.

{
  "MonitoringIndicatorId": 30,
  "ScheduleDetails": {
    "Frequency": "SpecificWeekdays",
    "Weekdays": [
      "Monday",
      "Wednesday",
      "Friday"
    ],
    "IntervalValue": null,
    "IntervalUnit": null,
    "CycleActiveDays": null,
    "CyclePauseDays": null,
    "Multiplicity": "Once",
    "EveryHours": null,
    "Reminders": [
      {
        "Time": "08:00:00"
      }
    ],
    "DurationDays": 14
  }
}

Розклад ліків і моніторингу

Розклад має однакові основні поняття, але різний регістр назв полів. У ліків він міститься в assignmentDetails.schedule, у моніторингу — в ScheduleDetails. frequency або Frequency задає дні виконання; multiplicity або Multiplicity — кратність протягом дня.

Поле ліків	Поле моніторингу	Тип і правила
frequency	Frequency	Рядковий DoctorAssignmentFrequency. Явно передавайте потрібне значення; при пропуску типове значення Unspecified.
weekdays	Weekdays	Масив рядкових DoctorAssignmentWeekday; типово [], null не допускається. Для SpecificWeekdays потрібен непорожній масив унікальних днів. У моніторингу Unspecified не допускається як день.
intervalValue	IntervalValue	integer або null; для Interval обов’язкове > 0.
intervalUnit	IntervalUnit	Рядковий DoctorAssignmentIntervalUnit або null; для Interval обов’язкове. У моніторингу Unspecified не допускається.
cycleActiveDays	CycleActiveDays	integer або null; для частоти RepeatingCycle обов’язкове > 0.
cyclePauseDays	CyclePauseDays	integer або null; для частоти RepeatingCycle обов’язкове ≥ 0.
multiplicity	Multiplicity	Рядковий DoctorAssignmentMultiplicity; при пропуску Unspecified.
everyHours	EveryHours	integer або null; для кратності EveryHours обов’язкове > 0.
reminders	Reminders	Масив нагадувань, типово []. У моніторингу null і null-елементи не допускаються. Формати елементів наведені нижче.
durationDays	DurationDays	integer або null; якщо задане, > 0.

Числові параметри розкладу зберігаються як short: позитивні значення мають бути в межах 1–32767; для паузи допустимий також 0. Swagger відображає їх як integer/int32.

Для моніторингу сервер залишає лише параметри вибраної частоти: дні тижня для SpecificWeekdays, інтервал для Interval, активні дні та паузу для RepeatingCycle. EveryHours зберігається лише при однойменній кратності. Інші залежні параметри очищуються. Передавайте лише параметри, які відповідають вибраному розкладу.

Нагадування	Поле	Тип і значення
Ліки	time	Локальний час, наприклад 08:00:00.
Ліки	dosageAmount	number або null; кількість для цього часу прийому.
Ліки	dosageUnit	string або null; код одиниці для цього часу прийому.
Моніторинг	Time	Обов’язковий локальний час із точністю до хвилини: 08:00:00; секунди й частки секунди мають бути нульовими.

Частота виконання

JSON значення	Код enum	Значення
"Unspecified"	0	Не визначено.
"Daily"	1	Щодня.
"EveryOtherDay"	2	Через день.
"SpecificWeekdays"	3	У вибрані дні тижня.
"RepeatingCycle"	4	Повторюваний цикл активних днів і паузи.
"Interval"	5	Через заданий інтервал.
"AsNeeded"	6	За потреби.

Дні тижня та одиниці інтервалу

Перелік	JSON значення і відповідні коди
DoctorAssignmentWeekday	"Unspecified" = 0; "Monday" = 1; "Tuesday" = 2; "Wednesday" = 3; "Thursday" = 4; "Friday" = 5; "Saturday" = 6; "Sunday" = 7.
DoctorAssignmentIntervalUnit	"Unspecified" = 0; "Day" = 1; "Week" = 2; "Month" = 3.

Коди в цьому розділі пояснюють enum. У JSON-полях розкладу та елементах масиву днів використовуйте рядкові назви.

Кратність протягом дня

JSON значення	Код enum	Значення
"Unspecified"	0	Не визначено.
"Once"	1	Один раз.
"Twice"	2	Двічі.
"ThreeTimes"	3	Тричі.
"MoreThanThree"	4	Більше трьох разів.
"EveryHours"	5	Кожні N годин; потрібне everyHours або EveryHours.
"RepeatingCycle"	6	Повторювана кратність. Параметри активних днів і паузи належать до частоти RepeatingCycle.
"AsNeeded"	7	За потреби.

Зв’язок приймання ліків із їжею

mealRelation у JSON	Код enum	Значення
"Unspecified"	0	Не визначено.
"BeforeMeal"	1	До їжі.
"WithMeal"	2	Під час їжі.
"AfterMeal"	3	Після їжі.
"Irrelevant"	4	Незалежно від їжі.
null	—	Зв’язок не заданий.

Правила нагадування послуги

ReminderRule у JSON	Код enum	Значення
"Unspecified"	0	Значення enum; нові запити його не приймають.
"SpecificDate"	1	На конкретну дату ReminderDate.
"DaysAfterMedication"	2	Через DaysAfterMedication днів після приймання ліків.
"NoDate"	3	Без визначеної дати; типове значення.
"TreatmentDay"	4	На TreatmentDay день лікування.

AdditionalCondition у JSON	Код enum	Значення
"Unspecified"	0	Значення enum; у запиті використовуйте null, якщо умови немає.
"Fasting"	1	Натщесерце.
"OneHourBeforeMeal"	2	За годину до їжі.
"OneHourAfterMeal"	3	Через годину після їжі.
"WithMeal"	4	Під час їжі.
"Other"	5	Інша умова; потрібний AdditionalConditionText.

Типи та статуси послуг

Поле	Значення
PackageType — рядок	"Group" = 0 — група; "Protocol" = 1 — протокол/консультаційна послуга; "Analize" = 2 — аналіз; "MaterialSale" = 3 — продаж матеріалів. Назва "Analize" зберігається саме в такому написанні.
AssuranceAproveState — число	0 NONE — без погодження; 1 REJECTED — відхилено; 2 APROVED — погоджено; 3 PARTIALLY — погоджено частково. Назви Aprove і APROVED відповідають контракту.
Status — число	0 None — без окремого статусу; 1 PatientRefusal — відмова пацієнта; 2 AlreadyDone — вже виконано; 3 RemindedLater — нагадати пізніше; 4 NotReachedByPhone — не додзвонилися.

Довідники для заповнення полів

Коди форм та одиниць потрібно брати з відповідного довідника, передавати саме код, а не перекладену назву.

Метод	Призначення	Swagger
GET /api/erp/v1/drugs?search={text}	Пошук локальних ліків. Повертає масив DrugDto; scope gambit:static_data.	SearchDrugs
GET /api/erp/v1/drugs/catalog/search?search={text}	Пошук ліків у каталозі з відповіддю DrugDto[]; scope gambit:static_data.	SearchCatalogDrugs
GET /api/erp/v1/packages	Каталог послуг для вибору PackageId; scope gambit:erp:packages.	GetPackages
GET /api/v2/dictionaries/{name}	Довідники MEDICATION_FORM для форми та MEDICATION_UNIT для одиниці дозування; scope gambit:static_data.	GetAppDictionariesByName
GET /api/erp/v1/monitoring-indicators?q={text}	Список показників моніторингу; необов’язковий пошук q; scope gambit:static_data.	GetMonitoringIndicators
GET /api/erp/v1/monitoring-indicators/{id}	Один показник моніторингу; 200 або 404; scope gambit:static_data.	GetMonitoringIndicator

DrugDto описаний у розділі ліків. Об’єкт показника моніторингу має Id (integer), Name (непорожній string, до 500 символів після обрізання пробілів) і Unit (string або null, до 255 символів). Приклад коду одиниці моніторингу — mm[Hg].

Керування довідником моніторингу

Для зовнішнього API потрібен scope gambit:static_data. Тіло POST і PUT: { "Name": "Демонстраційний показник", "Unit": "mm[Hg]" }.

Метод	Результат	Swagger
POST /api/erp/v1/monitoring-indicators	201: показник; 400 — валідація; 409 — конфлікт.	CreateMonitoringIndicator
PUT /api/erp/v1/monitoring-indicators/{id}	200: показник; 400, 404, 409.	UpdateMonitoringIndicator
DELETE /api/erp/v1/monitoring-indicators/{id}	204 без тіла; 404.	DeleteMonitoringIndicator

Вебхуки призначень

Зовнішня система реєструє URL свого обробника та потрібні тригери через /api/webhooks. Clinica Web надсилає на цей URL HTTP POST із JSON-об’єктом WebhookUpdateEvent. Для керування підписками потрібен scope gambit:webhooks.

Основне посилання: приклад обробника та схема WebhookUpdateEvent у Swagger. Метод /api/webhooks/dummy є демонстрацією контракту; для інтеграції в Uri потрібно вказати URL власного сервісу.

Методи керування підписками

Метод	Відповідь	Swagger
GET /api/webhooks	200: масив підписок поточного API-клієнта WebhookDescription[].	GetWebhooks
GET /api/webhooks/{id}	200: WebhookDetails; 404.	GetWebhookById
POST /api/webhooks	200: UUID створеної підписки; 400 — валідація.	CreateWebhook
PUT /api/webhooks/{id}	200 без тіла; 400, 404 за Swagger.	UpdateWebhook
DELETE /api/webhooks/{id}	200 без тіла. Swagger також декларує 404.	DeleteWebhook
POST /api/webhooks/dummy	Демонстраційний приймач WebhookUpdateEvent; повертає 200.	HandleExampleWebhook

При видаленні підписки поточна реалізація повертає 200 також тоді, коли не знайдено підписку цього клієнта; такий результат не підтверджує, що запис існував.

Поле POST і PUT	Тип і обов’язковість	Опис
Uri	URI string, обов’язкове	Адреса обробника у зовнішній системі. Для інтеграції використовуйте повну HTTPS-адресу.
Triggers	array of integer, обов’язковий непорожній масив	Коди подій, на які підписується зовнішня система. Для всіх змін призначень — 10–18.
SecretToken	string або null	Необов’язковий секрет до 255 символів. При доставці передається в заголовку X-ClinicaWeb-Token.

PUT підписки передає весь набір Uri, Triggers, SecretToken; пропуск секрету прибирає його значення. Зміни підписок можуть поширюватися між процесами до 5 хвилин.

Додаткове поле відповіді	Де повертається	Опис
Id	Список і деталі	UUID підписки.
LastErrorMessage	Лише деталі	Текст збереженої останньої помилки або null.
LastErrorDate	Лише деталі	Дата збереженої останньої помилки або null.

Список і деталі також містять Uri, Triggers і SecretToken. Обмежуйте доступ до відповідей із секретом так само, як до конфігурації інтеграції.

Приклад підписки на всі зміни призначень

POST https://dev.medakadem.com.ua/api/webhooks з Bearer-токеном зі scope gambit:webhooks:

{
  "Uri": "https://integration.example.com/webhooks/clinica-assignments",
  "Triggers": [
    10,
    11,
    12,
    13,
    14,
    15,
    16,
    17,
    18
  ],
  "SecretToken": "REPLACE_WITH_YOUR_SECRET"
}

Сервер повертає UUID як JSON-рядок, наприклад "11111111-1111-4111-8111-111111111111". Збережіть його для читання, зміни або видалення підписки.

Події призначень

Код Trigger	Назва події	Заповнене поле
10	ReferralSalepackPackageCreated — створено послугу	ReferralSalepackPackage
11	ReferralSalepackPackageDeleted — видалено послугу	Контракт передбачає ReferralSalepackPackage; поточне обмеження доставки описане нижче.
12	ReferralSalepackPackageUpdated — змінено послугу	ReferralSalepackPackage
13	ProtocolDrugCreated — створено призначення ліків	ProtocolDrug
14	ProtocolDrugDeleted — видалено призначення ліків	ProtocolDrug
15	ProtocolDrugUpdated — змінено призначення ліків	ProtocolDrug
16	ProtocolMonitoringAssignmentCreated — створено моніторинг	ProtocolMonitoringAssignment
17	ProtocolMonitoringAssignmentDeleted — видалено моніторинг	ProtocolMonitoringAssignment
18	ProtocolMonitoringAssignmentUpdated — змінено моніторинг	ProtocolMonitoringAssignment

Оболонка повідомлення

Поле WebhookUpdateEvent	Тип	Коли заповнюється
Trigger	integer enum, обов’язкове	Код події.
ProtocolDrug	ERPProtocolDrugDto	Тригери 13–15. Поля всередині мають camelCase; повна схема описана в розділі ліків.
ProtocolMonitoringAssignment	ERPProtocolMonitoringAssignment	Тригери 16–18. Поля всередині мають PascalCase.
ReferralSalepackPackage	ERPReferralSalepackPackage	Тригери 10 і 12; для 11 є обмеження доставки. Повна модель послуги, включно з вихідними даними та пов’язаними записами.
Prerecord, Patient, Order, Protocol	Інші об’єкти WebhookUpdateEvent	Для інших типів подій, перелічених нижче.

Повідомлення призначення містить Trigger і відповідний об’єкт. Незадіяні payload-поля з null пропускаються. Для ідентифікації використовуйте ID призначення, пацієнта та протоколу з payload; не ототожнюйте ID призначення ліків з ID запису drug або ID призначеної послуги з PackageId.

Приклад повідомлення про зміну ліків

На власний обробник надходять заголовки Content-Type: application/json і, якщо задано секрет, X-ClinicaWeb-Token: REPLACE_WITH_YOUR_SECRET.

{
  "Trigger": 15,
  "ProtocolDrug": {
    "id": 10,
    "patientId": 7,
    "protocolId": 42,
    "del": false,
    "drug": {
      "id": 55,
      "pharmacyId": "00000000-0000-0000-0000-000000000000",
      "name": "Демонстраційний препарат",
      "component": null,
      "atxCode": null,
      "dosage": null,
      "dosageUnit": null,
      "medicationForm": null,
      "manufacture": null
    },
    "description": "Демонстраційний коментар",
    "assignmentDetails": {
      "medicationForm": null,
      "dosageAmount": 1,
      "dosageUnit": "PIECE",
      "mealRelation": "AfterMeal",
      "schedule": {
        "frequency": "Daily",
        "weekdays": [],
        "intervalValue": null,
        "intervalUnit": null,
        "cycleActiveDays": null,
        "cyclePauseDays": null,
        "multiplicity": "Twice",
        "everyHours": null,
        "reminders": [
          {
            "time": "08:00:00",
            "dosageAmount": 1,
            "dosageUnit": "PIECE"
          },
          {
            "time": "20:00:00",
            "dosageAmount": 1,
            "dosageUnit": "PIECE"
          }
        ],
        "durationDays": 7
      }
    },
    "daysCount": 0,
    "perDayCount": 0,
    "dose": null
  }
}

Приклад повідомлення про видалення моніторингу

{
  "Trigger": 17,
  "ProtocolMonitoringAssignment": {
    "ScheduleDetails": {
      "Frequency": "SpecificWeekdays",
      "Weekdays": [
        "Monday",
        "Wednesday",
        "Friday"
      ],
      "IntervalValue": null,
      "IntervalUnit": null,
      "CycleActiveDays": null,
      "CyclePauseDays": null,
      "Multiplicity": "Once",
      "EveryHours": null,
      "Reminders": [
        {
          "Time": "08:00:00"
        }
      ],
      "DurationDays": 14
    },
    "Id": 20,
    "PatientId": 7,
    "ProtocolId": 42,
    "Del": true,
    "MonitoringIndicatorId": 30,
    "MonitoringIndicatorName": "Демонстраційний показник",
    "MonitoringIndicatorUnit": "mm[Hg]"
  }
}

Для видалення ліків аналогічно надходить Trigger: 14 та ProtocolDrug.del: true.

Доставка та обробка

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

Таймаут одного HTTP-запиту доставки — 10 секунд. Реалізація налаштована на до 10 повторних спроб після початкової, із затримкою 1 секунда. Повтори застосовуються до винятків і відповідей 408, 429, 500, 502, 503, 504, 521, 522, 524. Інші помилкові HTTP-коди ця політика не повторює.

Інші доступні значення Trigger

Ці значення належать до спільного механізму вебхуків. Їх можна додати до Triggers, якщо інтеграції потрібні відповідні об’єкти; схеми цих об’єктів доступні за основним посиланням на приклад обробника у Swagger.

Код	Подія	Payload
0	PrerecordCreated	Prerecord
1	PrerecordDeleted	Prerecord
2	PrerecordUpdated	Prerecord
3	PatientCreated	Patient
4	PatientUpdated	Patient
5	OrderAdded	Order
6	OrderUpdated	Order
7	OrderDeleted	Order
8	Fiscalization	Order
9	ProtocolUpdated — збереження протоколу	Protocol

Помилки та практичний порядок інтеграції

HTTP-код	Як трактувати
200	Успішне читання або зміна; тип тіла залежить від методу. Створення підписки теж повертає 200.
201	Призначення або показник створено. Для призначень повертається об’єкт і Location.
204	Призначення або показник видалено; тіло відсутнє.
400	Помилка структури або валідації, невідповідність протоколу, недоступна послуга чи заборонене перейменування каталожних ліків. Читайте тіло помилки.
401 / 403	Перевірте токен, scope і доступ до ресурсу.
404	Конкретний ресурс або потрібна відповідність ідентифікаторів не знайдені. Для порожніх списків можливий 200 з []; точні коди наведені біля методів.
409	Конфлікт під час збереження показника моніторингу.

Для помилок валідації використовується application/problem+json із масивами повідомлень у errors. Приклад відповіді при незбігу ProtocolId:

{
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "ProtocolId": [
      "ProtocolId must match the route."
    ]
  }
}