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, когда табелей больше нет. Общие правила пагинации — в Конвенциях → Пагинация.

Что дальше

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