SmengoAPI

Чек-ины

Возвращает чек-ины — фактические отметки прихода и ухода сотрудников, с пагинацией и фильтрами по периоду, отделу и сотруднику.

Скоуп

Требуется скоуп checkins.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/check-ins \
  -H "Authorization: Bearer smg_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

За конкретный период и по отделу:

curl -s "https://smengo.com/api/v1/check-ins?from=2026-07-01&to=2026-07-31&department_id=9c1a2e34-5678-4abc-9def-0123456789ab" \
  -H "Authorization: Bearer smg_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Ответ

{
  "data": [
    {
      "id": "4d8f2c6a-1e3b-4f7d-9c5a-8b0e2f4a6c19",
      "employee_id": "5e6d9f2a-3b7c-4e2f-9a1d-7c8e2f6b4a10",
      "entry_date": "2026-07-14",
      "check_in_at": "2026-07-14T05:58:12.000Z",
      "check_out_at": "2026-07-14T14:03:47.000Z",
      "source": "telegram",
      "schedule_entry_id": "7a3c1d5e-8f2b-4c6a-9e1f-2d4b6a8c0e13"
    },
    {
      "id": "6c0a2e4d-7b9f-4c1e-8a3d-5e7f9b1d3a64",
      "employee_id": "0b2f5e7a-9c31-4d6e-8a2b-4f1e6c9d3a52",
      "entry_date": "2026-07-15",
      "check_in_at": "2026-07-15T06:02:33.000Z",
      "check_out_at": null,
      "source": "telegram",
      "schedule_entry_id": null
    }
  ],
  "meta": { "next_cursor": null }
}

Поля ответа

Поле Тип Описание
id string (uuid) Уникальный идентификатор чек-ина.
employee_id string (uuid) Сотрудник, которому принадлежит отметка. Имя сотрудника в ответ не вложено (в отличие от записей графика) — расшифровывайте employee_id через Сотрудников.
entry_date string (YYYY-MM-DD) День отметки, в таймзоне организации; список отсортирован по этому полю (плюс id как тай-брейкер).
check_in_at string (ISO 8601 UTC) | null Момент отметки прихода; null — чекин не происходил.
check_out_at string (ISO 8601 UTC) | null Момент отметки ухода; null — чекаут не происходил (или ещё не произошёл). Возможна любая комбинация null у пары check_in_at/check_out_at, включая чекин без чекаута.
source string Источник отметки. Это открытая строка, а не закрытый enum: сейчас единственный, кто пишет чек-ины, — Telegram-бот со значением telegram; в будущем могут появиться другие значения.
schedule_entry_id string (uuid) | null Привязка к записи графика (см. Записи графика); null — чекин вне графика.

Уволенные сотрудники в ответе не появляются — они исключены целиком, вместе со своими чек-инами, независимо от фильтров.

Пагинация

Список отсортирован по entry_date, id. Если чек-инов больше, чем limit, meta.next_cursor содержит курсор для следующей страницы; передайте его в cursor следующего запроса как есть:

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

meta.next_cursor равен null, когда чек-инов больше нет. Общие правила пагинации — в Конвенциях → Пагинация.

Что дальше

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