SmengoAPI

Табелі

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

Скоуп

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

Коли табель існує

Табель — це документ, який менеджер формує вручну в застосунку Smengo (сторінка «Табель», право «Табель»); автоматично, за розкладом, табелі не генеруються. Поки табель за місяць не сформовано, ендпоінт повертає за цей період порожній список. Порожня відповідь — не помилка: перш ніж робити висновки, перевірте, чи сформовано період узагалі.

  • Співробітник без жодного запланованого дня в періоді рядка не отримує — рядки табеля будуються з днів графіка. Відрізнити «співробітник не працював» від «табель не сформовано» засобами API неможливо — єдиний сигнал це наявність рядків інших співробітників за той самий період.
  • Звільнені співробітники виключені повністю — разом з історичними табелями. Табель минулого місяця співробітника, видаленого із застосунку вчора, з API вже не видно. Для бухгалтерських архівів вивантажуйте табелі до видалення співробітників. Співробітники з відкликаним доступом (access_revoked) у табелях залишаються.
  • Імен у рядках табеля немає — лише employee_id. Для звіту з іменами ключу потрібен другий скоуп employees.read (запит до Співробітників): з одним timesheets.read ви отримаєте тільки UUID. Зате employee_id з табеля завжди резолвиться в /employees — обидва ресурси симетрично виключають звільнених.

Query-параметри

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

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

Зверніть увагу на зіставлення за period: діапазон from=2026-06-15&to=2026-07-15 не зачепить ні червневий, ні липневий табель — перші дні обох місяців (2026-06-01, 2026-07-01) у діапазон не потрапляють. Щоб отримати табелі за червень і липень, запитуйте from=2026-06-01&to=2026-07-31.

Запит

Без параметрів — табелі поточного місяця:

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

За два місяці:

curl -s "https://smengo.com/api/v1/timesheets?from=2026-06-01&to=2026-07-31" \
  -H "Authorization: Bearer smg_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Відповідь

{
  "data": [
    {
      "id": "e2a4c6b8-0d1f-4e3a-9b7c-5f6a8d0e2c31",
      "employee_id": "5e6d9f2a-3b7c-4e2f-9a1d-7c8e2f6b4a10",
      "period": "2026-06-01",
      "planned_minutes": 10080,
      "actual_minutes": 10230,
      "approved_minutes": 10080,
      "days_from_plan": 0,
      "shift_count": 21,
      "status": "locked"
    },
    {
      "id": "1f3d5b7a-9c0e-4d2f-8b6a-4c8e0a2d6f13",
      "employee_id": "0b2f5e7a-9c31-4d6e-8a2b-4f1e6c9d3a52",
      "period": "2026-07-01",
      "planned_minutes": 9600,
      "actual_minutes": 9012,
      "approved_minutes": 0,
      "days_from_plan": 3,
      "shift_count": 20,
      "status": "draft"
    }
  ],
  "meta": { "next_cursor": null }
}

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

Поле Тип Опис
id string (uuid) Унікальний ідентифікатор табеля.
employee_id string (uuid) Співробітник, якому належить табель (див. Співробітники).
period string (YYYY-MM-01) Місяць табеля — завжди перший день місяця, в таймзоні організації; список відсортований за цим полем (плюс id як тай-брейкер).
planned_minutes number (int ≥ 0) Планові хвилини за місяць — із графіка.
actual_minutes number (int ≥ 0) Фактичні хвилини — із чек-інів.
approved_minutes number (int ≥ 0) Погоджені хвилини.
days_from_plan number (int) Кількість планових днів, де не було валідної пари чек-ін/чек-аут і факт узято рівним плану. Обчислюється під час збирання табеля — індикатор того, яка частина «факту» насправді підставлена з плану.
shift_count number (int) Кількість планових днів співробітника в періоді.
status "draft" | "approved" | "locked" Статус табеля: чернетка, погоджений, закритий.

Усі тривалості — в цілих хвилинах: дробових годин і десяткових значень у відповіді немає.

Грошові поля у v1 не віддаються (Monetary fields are not exposed in v1) — ставки, нарахування та вартість відпрацьованого часу через API недоступні. AI-пояснення (explanations) і ручні коригування (adjustments) у вибірку теж не входять, а звільнені співробітники виключені з відповіді повністю.

Пагінація

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

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

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

Що далі

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