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, коли чек-інів більше немає. Загальні правила пагінації — у Конвенціях → Пагінація.

Що далі

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