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.

Что дальше

Была ли статья полезна?