Заголовки запроса
API-токен сервисного пользователя в формате
Bearer YOUR_TOKEN. Токен выпускает владелец школы в кабинете:
Управление → Школа → Для разработчиков → API-ключи — подробнее в разделе «Аутентификация».Числовой ID продавца — аккаунта, которому принадлежит школа. Скопируйте его на странице API-ключи в
карточке «Данные для интеграции → Идентификаторы». По этому ID проверяются права токена.
Числовой ID школы, берётся там же, где
Seller-Id. Значение должно совпадать со школой продавца — иначе
вернётся ошибка 400 с cause: "ForbiddenSchoolMismatch".Трудоустройство (
employment) связывает пользователя школы с департаментом и, опционально, должностью.
У сотрудника может быть несколько записей трудоустройства в истории, но только одна активная для
конкретной пары департамент + должность. Должность можно не указывать — тогда сотрудник числится в
департаменте без должности, и активная запись такого типа уникальна по паре департамент + пользователь.
У записи также фиксируются условия занятости: вид (kind), тип (type) и ставка (rate).Помимо должности, трудоустройству можно присвоить грейд (
gradeId) —
уровень карьерной шкалы школы. Грейд доступен, когда грейды включены в школе, иначе вернётся
StaffGradesDisabled. Если у должности задан ограниченный список грейдов, присвоить можно только грейд из
этого списка (StaffGradeNotForPosition). Если должность привязана к подразделениям,
назначить её можно только в одном из них (StaffPositionNotInDepartment); должность без привязки — общая для
всей школы и доступна в любом департаменте.Перевод (
transfer) и повышение (promote) не изменяют текущую запись, а закрывают её (finishAt, статус
Terminated) и создают новую активную запись в целевом департаменте либо с новой должностью. Условия
занятости (kind, type, rate) и внешний идентификатор extId переносятся в новую запись без изменений.
В ответе возвращается именно новая запись трудоустройства — с новым id. Поэтому в своей системе храните
extId трудоустройства, а не id: id меняется при каждом переводе и повышении, extId — нет. Назначение
руководителем департамента переходит на новую запись автоматически; ранее созданные отсутствия остаются
привязанными к закрытой записи. Исправить условия занятости или дату начала текущей записи без перехода
можно через update — тогда запись и её id не меняются.У трудоустройства может быть внешний идентификатор
extId — ID записи в системе клиента (например, HR-системе).
От 1 до 50 символов, без / и пробелов. Уникален в рамках школы среди открытых (не завершённых)
трудоустройств: при переводе или повышении extId переносится на новую активную запись (закрытая сохраняет
копию), а после увольнения освобождается — его можно снова передать при повторном найме. По extId доступны
отдельные роуты ext/{extId}/update, ext/{extId}/transfer, ext/{extId}/promote и ext/{extId}/terminate;
они находят только открытую запись, поэтому для уже закрытого трудоустройства вернут StaffEmploymentNotFound.Какую операцию выбрать
Удаления трудоустройства в API нет: запись закрывается только через
terminate и остаётся в истории. Каждая
операция изменения есть в двух вариантах: по employmentId (в теле запроса, у update — в пути) и по extId
в пути (ext/{extId}/...). Работают они одинаково; вариант с extId удобнее при синхронизации — не нужно
хранить внутренние ID Exode.
Список трудоустройств
StaffView).
Параметры запроса
Параметры-массивы передаются повторением параметра в строке запроса:
userIds=1&userIds=2&userIds=3.Пагинация
Фильтрация
Фильтр по внешним идентификаторам (
extId) трудоустройств. До 250 значений, каждое до 50 символов.Фильтр по внешним идентификаторам (
extId) департаментов. До 250 значений, каждое до 50 символов.Фильтр по внешним идентификаторам (
extId) должностей. До 250 значений, каждое до 50 символов.Фильтр по ID грейдов. До 100 значений.
true — только сотрудники, выполнившие все условия перехода на следующий грейд; false — только те, кто их
ещё не выполнил.Если
true — вернуть только действующие на текущий момент трудоустройства: статус Active, дата startAt
уже наступила. Наём с будущей датой startAt сюда не попадёт до её наступления — чтобы получить и такие
записи, используйте statuses=Active.Сортировка
Направление сортировки по дате создания записи:
ASC или DESC. Аналогично работают параметры id и
updatedAt. Без параметров сортировки записи одного сотрудника идут подряд (группировка по userId).Поля ответа
Нанять сотрудника
StaffManage).
Создаёт новую активную запись трудоустройства. Пользователь, департамент и должность (если указана) должны
принадлежать школе. У сотрудника не может быть активного дубля с той же парой департамент + должность, а при
найме без должности — с той же парой департамент + пользователь. Если пользователь ранее был уволен и имеет
статус Terminated, найм автоматически возвращает ему статус Active.
Департамент обязателен и указывается по ID или внешнему идентификатору: в паре departmentId /
departmentExtId передаётся ровно один параметр. Должность опциональна: передайте ровно один параметр из
пары positionId / positionExtId, либо не передавайте оба — тогда сотрудник нанимается без должности. Оба
поля одной пары одновременно передавать нельзя. Если должность привязана к подразделениям, департамент найма
должен быть среди них, иначе вернётся StaffPositionNotInDepartment.
Грейд опционален и задаётся так же — одним параметром из пары gradeId / gradeExtId. Он проверяется на
принадлежность школе (StaffGradeNotFound) и на соответствие списку грейдов должности
(StaffGradeNotForPosition); при выключенных в школе грейдах вернётся StaffGradesDisabled.
Параметры запроса
ID пользователя, который принимается на работу. Пользователь должен быть уже зарегистрирован в школе, иначе
вернётся
UserNotBelongsToSchool. ID возвращается при создании пользователя; по вашему внешнему
идентификатору его можно найти через user/find. Чтобы создать пользователя
и сразу нанять его одним вызовом, используйте extra.staff.employments в
user/create или user/upsert.Внешний идентификатор трудоустройства из системы клиента. От 1 до 50 символов, без
/ и пробелов.
Должен быть уникален в рамках школы среди открытых (не завершённых) трудоустройств. Задаётся только при найме:
update трудоустройства extId не меняет, а в панели администратора такого поля нет. Если в школе подключено
приложение — источник оргструктуры и оно импортирует сотрудников, найм с extId вернёт
MiniappInstallationManagedEntity.ID должности. Должность должна принадлежать школе и быть доступна в департаменте найма (должность без
привязки к подразделениям доступна везде). Опционально: передайте один параметр из пары
positionId / positionExtId, либо не передавайте оба — сотрудник будет нанят без должности.ID грейда. Грейд должен принадлежать школе и входить в список грейдов
должности (если список задан). Опционально: передайте один параметр из пары
gradeId / gradeExtId, либо не
передавайте оба — сотрудник будет нанят без грейда.ID департамента. Департамент должен принадлежать школе. Передаётся ровно один параметр из пары
departmentId / departmentExtId.Дата начала трудоустройства в формате ISO 8601 (например,
2026-07-02T00:00:00.000Z). По умолчанию — текущий
момент. Можно указать дату в прошлом (перенос истории) или в будущем (запланированный приём): будущая запись
сразу получает статус Active, но до наступления startAt не попадает в выборку activeOnly=true и не может
быть назначена руководителем департамента.Вид занятости:
Main (основное место работы), InternalSecondary (внутреннее совместительство),
ExternalSecondary (внешнее совместительство). По умолчанию Main.Изменить условия трудоустройства
StaffManage).
Исправляет условия открытой записи трудоустройства на месте — без перехода и без новой записи в истории:
дату начала (startAt), ставку (rate), тип (type) и вид (kind) занятости. id и extId записи не
меняются. Подходит, чтобы исправить ошибку ввода или изменить ставку без перевода. Департамент, должность и
грейд так не меняются — для них есть transfer и
promote, которые сохраняют историю.
Передаются только изменяемые поля; не переданные (и null) остаются прежними. Если не передано ни одного поля,
вернётся StaffEmploymentInputRequired. Для закрытой записи вернётся StaffEmploymentNotFound.
Если запись создана переводом или повышением, вместе с её
startAt переносится дата окончания (finishAt)
предыдущей записи цепочки — история остаётся непрерывной. Новая дата начала не может быть раньше начала
предыдущей записи, иначе вернётся StaffEmploymentInvalidTransitionDate. У записи, созданной наймом, дату
начала можно перенести на любую — в прошлое или в будущее.Параметры запроса
Новая дата начала трудоустройства в формате ISO 8601 (например,
2026-07-01T00:00:00.000Z). Если в школе
подключено приложение — источник оргструктуры и оно импортирует сотрудников, изменение даты начала записи с
extId вернёт MiniappInstallationManagedEntity.Вид занятости:
Main (основное место работы), InternalSecondary (внутреннее совместительство),
ExternalSecondary (внешнее совместительство).Изменить условия по внешнему идентификатору
StaffManage).
Аналог изменения условий по employmentId, но открытая запись трудоустройства находится по внешнему
идентификатору extId в рамках школы. Тело запроса и правила — те же: меняются только startAt, rate, type
и kind, хотя бы одно поле обязательно.
Параметры запроса
Внешний идентификатор открытой записи трудоустройства. Значение в пути должно быть URL-encoded.
Новая дата начала трудоустройства в формате ISO 8601. Не раньше начала предыдущей записи цепочки, если запись
создана переводом или повышением.
Перевести в другой департамент
StaffManage).
Закрывает текущую активную запись трудоустройства (finishAt, статус Terminated) и создаёт новую активную
запись в целевом департаменте. Целевой департамент должен принадлежать школе. Если у сотрудника в целевом
департаменте уже есть открытая запись с той же должностью, вернётся StaffEmploymentAlreadyExists.
По умолчанию должность и грейд сохраняются; если текущая должность привязана к подразделениям и целевого
департамента среди них нет, вернётся StaffPositionNotInDepartment. Чтобы одновременно сменить должность и/или
грейд, передайте toPositionId и/или toGradeId — это одна операция вместо пары transfer + promote. Новые
должность и грейд проверяются так же, как при смене должности, но относительно целевого
департамента.
Параметры запроса
ID целевого департамента. Департамент должен принадлежать школе. Передаётся ровно один параметр из пары
toDepartmentId / toDepartmentExtId.ID новой должности в целевом департаменте. Значение
null снимает должность. Не передан — должность
сохраняется. Указывается только по ID (варианта с extId нет).ID нового грейда. Значение
null снимает грейд. Указывается только
по ID (варианта с extId нет).Дата перевода в формате ISO 8601. Должна быть не раньше
startAt текущей записи, иначе вернётся
StaffEmploymentInvalidTransitionDate. По умолчанию — текущий момент.Перевести по внешнему идентификатору
StaffManage).
Аналог перевода по employmentId, но активная запись трудоустройства находится по внешнему идентификатору
extId в рамках школы. Тело запроса — как у обычного перевода, без поля employmentId: при необходимости
передайте toPositionId / toGradeId, чтобы сменить должность и грейд той же операцией.
Параметры запроса
Внешний идентификатор активной записи трудоустройства. Значение в пути должно быть URL-encoded.
ID целевого департамента. Департамент должен принадлежать школе. Передаётся ровно один параметр из пары
toDepartmentId / toDepartmentExtId.ID новой должности в целевом департаменте. Значение
null снимает должность. Не передан — должность
сохраняется. Указывается только по ID (варианта с extId нет).ID нового грейда. Значение
null снимает грейд. Указывается только
по ID (варианта с extId нет).Дата перевода в формате ISO 8601. Должна быть не раньше
startAt текущей записи, иначе вернётся
StaffEmploymentInvalidTransitionDate. По умолчанию — текущий момент.Сменить должность
StaffManage).
Закрывает текущую активную запись трудоустройства (finishAt, статус Terminated) и создаёт новую активную
запись с новой должностью и/или грейдом в том же департаменте. Целевая должность должна принадлежать школе и быть
доступна в текущем департаменте (StaffPositionNotInDepartment). Если у сотрудника в этом департаменте уже есть
открытая запись с новой должностью, вернётся StaffEmploymentAlreadyExists.
Запрос должен явно выражать намерение: передайте должность (toPositionId или toPositionExtId) и/или
грейд (toGradeId или toGradeExtId), чтобы назначить их, либо null, чтобы снять (сотрудник останется
в департаменте без должности или без грейда). Если не передать ни одно из этих полей, вернётся ошибка
StaffEmploymentInputRequired.
Грейд проверяется так же, как при найме: StaffGradeNotFound, StaffGradeNotForPosition,
StaffGradesDisabled. Если меняется только должность, текущий грейд сохраняется, когда он есть в списке грейдов
новой должности, и сбрасывается в null, когда его там нет.
Параметры запроса
ID целевой должности. Должность должна принадлежать школе. Передаётся ровно один параметр из пары
toPositionId / toPositionExtId. Значение null снимает должность — трудоустройство остаётся в
департаменте без должности. Оба поля пары одновременно передавать нельзя.ID целевого грейда. Передаётся ровно один параметр из пары
toGradeId / toGradeExtId. Значение null снимает грейд.Дата смены должности в формате ISO 8601. Должна быть не раньше
startAt текущей записи, иначе вернётся
StaffEmploymentInvalidTransitionDate. По умолчанию — текущий момент.Сменить должность по внешнему идентификатору
StaffManage).
Аналог смены должности по employmentId, но активная запись трудоустройства находится по внешнему идентификатору
extId в рамках школы. Тело запроса — как у обычной смены должности, без поля employmentId: передайте
должность и/или грейд, чтобы назначить их, либо null, чтобы снять; если не передано ни одно из этих полей —
ошибка StaffEmploymentInputRequired.
Параметры запроса
Внешний идентификатор активной записи трудоустройства. Значение в пути должно быть URL-encoded.
ID целевой должности. Должность должна принадлежать школе. Передаётся ровно один параметр из пары
toPositionId / toPositionExtId. Значение null снимает должность — трудоустройство остаётся в
департаменте без должности. Оба поля пары одновременно передавать нельзя.ID целевого грейда. Передаётся ровно один параметр из пары
toGradeId / toGradeExtId. Значение null снимает грейд.Дата смены должности в формате ISO 8601. Должна быть не раньше
startAt текущей записи, иначе вернётся
StaffEmploymentInvalidTransitionDate. По умолчанию — текущий момент.Уволить сотрудника
StaffManage).
Закрывает активную запись трудоустройства: проставляет finishAt, переводит статус в Terminated и снимает
сотрудника с руководства департаментами. В ответе возвращается закрытая запись.
Защиты при увольнении с последнего активного трудоустройства: нельзя уволить самого себя — пользователя,
от имени которого выполняется запрос (
StaffCannotTerminateSelf), и владельца школы
(StaffCannotTerminateSchoolOwner). При сверке полного списка сотрудников пропускайте этих пользователей.Увольнение вступает в силу в момент вызова: запись сразу получает статус
Terminated, а при увольнении
с последнего трудоустройства сразу закрывается доступ — даже если finishAt указан в будущем. Отложенного
увольнения нет, поэтому вызывайте terminate в день фактического увольнения.Параметры запроса
Дата увольнения в формате ISO 8601, сохраняется в записи. Должна быть не раньше
startAt трудоустройства, иначе
вернётся StaffEmploymentInvalidTransitionDate. По умолчанию — текущий момент.Уволить по внешнему идентификатору
StaffManage).
Аналог увольнения по employmentId, но активная запись трудоустройства находится по внешнему идентификатору
extId в рамках школы. Тело запроса — как у обычного увольнения, без поля employmentId. Действуют те же
защиты и та же логика перевода пользователя в статус Terminated при увольнении с последнего активного
трудоустройства.
Параметры запроса
Внешний идентификатор активной записи трудоустройства. Значение в пути должно быть URL-encoded.
Дата увольнения в формате ISO 8601, сохраняется в записи. Должна быть не раньше
startAt трудоустройства, иначе
вернётся StaffEmploymentInvalidTransitionDate. По умолчанию — текущий момент.Требования к правам доступа
Модуль staff доступен только для школ сегмента
Corporate. Для чтения списка требуется право «Просмотр персонала» (StaffView), для
операций найма, изменения условий, перевода, повышения и увольнения — право «Управление персоналом»
(StaffManage).Обновлено: 2026-10-23 10:08 UTC