SmengoAPI

Записи графіка

Повертає опубліковані записи графіка змін — по днях, з пагінацією та фільтрами за періодом, відділом і співробітником.

Скоуп

Потрібен скоуп schedule.read. Без нього ключ отримає 403 missing_scope. Яке право потрібне творцеві ключа, щоб видати цей скоуп, — у Скоупах і правах → Таблиця скоупів.

Query-параметри

Параметр Обов'язковий Опис
limit ні Ціле 1..200, за замовчуванням 100.
cursor ні Курсор meta.next_cursor попередньої відповіді — для наступної сторінки.
from, to ні Дати YYYY-MM-DD у таймзоні організації, межі включно — фільтр за entry_date. Передаються лише парою; максимальний діапазон — 366 днів. Без них — поточний календарний місяць.
department_id ні UUID відділу. Зіставляється через відділ співробітника, а не через власну колонку запису: повернуться записи співробітників цього відділу. Невідомий або чужий department_id — не помилка, просто порожній список.
employee_id ні UUID співробітника — суворе рівняння. Невідомий або чужий employee_id — теж порожній список, не помилка.

Інших параметрів у ресурсу немає: будь-який зайвий параметр → 400 validation_error — відхиляється явно, а не ігнорується мовчки (див. Конвенції → Фільтри). Передати лише from без to (або навпаки) теж не можна — 400 з підказкою pass both from and to, or neither.

Запит

Без параметрів — записи поточного місяця в таймзоні організації:

curl -s https://smengo.com/api/v1/schedule-entries \
  -H "Authorization: Bearer smg_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

За конкретний період і по одному співробітнику:

curl -s "https://smengo.com/api/v1/schedule-entries?from=2026-07-01&to=2026-07-31&employee_id=5e6d9f2a-3b7c-4e2f-9a1d-7c8e2f6b4a10" \
  -H "Authorization: Bearer smg_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Відповідь

{
  "data": [
    {
      "id": "7a3c1d5e-8f2b-4c6a-9e1f-2d4b6a8c0e13",
      "employee_id": "5e6d9f2a-3b7c-4e2f-9a1d-7c8e2f6b4a10",
      "employee_full_name": "Иванова Мария",
      "entry_date": "2026-07-14",
      "status_id": "c2e4a6b8-1d3f-4a5c-8e7b-9f0a1b2c3d4e",
      "shift_preset_id": "3f8e2a1c-6b5d-4e9f-a2c1-7d8e9f0a1b2c",
      "start_time": null,
      "end_time": null
    },
    {
      "id": "b91f4e2d-0a7c-4b3e-8d6f-1c2a3b4c5d6e",
      "employee_id": "0b2f5e7a-9c31-4d6e-8a2b-4f1e6c9d3a52",
      "employee_full_name": "Петров Игорь",
      "entry_date": "2026-07-14",
      "status_id": "c2e4a6b8-1d3f-4a5c-8e7b-9f0a1b2c3d4e",
      "shift_preset_id": null,
      "start_time": "22:00:00",
      "end_time": "06:00:00"
    }
  ],
  "meta": { "next_cursor": null }
}

Поля відповіді

Поле Тип Опис
id string (uuid) Унікальний ідентифікатор запису графіка.
employee_id string (uuid) Співробітник, якому належить запис (див. Співробітники).
employee_full_name string Повне ім'я співробітника. Вкладено свідомо: BI-вивантаження графіка обходиться без другого запиту до /employees.
entry_date string (YYYY-MM-DD) День запису, в таймзоні організації; список відсортований за цим полем (плюс id як тай-брейкер).
status_id string (uuid) Статус дня — робочий день, відпустка, лікарняний тощо; розшифрування в Типах статусів.
shift_preset_id string (uuid) | null Пресет зміни (див. Пресети змін); null, якщо запис до пресета не прив'язаний.
start_time string (HH:MM:SS) | null Початок зміни — перевизначення на рівні конкретного запису, в таймзоні організації.
end_time string (HH:MM:SS) | null Кінець зміни — теж per-entry-перевизначення.

start_time/end_time — це сирі перевизначення часу для конкретного запису. null не означає «часу немає»: в такому разі час зміни визначається пресетом (shift_preset_id) або статусом (status_id) — обидва довідники віддають свої дефолтні часи. Нічні зміни можуть перетинати північ, тому start_time < end_time не гарантований: "22:00:00" → "06:00:00" — зміна до ранку наступного дня.

Чернетки графіка в цій відповіді не з'являються ніколи — ендпоінт віддає лише опубліковані записи; звільнені співробітники виключені повністю разом зі своїми записами. Службові поля note, created_by, updated_by у вибірку не входять.

Пагінація

Список відсортований за entry_date, id. Якщо записів більше, ніж limit, meta.next_cursor містить курсор для наступної сторінки; передайте його в cursor наступного запиту як є:

curl -s "https://smengo.com/api/v1/schedule-entries?limit=1&cursor=eyJrIjoiMjAyNi0wNy0xNCIsImlkIjoiN2EzYzFkNWUtOGYyYi00YzZhLTllMWYtMmQ0YjZhOGMwZTEzIn0" \
  -H "Authorization: Bearer smg_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

meta.next_cursor дорівнює null, коли записів більше немає. Загальні правила пагінації — у Конвенціях → Пагінація.

Що далі

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