Обзор 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 — там запрос руками сделать можно.
Что дальше
- Аутентификация — как получить и использовать ключ.
- Быстрый старт — первый запрос за пару минут.