Заголовки запроса
API-токен сервисного пользователя в формате
Bearer YOUR_TOKEN. Токен выпускает владелец школы в кабинете:
Управление → Школа → Для разработчиков → API-ключи — подробнее в разделе «Аутентификация».Числовой ID продавца — аккаунта, которому принадлежит школа. Скопируйте его на странице API-ключи в
карточке «Данные для интеграции → Идентификаторы». По этому ID проверяются права токена.
Числовой ID школы, берётся там же, где
Seller-Id. Значение должно совпадать со школой продавца — иначе
вернётся ошибка 400 с cause: "ForbiddenSchoolMismatch".Должности — это справочник наименований позиций сотрудников школы (например, «Backend Engineer»). Должности
назначаются сотрудникам при найме и повышении и используются модулем персонала (staff) для описания структуры
занятости.
Требования к правам доступа
Чтение (
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}. Удалённое подразделение
снимается со всех должностей: должность, у которой не осталось подразделений, становится общей для школы.Список должностей
StaffView).
Эндпоинт возвращает пагинированный список должностей. Параметры пагинации и фильтрации передаются как
query-параметры.
Параметры
Поиск по названию должности. Максимум 50 символов. Поиск нечёткий (находит и частичные совпадения), поэтому для
поиска конкретной должности по имени сравнивайте
name найденных записей со своим значением без учёта
регистра, а надёжнее — ищите по extIds.Фильтр по списку внешних идентификаторов (
extId). До 250 значений, каждое — максимум 50 символов.Должности, доступные в подразделении: привязанные к нему и общие для всей школы (без привязки к
подразделениям).
Направление сортировки по дате создания. Возможные значения:
ASC, DESC. Аналогично работают параметры id
и updatedAt.Ответ
Пагинированный объект:
items (массив должностей), page, count, pages, isFirst, isLast, next,
prev.Создание должности
StaffManage).
Параметры запроса
Название должности. От 1 до 100 символов. Пробелы в начале и конце обрезаются автоматически. Должно быть
уникальным в рамках школы.
Внешний идентификатор должности из системы клиента (CRM/1C). От 1 до 50 символов, не может содержать
/ и
пробельные символы. Должен быть уникальным в рамках школы среди неудалённых записей.ID подразделений, в которых доступна должность. До 250 значений. Не передано или
[] — должность общая для всей
школы. Все подразделения должны принадлежать школе, иначе вернётся StaffDepartmentNotFound. Подробнее — в
разделе «Привязка к подразделениям и грейдам».ID грейдов, которые можно присвоить сотруднику на этой должности. До 100
значений. Не передано или
[] — подходят любые грейды. Все грейды должны принадлежать школе, иначе вернётся
StaffGradeNotFound.Обновление должности
StaffManage).
Параметры
Новое название должности. От 1 до 100 символов. Пробелы в начале и конце обрезаются автоматически. Должно быть
уникальным в рамках школы.
Внешний идентификатор должности из системы клиента (CRM/1C). От 1 до 50 символов, не может содержать
/ и
пробельные символы. Должен быть уникальным в рамках школы среди неудалённых записей.Новый список ID подразделений, в которых доступна должность (до 250). Заменяет текущий список целиком;
[]
делает должность общей для всей школы; не передано — привязка не меняется. Ошибка StaffDepartmentNotFound,
если подразделение не найдено в школе.Новый список ID грейдов должности (до 100). Заменяет текущий список целиком;
[] — подходят любые грейды; не
передано — список не меняется. Ошибка StaffGradeNotFound, если грейд не найден в школе.Обновление должности по extId
StaffManage).
Эндпоинт-аналог обновления по ID: должность находится по внешнему идентификатору
extId в рамках школы.
Значение extId в пути должно быть URL-encoded.Параметры
Внешний идентификатор (
extId) обновляемой должности в рамках школы. Должен быть URL-encoded.Новое название должности. От 1 до 100 символов. Пробелы в начале и конце обрезаются автоматически. Должно быть
уникальным в рамках школы.
Новый внешний идентификатор должности. От 1 до 50 символов, не может содержать
/ и пробельные символы.
Должен быть уникальным в рамках школы среди неудалённых записей.Новый список ID подразделений, в которых доступна должность (до 250). Работает так же, как при
обновлении по ID.
Новый список ID грейдов должности (до 100). Работает так же, как при обновлении по ID.
Удаление должности
StaffManage).
Параметры
Ответ
Удаление должности по extId
StaffManage).
Эндпоинт-аналог удаления по ID: должность находится по внешнему идентификатору
extId в рамках школы.
Значение extId в пути должно быть URL-encoded.Параметры
Внешний идентификатор (
extId) удаляемой должности в рамках школы. Должен быть URL-encoded.Ответ
Обновлено: 2026-10-22 23:06 UTC