Перейти к основному содержанию

Заголовки запроса

string
обязательно
API-токен сервисного пользователя в формате Bearer YOUR_TOKEN. Токен выпускает владелец школы в кабинете: Управление → Школа → Для разработчиков → API-ключи — подробнее в разделе «Аутентификация».
integer
обязательно
Числовой ID продавца — аккаунта, которому принадлежит школа. Скопируйте его на странице API-ключи в карточке «Данные для интеграции → Идентификаторы». По этому ID проверяются права токена.
integer
обязательно
Числовой ID школы, берётся там же, где Seller-Id. Значение должно совпадать со школой продавца — иначе вернётся ошибка 400 с cause: "ForbiddenSchoolMismatch".
Должности — это справочник наименований позиций сотрудников школы (например, «Backend Engineer»). Должности назначаются сотрудникам при найме и повышении и используются модулем персонала (staff) для описания структуры занятости.
Все эндпоинты модуля персонала доступны только для школ корпоративного сегмента (Corporate). Запрос от школы другого сегмента будет отклонён.

Требования к правам доступа

Чтение (list) требует права «Просмотр персонала» (StaffView). Создание, обновление и удаление требуют права «Управление персоналом» (StaffManage). Во всех случаях необходима аутентификация по токену и принадлежность школы к сегменту Corporate.
Сервисный пользователь должен быть аутентифицирован по токену и иметь соответствующие права доступа к указанной школе.
Название должности уникально в рамках школы без учёта регистра («Менеджер» и «менеджер» — одно и то же название). Попытка создать или переименовать должность в уже существующее название в этой же школе вернёт ошибку StaffPositionNameIsNotUniq.
Поле extId — внешний идентификатор должности из системы клиента (CRM/1C, например GUID). Уникален в рамках школы среди неудалённых записей (уникальный индекс school + extId). От 1 до 50 символов, не может содержать / и пробельные символы — значение используется в путях ext/{extId}.

Привязка к подразделениям и грейдам

Должность можно ограничить списком подразделений и списком грейдов. Обе привязки необязательны: создавать должности без них можно, это ни на что не влияет, а привязать можно позже.
  • departmentIds — подразделения, в которых доступна должность. Не переданы или пустой массив — должность общая для всей школы (в интерфейсе: «Все подразделения»). Если привязка задана, нанять, повысить или перевести сотрудника на эту должность в другом подразделении нельзя — вернётся StaffPositionNotInDepartment (см. занятость).
  • gradeIds — грейды, которые можно присвоить сотруднику на этой должности. Не переданы или пустой массив — подходят любые грейды школы.
Массив заменяет список целиком: чтобы добавить подразделение, передайте полный новый список. [] снимает привязку, а если поле не передано при обновлении — привязка не меняется. Передаются внутренние ID подразделений и грейдов (не extId): ID подразделения по его extId можно получить через department/list?extIds=.... В ответе должности возвращается departmentIds — подразделения, к которым она привязана ([] — общая для школы); список должностей подразделения отдаёт position/list?departmentId={id}. Привязка к грейдам в ответе не возвращается — грейды должности отдаёт grade/list?positionId={id}. Удалённое подразделение снимается со всех должностей: должность, у которой не осталось подразделений, становится общей для школы.
Если в школе подключено приложение — источник оргструктуры (например, интеграция с Verifix) и оно импортирует должности, должности с extId управляются им: создание должности с extId, изменение name и extId такой должности и её удаление через API вернут ошибку MiniappInstallationManagedEntity. Привязку к подразделениям и грейдам (departmentIds, gradeIds) при этом менять можно. Если импорт должностей в настройках приложения выключен, ограничение снимается: должности остаются связанными с интеграцией, но меняются вручную.

Список должностей

Требуется аутентификация и право «Просмотр персонала» (StaffView).
Эндпоинт возвращает пагинированный список должностей. Параметры пагинации и фильтрации передаются как query-параметры.

Параметры

integer
Количество пропускаемых записей (offset-пагинация). Минимум 0.
integer
Количество возвращаемых записей на странице. От 1 до 1000.
integer
Номер страницы (альтернатива skip). Минимум 1.
integer[]
Фильтр по ID должностей. До 250 значений.
Поиск по названию должности. Максимум 50 символов. Поиск нечёткий (находит и частичные совпадения), поэтому для поиска конкретной должности по имени сравнивайте name найденных записей со своим значением без учёта регистра, а надёжнее — ищите по extIds.
string[]
Фильтр по списку внешних идентификаторов (extId). До 250 значений, каждое — максимум 50 символов.
integer
Должности, доступные в подразделении: привязанные к нему и общие для всей школы (без привязки к подразделениям).
enum
Направление сортировки по дате создания. Возможные значения: ASC, DESC. Аналогично работают параметры id и updatedAt.

