SmengoAPI

Події

У v1 доступні чотири події. Кожна надходить у спільному конверті — тут описано лише те, що відрізняється: склад data, наявність посилання related і право, потрібне для підписки.

Каталог

Подія Коли виникає Склад data related
schedule.published менеджер опублікував місяць графіка month, published_at немає
schedule_entry.changed зміну створили, змінили або видалили — будь-яким шляхом action, entry_id, employee_id, entry_date є, крім action: "deleted"
checkin.recorded співробітник відмітив прихід або вихід у боті check_in_id, employee_id, entry_date, kind є
swap.decided менеджер схвалив або відхилив заявку на заміну request_id, employee_id, entry_date, decision немає

Службова подія ping (кнопка «Надіслати тестову») до каталогу не входить: підписатися на неї не можна, а надходить вона в тому самому конверті, що й решта подій, — із data: {"test": true} усередині (див. приклад).

Право на підписку

Підписка на подію потребує того самого права, яким гейтиться перегляд цих даних в інтерфейсі Smengo. Правило те саме, що й у скоупів API-ключа: події ендпоінта — підмножина прав того, хто його створив.

Подія Право у творця ендпоінта Той самий гейт у застосунку
schedule.published «Переглядати графік» грид /schedule
schedule_entry.changed «Переглядати графік» грид /schedule
checkin.recorded «Керувати працівниками» розділ «Чекіни»
swap.decided «Керування змінами» рішення щодо заявок на заміну

Право «Налаштування організації» (manage_org) дозволяє заводити й видаляти вебхуки, але саме по собі не дає жодної підписки. Недоступні події вимкнені у формі; спроба обійти форму відбивається й на рівні бази.

schedule.published

Публікація місяця графіка. Одна публікація — одна подія.

{
  "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "type": "schedule.published",
  "created": "2026-07-28T14:03:11.902Z",
  "sequence": 10201,
  "org_id": "9c1a2e34-5678-4abc-9def-0123456789ab",
  "api_version": "v1",
  "data": {
    "month": "2026-08-01",
    "published_at": "2026-07-28T14:03:11.884+00:00"
  }
}
  • month — перше число опублікованого місяця у форматі YYYY-MM-DD: рядок можна одразу підставити в from запиту до API.
  • published_at — момент публікації, ISO 8601 зі зміщенням.
  • related немає: GET-ресурсу публікацій в API v1 не існує. За вмістом ідіть у GET /schedule-entries з діапазоном на місяць із month.

schedule_entry.changed

Зміну створено, змінено або видалено — гридом, застосуванням чернетки, ботом, видаленням працівника назавжди (каскадне видалення породжує deleted на кожну його зміну).

{
  "id": "3f1c8b52-9a4d-4f7e-b2c1-8e5d0a6b4c39",
  "type": "schedule_entry.changed",
  "created": "2026-08-01T09:15:23.481Z",
  "sequence": 10427,
  "org_id": "9c1a2e34-5678-4abc-9def-0123456789ab",
  "api_version": "v1",
  "data": {
    "action": "updated",
    "employee_id": "5e6d9f2a-3b7c-4e2f-9a1d-7c8e2f6b4a10",
    "entry_date": "2026-08-14",
    "entry_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
  },
  "related": {
    "url": "https://smengo.com/api/v1/schedule-entries?from=2026-08-14&to=2026-08-14"
  }
}
  • action — created, updated або deleted.
  • entry_id — ідентифікатор рядка графіка; збігається з id у відповіді GET /schedule-entries.
  • employee_id — співробітник після зміни: якщо зміну перепризначили, надійде новий.
  • entry_date — день зміни, YYYY-MM-DD у часовому поясі організації.
  • related відсутнє за action: "deleted": запису вже немає, і запит повернув би порожній список. Для видалення достатньо entry_id — видаліть рядок у себе.

Перезбереження зміни без правок події не породжує: подія народжується, лише якщо змінилося значуще поле (співробітник, дата, статус, шаблон зміни, час початку або кінця).

Звичайне видалення працівника — кнопка «Видалити», після якої він переїжджає до папки «Видалені», — подій не породжує взагалі: ховається сама картка працівника, а рядки графіка лишаються на місці. Каскад спрацьовує лише на «Видалити назавжди» з папки «Видалені»: там рядки змін справді видаляються, і на кожен надходить deleted.

Врахуйте побічний ефект звичайного видалення: подій немає, але з API v1 такий працівник і його зміни зникають — GET /schedule-entries, /check-ins і /timesheets вирізають видалених. Якщо ви тримаєте власну копію графіка, звіряйте її зі Співробітниками, а не чекайте на цей випадок deleted.

Масова операція — застосування чернетки чи видалення працівника назавжди — дає пачку подій: у всіх однаковий created, розрізняє їх sequence. Пачка їде в межах ~15 хвилин.

checkin.recorded

Співробітник відмітив прихід або вихід у Telegram-боті.

{
  "id": "8d7c6b5a-4e3f-4a2b-9c8d-7e6f5a4b3c2d",
  "type": "checkin.recorded",
  "created": "2026-08-14T06:02:44.117Z",
  "sequence": 10512,
  "org_id": "9c1a2e34-5678-4abc-9def-0123456789ab",
  "api_version": "v1",
  "data": {
    "check_in_id": "c3d4e5f6-a7b8-4c9d-8e1f-2a3b4c5d6e7f",
    "employee_id": "5e6d9f2a-3b7c-4e2f-9a1d-7c8e2f6b4a10",
    "entry_date": "2026-08-14",
    "kind": "in"
  },
  "related": {
    "url": "https://smengo.com/api/v1/check-ins?from=2026-08-14&to=2026-08-14"
  }
}
  • kind — in (прихід) або out (вихід).
  • check_in_id — ідентифікатор рядка відмітки; збігається з id у відповіді GET /check-ins. Прихід і вихід одного дня ділять один рядок, тому check_in_id у пари подій збігається, а Smengo-Event-Id — різний.
  • Точного часу приходу та виходу в тілі немає: самі хвилини дочитуються за related (check_in_at, check_out_at).

swap.decided

Менеджер ухвалив рішення щодо заявки на заміну.

{
  "id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
  "type": "swap.decided",
  "created": "2026-08-10T11:47:02.330Z",
  "sequence": 10480,
  "org_id": "9c1a2e34-5678-4abc-9def-0123456789ab",
  "api_version": "v1",
  "data": {
    "decision": "approved",
    "employee_id": "5e6d9f2a-3b7c-4e2f-9a1d-7c8e2f6b4a10",
    "entry_date": "2026-08-16",
    "request_id": "f6e5d4c3-b2a1-4f9e-8d7c-6b5a4f3e2d1c"
  }
}
  • decision — approved або rejected. Скасування заявки самим співробітником подією не є.
  • employee_id — автор заявки, entry_date — день зміни, щодо якої вона подана.
  • related немає: GET-ресурсу заявок на заміну в API v1 не існує. Наслідки схвалення видно в графіку — якщо потрібен факт перестановки, підпишіться заразом на schedule_entry.changed.
  • Повторні технічні оновлення заявки (наприклад, відмітка про сповіщення) подій не породжують — лише перехід статусу в approved/rejected.

Далі

Чи була стаття корисною?