Огляд API
Smengo API — це програмний доступ до даних вашої організації: співробітники, відділи, графік та інші ресурси платформи. Він потрібен для інтеграцій, BI-вивантажень і автоматизованої синхронізації даних із зовнішніми системами — без ручного експорту з інтерфейсу.
Як влаштований API
API працює поверх HTTPS і версіонується в шляху: базова адреса — https://smengo.com/api/v1. Зворотно несумісні зміни виходитимуть як /api/v2, а не як правки поточної версії — так наявні інтеграції не ламаються непомітно.
Відповіді — завжди JSON, включно з помилками. Формат відповідей і пагінація описані в Конвенціях.
Наразі API строго read-only — лише GET-запити. Ендпоінти для запису (створення змін, відміток тощо) не входять до v1 і з'являться окремим етапом за запитом.
Що доступно зараз
У v1 відкрито всі дев'ять ресурсів платформи — кожен строго на читання.
Довідники — доступні будь-якому валідному ключу організації, без скоупів:
GET /org— дані організації (назва, таймзона, локаль).GET /departments— список відділів.GET /shift-presets— пресети змін.GET /status-types— типи статусів.
Дані — кожен ресурс закритий своїм скоупом (див. Скоупи та права):
GET /employees— список співробітників (employees.read).GET /schedule-entries— записи графіка змін (schedule.read).GET /check-ins— відмітки приходу/відходу (checkins.read).GET /timesheets— табелі (timesheets.read).GET /demand-signals— сигнали попиту (demand.read).
Машинозчитуваний опис усього API — спека OpenAPI 3.1: GET /api/v1/openapi.json, публічна, без ключа. Спробувати запити просто в браузері можна в інтерактивній консолі на сторінці /developers.
API-ключ — серверний секрет
Кожен запит автентифікується API-ключем організації (див. Автентифікацію). Ключ не можна використовувати в коді, що виконується в браузері користувача — CORS для /api/v1 вимкнено навмисно, запити з чужого домену не пройдуть. Тримайте ключ на сервері — у бекенді вашої інтеграції, скрипті чи serverless-функції — і ніколи не вбудовуйте його в клієнтський JavaScript. Виняток один: консоль розробника живе на нашому домені й викликає API з того самого origin — там запит руками зробити можна.
Що далі
- Автентифікація — як отримати і використовувати ключ.
- Швидкий старт — перший запит за кілька хвилин.