Ответ

object
обязательно
Пагинированный объект: items (массив должностей), page, count, pages, isFirst, isLast, next, prev.

Создание должности

Требуется аутентификация и право «Управление персоналом» (StaffManage).

Параметры запроса

string
обязательно
Название должности. От 1 до 100 символов. Пробелы в начале и конце обрезаются автоматически. Должно быть уникальным в рамках школы.
string
Внешний идентификатор должности из системы клиента (CRM/1C). От 1 до 50 символов, не может содержать / и пробельные символы. Должен быть уникальным в рамках школы среди неудалённых записей.
integer[]
ID подразделений, в которых доступна должность. До 250 значений. Не передано или [] — должность общая для всей школы. Все подразделения должны принадлежать школе, иначе вернётся StaffDepartmentNotFound. Подробнее — в разделе «Привязка к подразделениям и грейдам».
integer[]
ID грейдов, которые можно присвоить сотруднику на этой должности. До 100 значений. Не передано или [] — подходят любые грейды. Все грейды должны принадлежать школе, иначе вернётся StaffGradeNotFound.

Обновление должности

Требуется аутентификация и право «Управление персоналом» (StaffManage).

Параметры

integer
обязательно
ID обновляемой должности в рамках школы.
string
Новое название должности. От 1 до 100 символов. Пробелы в начале и конце обрезаются автоматически. Должно быть уникальным в рамках школы.
string
Внешний идентификатор должности из системы клиента (CRM/1C). От 1 до 50 символов, не может содержать / и пробельные символы. Должен быть уникальным в рамках школы среди неудалённых записей.
integer[]
Новый список ID подразделений, в которых доступна должность (до 250). Заменяет текущий список целиком; [] делает должность общей для всей школы; не передано — привязка не меняется. Ошибка StaffDepartmentNotFound, если подразделение не найдено в школе.
integer[]
Новый список ID грейдов должности (до 100). Заменяет текущий список целиком; [] — подходят любые грейды; не передано — список не меняется. Ошибка StaffGradeNotFound, если грейд не найден в школе.

Обновление должности по extId

Требуется аутентификация и право «Управление персоналом» (StaffManage).
Эндпоинт-аналог обновления по ID: должность находится по внешнему идентификатору extId в рамках школы. Значение extId в пути должно быть URL-encoded.

Параметры

string
обязательно
Внешний идентификатор (extId) обновляемой должности в рамках школы. Должен быть URL-encoded.
string
Новое название должности. От 1 до 100 символов. Пробелы в начале и конце обрезаются автоматически. Должно быть уникальным в рамках школы.
string
Новый внешний идентификатор должности. От 1 до 50 символов, не может содержать / и пробельные символы. Должен быть уникальным в рамках школы среди неудалённых записей.
integer[]
Новый список ID подразделений, в которых доступна должность (до 250). Работает так же, как при обновлении по ID.
integer[]
Новый список ID грейдов должности (до 100). Работает так же, как при обновлении по ID.

Удаление должности

Требуется аутентификация и право «Управление персоналом» (StaffManage).
Должность нельзя удалить, если на ней есть активные сотрудники (включая запланированный наём с будущей датой) — вернётся StaffPositionHasActiveEmployments. Сначала смените сотрудникам должность через promote или уволите их.

Параметры

integer
обязательно
ID удаляемой должности в рамках школы.

Ответ

integer
обязательно
Количество удалённых записей (1 при успешном удалении).

Удаление должности по extId

Требуется аутентификация и право «Управление персоналом» (StaffManage).
Должность нельзя удалить, если на ней есть активные сотрудники (включая запланированный наём с будущей датой) — вернётся StaffPositionHasActiveEmployments. Сначала смените сотрудникам должность через promote или уволите их.
Эндпоинт-аналог удаления по ID: должность находится по внешнему идентификатору extId в рамках школы. Значение extId в пути должно быть URL-encoded.

Параметры

string
обязательно
Внешний идентификатор (extId) удаляемой должности в рамках школы. Должен быть URL-encoded.

Ответ

integer
обязательно
Количество удалённых записей (1 при успешном удалении).

Обновлено: 2026-10-22 23:06 UTC