Отделы

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

Скоуп

Скоуп не требуется — эндпоинт доступен любому валидному ключу организации. Подробнее — в Скоупах и правах.

Query-параметры

Параметр	Обязателен	Описание
limit	нет	Целое 1..200, по умолчанию 100.
cursor	нет	Курсор meta.next_cursor предыдущего ответа — для следующей страницы.

department_id и employee_id на этом ресурсе не поддержаны: если передать любой из них, ответ — 400 validation_error (параметр отклоняется явно, а не игнорируется молча — см. Конвенции → Фильтры). У отделов также нет from/to — это ресурс без временно́го измерения.

Запрос

curl -s https://smengo.com/api/v1/departments \
  -H "Authorization: Bearer smg_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Ответ

{
  "data": [
    {
      "id": "9c1a2e34-5678-4abc-9def-0123456789ab",
      "name": "Кухня",
      "parent_id": null,
      "sort_order": 0,
      "color": "#f97316",
      "geo": null
    },
    {
      "id": "3f7b1c9a-2d4e-4a11-8b6f-5e0d9c2a7f31",
      "name": "Зал",
      "parent_id": null,
      "sort_order": 1,
      "color": null,
      "geo": null
    }
  ],
  "meta": { "next_cursor": null }
}

Поля ответа

Поле	Тип	Описание
id	string (uuid)	Уникальный идентификатор отдела.
name	string	Название отдела.
parent_id	string (uuid) | null	Родительский отдел, если отделы вложены; null для отдела верхнего уровня.
sort_order	number	Порядковый номер отдела в списке; список отсортирован по этому полю (плюс id как тай-брейкер).
color	string | null	Hex-цвет отдела (например, #f97316), которым он подсвечивается в графике; null, если цвет не задан.
geo	string | null	Свободный текст с точкой/локацией отдела; null, если не задан.

Пагинация

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

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

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

Что дальше

• Организация — данные организации, включая таймзону.
• Сотрудники — у каждого сотрудника есть department_id, ссылающийся на отдел из этого списка.
• Конвенции — формат ответов и фильтры.