Заголовки запроса
API-токен сервисного пользователя в формате
Bearer YOUR_TOKEN. Токен выпускает владелец школы в кабинете:
Управление → Школа → Для разработчиков → API-ключи — подробнее в разделе «Аутентификация».Числовой ID продавца — аккаунта, которому принадлежит школа. Скопируйте его на странице API-ключи в
карточке «Данные для интеграции → Идентификаторы». По этому ID проверяются права токена.
Числовой ID школы, берётся там же, где
Seller-Id. Значение должно совпадать со школой продавца — иначе
вернётся ошибка 400 с cause: "ForbiddenSchoolMismatch".Департаменты — это иерархические подразделения школы. Каждый департамент может иметь родительский департамент
(
parentId), за счёт чего строится дерево организационной структуры. Департаменты используются модулем
персонала (staff) для распределения сотрудников по подразделениям и назначения руководителей.Поле
extId — внешний идентификатор департамента из системы клиента (CRM, 1C и т.п.). Он уникален в рамках
школы среди неудалённых записей, имеет длину от 1 до 50 символов и не может содержать / и пробельные символы
(значение должно быть URL-safe — оно используется в путях ext/{extId}). По extId доступны отдельные
эндпоинты обновления и удаления.Требования к правам доступа
Чтение (
tree, list) требует права «Просмотр персонала» (StaffView). Создание, обновление и удаление требуют права
«Управление персоналом» (StaffManage). Во всех случаях необходима аутентификация по токену и принадлежность школы к сегменту
Corporate.Дерево департаментов
StaffView).
Эндпоинт возвращает плоский массив всех департаментов школы. Иерархия задаётся полем
parentId каждого
департамента (null — корневой департамент). Само дерево строится на стороне клиента группировкой элементов по
parentId.Ответ
Массив департаментов школы. Поле
parentId указывает на родительский департамент (null — корневой).Список департаментов
StaffView).
В отличие от
tree, эндпоинт возвращает пагинированный список департаментов. Параметры пагинации и фильтрации
передаются как query-параметры.Параметры
Массив ID родительских департаментов для фильтрации (до 250 значений). Возвращает только дочерние департаменты
указанных родителей.
Массив внешних идентификаторов (
extId) для фильтрации (до 250 значений, каждый — до 50 символов).Направление сортировки по дате создания. Возможные значения:
ASC, DESC. Аналогично работают параметры id
и updatedAt.Ответ
Пагинированный объект:
items (массив департаментов), page, count, pages, isFirst, isLast, next,
prev.Создание департамента
StaffManage).
Параметры запроса
Название департамента. От 1 до 100 символов. Пробелы в начале и конце обрезаются автоматически.
Внешний идентификатор департамента из системы клиента (CRM/1C). От 1 до 50 символов, не может содержать
/ и
пробельные символы (URL-safe — используется в путях ext/{extId}). Должен быть уникален в рамках школы среди
неудалённых департаментов, иначе будет возвращена ошибка StaffDepartmentExtIdIsNotUniq.ID родительского департамента. Родитель указывается через
parentId или parentExtId — передаётся не более
одного поля из пары. Если указан — должен принадлежать той же школе, иначе будет возвращена ошибка
StaffDepartmentNotFound. Если родитель не указан ни одним из полей — департамент создаётся корневым.Внешний идентификатор (
extId) родительского департамента — альтернатива parentId (передаётся не более одного
поля из пары). От 1 до 50 символов. Родитель должен быть создан раньше дочернего департамента и принадлежать
той же школе, иначе будет возвращена ошибка StaffDepartmentNotFound.Трудоустройство, назначаемое основным руководителем создаваемого департамента. Необязательно. Указывается
через
primaryManagerEmploymentId или primaryManagerEmploymentExtId. Трудоустройство должно быть
активным и уже начавшимся (startAt не в будущем), иначе вернётся StaffEmploymentNotFound; департамент
трудоустройства при этом может быть любым. Результат тот же, что у
department-manager/set с isPrimary: true.Внешний идентификатор (
extId) трудоустройства-руководителя — альтернатива primaryManagerEmploymentId
(передаётся не более одного поля из пары). От 1 до 50 символов.Обновление департамента
StaffManage).
Тело запроса совпадает с созданием (все поля необязательны):
name, extId, родитель
(parentId/parentExtId) и основной руководитель (primaryManagerEmploymentId/primaryManagerEmploymentExtId).
Передавайте только те поля, которые нужно изменить.Параметры
Новое название департамента. От 1 до 100 символов. Пробелы в начале и конце обрезаются автоматически.
Новый внешний идентификатор департамента (можно переустановить). От 1 до 50 символов, не может содержать
/
и пробельные символы (URL-safe). Должен быть уникален в рамках школы среди неудалённых департаментов, иначе
будет возвращена ошибка StaffDepartmentExtIdIsNotUniq.Новый родительский департамент (переподчинение). Указывается через
parentId или parentExtId.
Передайте null, чтобы сделать департамент корневым. Новый родитель должен принадлежать той же школе
(StaffDepartmentNotFound) и не может быть самим департаментом или его потомком, иначе будет возвращена
ошибка StaffDepartmentParentCreatesCycle.Внешний идентификатор (
extId) нового родителя — альтернатива parentId (передаётся не более одного поля из
пары). От 1 до 50 символов. null делает департамент корневым. Если поле не передано, родитель не меняется —
поэтому при синхронизации передавайте его всегда, чтобы переподчинения из HR-системы попадали в Exode.Трудоустройство, назначаемое основным руководителем департамента. Указывается через
primaryManagerEmploymentId или primaryManagerEmploymentExtId. Передайте null, чтобы у департамента
не было основного руководителя: текущий основной руководитель станет обычным (запись руководителя
сохраняется; удалить её полностью можно через
department-manager/remove).Внешний идентификатор (
extId) трудоустройства-руководителя — альтернатива primaryManagerEmploymentId
(передаётся не более одного поля из пары). От 1 до 50 символов.Обновление департамента по extId
StaffManage).
Аналог обычного обновления, но департамент ищется по внешнему идентификатору (
extId) в рамках школы.
Тело запроса — то же, что и у PUT /saas/v2/staff/department/{departmentId}/update. Значение extId в пути
должно быть URL-encoded. Если департамент с таким extId не найден в рамках школы — будет возвращена ошибка
StaffDepartmentNotFound.Параметры
Удаление департамента
StaffManage).
При удалении департамент снимается со всех должностей,
которые к нему привязаны. Должность, у которой не осталось ни одного подразделения, становится общей для школы.
Параметры
Ответ
Удаление департамента по extId
StaffManage).
Аналог обычного удаления, но департамент ищется по внешнему идентификатору (
extId) в рамках школы. Действуют
те же правила: удалить можно только «листовой» департамент без дочерних подразделений и активных сотрудников
(иначе — StaffDepartmentHasChildren / StaffDepartmentHasActiveEmployments), а привязка департамента к
должностям снимается. Значение extId в пути должно быть URL-encoded. Если департамент с таким extId не найден
в рамках школы — будет возвращена ошибка StaffDepartmentNotFound.Параметры
Ответ
Обновлено: 2026-10-22 23:06 UTC