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

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

string
обязательно
API-токен сервисного пользователя в формате Bearer YOUR_TOKEN. Токен выпускает владелец школы в кабинете: Управление → Школа → Для разработчиков → API-ключи — подробнее в разделе «Аутентификация».
integer
обязательно
Числовой ID продавца — аккаунта, которому принадлежит школа. Скопируйте его на странице API-ключи в карточке «Данные для интеграции → Идентификаторы». По этому ID проверяются права токена.
integer
обязательно
Числовой ID школы, берётся там же, где Seller-Id. Значение должно совпадать со школой продавца — иначе вернётся ошибка 400 с cause: "ForbiddenSchoolMismatch".
Трудоустройство (employment) связывает пользователя школы с департаментом и, опционально, должностью. У сотрудника может быть несколько записей трудоустройства в истории, но только одна активная для конкретной пары департамент + должность. Должность можно не указывать — тогда сотрудник числится в департаменте без должности, и активная запись такого типа уникальна по паре департамент + пользователь. У записи также фиксируются условия занятости: вид (kind), тип (type) и ставка (rate).
Все эндпоинты модуля staff доступны только для школ сегмента Corporate. Для остальных сегментов запрос вернёт 401 с cause: "Forbidden" и сообщением Allowed only for Corporate school.
Если в школе подключено приложение — источник оргструктуры (например, интеграция с Verifix) и оно импортирует сотрудников, трудоустройствами с extId управляет оно, и изменение таких записей через API вернёт MiniappInstallationManagedEntity (в data.installationId — ID установки приложения). Ограничение действует для hire с extId в теле (пространство extId принадлежит интеграции), для transfer и terminate записи с extId, для update записи с extId, если меняется дата начала startAt (ставку, тип и вид занятости интеграция не синхронизирует — их менять можно), а также для promote записи с extId, если меняется должность и приложение импортирует должности (или грейд — когда интеграция синхронизирует грейды). Если импорт должностей выключен, должностью сотрудника владеет школа: синхронизация её не меняет, а promote на новую должность проходит. Записи без extId по-прежнему можно менять через API. Если импорт сотрудников в настройках приложения выключен, ограничение снимается: записи остаются связанными с интеграцией, но меняются вручную.
Помимо должности, трудоустройству можно присвоить грейд (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.

Пагинация

integer
Количество записей, которые нужно пропустить. По умолчанию 0.
integer
Номер страницы (альтернатива skip). Начинается с 1.
integer
Количество записей на странице. По умолчанию 100, максимум 1000.

Фильтрация

integer[]
Фильтр по ID трудоустройств. До 250 значений.
string[]
Фильтр по внешним идентификаторам (extId) трудоустройств. До 250 значений, каждое до 50 символов.
integer[]
Фильтр по ID пользователей. До 250 значений.
integer[]
Фильтр по ID департаментов. До 250 значений.
string[]
Фильтр по внешним идентификаторам (extId) департаментов. До 250 значений, каждое до 50 символов.
integer[]
Фильтр по ID должностей. До 250 значений.
string[]
Фильтр по внешним идентификаторам (extId) должностей. До 250 значений, каждое до 50 символов.
integer[]
Фильтр по ID грейдов. До 100 значений.
boolean
true — только сотрудники, выполнившие все условия перехода на следующий грейд; false — только те, кто их ещё не выполнил.
enum[]
Фильтр по статусам трудоустройства. Возможные значения: Active, Terminated. До 250 значений.
boolean
Если true — вернуть только действующие на текущий момент трудоустройства: статус Active, дата startAt уже наступила. Наём с будущей датой startAt сюда не попадёт до её наступления — чтобы получить и такие записи, используйте statuses=Active.
Поиск по сотруднику: ФИО, логин, ID пользователя. Максимум 50 символов.

Сортировка

enum
Направление сортировки по дате создания записи: ASC или DESC. Аналогично работают параметры id и updatedAt. Без параметров сортировки записи одного сотрудника идут подряд (группировка по userId).

Поля ответа

object
Постраничный список трудоустройств.

Нанять сотрудника

Требуется аутентификация и право «Управление персоналом» (StaffManage). Создаёт новую активную запись трудоустройства. Пользователь, департамент и должность (если указана) должны принадлежать школе. У сотрудника не может быть активного дубля с той же парой департамент + должность, а при найме без должности — с той же парой департамент + пользователь. Если пользователь ранее был уволен и имеет статус Terminated, найм автоматически возвращает ему статус Active. Департамент обязателен и указывается по ID или внешнему идентификатору: в паре departmentId / departmentExtId передаётся ровно один параметр. Должность опциональна: передайте ровно один параметр из пары positionId / positionExtId, либо не передавайте оба — тогда сотрудник нанимается без должности. Оба поля одной пары одновременно передавать нельзя. Если должность привязана к подразделениям, департамент найма должен быть среди них, иначе вернётся StaffPositionNotInDepartment. Грейд опционален и задаётся так же — одним параметром из пары gradeId / gradeExtId. Он проверяется на принадлежность школе (StaffGradeNotFound) и на соответствие списку грейдов должности (StaffGradeNotForPosition); при выключенных в школе грейдах вернётся StaffGradesDisabled.

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

integer
обязательно
ID пользователя, который принимается на работу. Пользователь должен быть уже зарегистрирован в школе, иначе вернётся UserNotBelongsToSchool. ID возвращается при создании пользователя; по вашему внешнему идентификатору его можно найти через user/find. Чтобы создать пользователя и сразу нанять его одним вызовом, используйте extra.staff.employments в user/create или user/upsert.
string
Внешний идентификатор трудоустройства из системы клиента. От 1 до 50 символов, без / и пробелов. Должен быть уникален в рамках школы среди открытых (не завершённых) трудоустройств. Задаётся только при найме: update трудоустройства extId не меняет, а в панели администратора такого поля нет. Если в школе подключено приложение — источник оргструктуры и оно импортирует сотрудников, найм с extId вернёт MiniappInstallationManagedEntity.
integer
ID должности. Должность должна принадлежать школе и быть доступна в департаменте найма (должность без привязки к подразделениям доступна везде). Опционально: передайте один параметр из пары positionId / positionExtId, либо не передавайте оба — сотрудник будет нанят без должности.
string
Внешний идентификатор (extId) должности — альтернатива positionId.
integer
ID грейда. Грейд должен принадлежать школе и входить в список грейдов должности (если список задан). Опционально: передайте один параметр из пары gradeId / gradeExtId, либо не передавайте оба — сотрудник будет нанят без грейда.
string
Внешний идентификатор (extId) грейда — альтернатива gradeId.
integer
ID департамента. Департамент должен принадлежать школе. Передаётся ровно один параметр из пары departmentId / departmentExtId.
string
Внешний идентификатор (extId) департамента — альтернатива departmentId.
string
Дата начала трудоустройства в формате ISO 8601 (например, 2026-07-02T00:00:00.000Z). По умолчанию — текущий момент. Можно указать дату в прошлом (перенос истории) или в будущем (запланированный приём): будущая запись сразу получает статус Active, но до наступления startAt не попадает в выборку activeOnly=true и не может быть назначена руководителем департамента.
enum
Вид занятости: Main (основное место работы), InternalSecondary (внутреннее совместительство), ExternalSecondary (внешнее совместительство). По умолчанию Main.
enum
Тип занятости: FullTime (полная) или PartTime (частичная). По умолчанию FullTime.
number
Ставка — доля полной ставки, от 0.01 до 1. По умолчанию 1.

Изменить условия трудоустройства

Требуется аутентификация и право «Управление персоналом» (StaffManage). Исправляет условия открытой записи трудоустройства на месте — без перехода и без новой записи в истории: дату начала (startAt), ставку (rate), тип (type) и вид (kind) занятости. id и extId записи не меняются. Подходит, чтобы исправить ошибку ввода или изменить ставку без перевода. Департамент, должность и грейд так не меняются — для них есть transfer и promote, которые сохраняют историю. Передаются только изменяемые поля; не переданные (и null) остаются прежними. Если не передано ни одного поля, вернётся StaffEmploymentInputRequired. Для закрытой записи вернётся StaffEmploymentNotFound.
Если запись создана переводом или повышением, вместе с её startAt переносится дата окончания (finishAt) предыдущей записи цепочки — история остаётся непрерывной. Новая дата начала не может быть раньше начала предыдущей записи, иначе вернётся StaffEmploymentInvalidTransitionDate. У записи, созданной наймом, дату начала можно перенести на любую — в прошлое или в будущее.

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

integer
обязательно
ID открытой записи трудоустройства.
string
Новая дата начала трудоустройства в формате ISO 8601 (например, 2026-07-01T00:00:00.000Z). Если в школе подключено приложение — источник оргструктуры и оно импортирует сотрудников, изменение даты начала записи с extId вернёт MiniappInstallationManagedEntity.
enum
Вид занятости: Main (основное место работы), InternalSecondary (внутреннее совместительство), ExternalSecondary (внешнее совместительство).
enum
Тип занятости: FullTime (полная) или PartTime (частичная).
number
Ставка — доля полной ставки, от 0.01 до 1.

Изменить условия по внешнему идентификатору

Требуется аутентификация и право «Управление персоналом» (StaffManage). Аналог изменения условий по employmentId, но открытая запись трудоустройства находится по внешнему идентификатору extId в рамках школы. Тело запроса и правила — те же: меняются только startAt, rate, type и kind, хотя бы одно поле обязательно.

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

string
обязательно
Внешний идентификатор открытой записи трудоустройства. Значение в пути должно быть URL-encoded.
string
Новая дата начала трудоустройства в формате ISO 8601. Не раньше начала предыдущей записи цепочки, если запись создана переводом или повышением.
enum
Вид занятости: Main, InternalSecondary или ExternalSecondary.
enum
Тип занятости: FullTime или PartTime.
number
Ставка — доля полной ставки, от 0.01 до 1.

Перевести в другой департамент

Требуется аутентификация и право «Управление персоналом» (StaffManage). Закрывает текущую активную запись трудоустройства (finishAt, статус Terminated) и создаёт новую активную запись в целевом департаменте. Целевой департамент должен принадлежать школе. Если у сотрудника в целевом департаменте уже есть открытая запись с той же должностью, вернётся StaffEmploymentAlreadyExists. По умолчанию должность и грейд сохраняются; если текущая должность привязана к подразделениям и целевого департамента среди них нет, вернётся StaffPositionNotInDepartment. Чтобы одновременно сменить должность и/или грейд, передайте toPositionId и/или toGradeId — это одна операция вместо пары transfer + promote. Новые должность и грейд проверяются так же, как при смене должности, но относительно целевого департамента.

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

integer
обязательно
ID переводимой активной записи трудоустройства.
integer
ID целевого департамента. Департамент должен принадлежать школе. Передаётся ровно один параметр из пары toDepartmentId / toDepartmentExtId.
string
Внешний идентификатор (extId) целевого департамента — альтернатива toDepartmentId.
integer | null
ID новой должности в целевом департаменте. Значение null снимает должность. Не передан — должность сохраняется. Указывается только по ID (варианта с extId нет).
integer | null
ID нового грейда. Значение null снимает грейд. Указывается только по ID (варианта с extId нет).
string
Дата перевода в формате ISO 8601. Должна быть не раньше startAt текущей записи, иначе вернётся StaffEmploymentInvalidTransitionDate. По умолчанию — текущий момент.

Перевести по внешнему идентификатору

Требуется аутентификация и право «Управление персоналом» (StaffManage). Аналог перевода по employmentId, но активная запись трудоустройства находится по внешнему идентификатору extId в рамках школы. Тело запроса — как у обычного перевода, без поля employmentId: при необходимости передайте toPositionId / toGradeId, чтобы сменить должность и грейд той же операцией.

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

string
обязательно
Внешний идентификатор активной записи трудоустройства. Значение в пути должно быть URL-encoded.
integer
ID целевого департамента. Департамент должен принадлежать школе. Передаётся ровно один параметр из пары toDepartmentId / toDepartmentExtId.
string
Внешний идентификатор (extId) целевого департамента — альтернатива toDepartmentId.
integer | null
ID новой должности в целевом департаменте. Значение null снимает должность. Не передан — должность сохраняется. Указывается только по ID (варианта с extId нет).
integer | null
ID нового грейда. Значение null снимает грейд. Указывается только по ID (варианта с extId нет).
string
Дата перевода в формате ISO 8601. Должна быть не раньше startAt текущей записи, иначе вернётся StaffEmploymentInvalidTransitionDate. По умолчанию — текущий момент.

Сменить должность

Требуется аутентификация и право «Управление персоналом» (StaffManage). Закрывает текущую активную запись трудоустройства (finishAt, статус Terminated) и создаёт новую активную запись с новой должностью и/или грейдом в том же департаменте. Целевая должность должна принадлежать школе и быть доступна в текущем департаменте (StaffPositionNotInDepartment). Если у сотрудника в этом департаменте уже есть открытая запись с новой должностью, вернётся StaffEmploymentAlreadyExists. Запрос должен явно выражать намерение: передайте должность (toPositionId или toPositionExtId) и/или грейд (toGradeId или toGradeExtId), чтобы назначить их, либо null, чтобы снять (сотрудник останется в департаменте без должности или без грейда). Если не передать ни одно из этих полей, вернётся ошибка StaffEmploymentInputRequired. Грейд проверяется так же, как при найме: StaffGradeNotFound, StaffGradeNotForPosition, StaffGradesDisabled. Если меняется только должность, текущий грейд сохраняется, когда он есть в списке грейдов новой должности, и сбрасывается в null, когда его там нет.

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

integer
обязательно
ID изменяемой активной записи трудоустройства.
integer | null
ID целевой должности. Должность должна принадлежать школе. Передаётся ровно один параметр из пары toPositionId / toPositionExtId. Значение null снимает должность — трудоустройство остаётся в департаменте без должности. Оба поля пары одновременно передавать нельзя.
string
Внешний идентификатор (extId) целевой должности — альтернатива toPositionId.
integer | null
ID целевого грейда. Передаётся ровно один параметр из пары toGradeId / toGradeExtId. Значение null снимает грейд.
string
Внешний идентификатор (extId) целевого грейда — альтернатива toGradeId.
string
Дата смены должности в формате ISO 8601. Должна быть не раньше startAt текущей записи, иначе вернётся StaffEmploymentInvalidTransitionDate. По умолчанию — текущий момент.

Сменить должность по внешнему идентификатору

Требуется аутентификация и право «Управление персоналом» (StaffManage). Аналог смены должности по employmentId, но активная запись трудоустройства находится по внешнему идентификатору extId в рамках школы. Тело запроса — как у обычной смены должности, без поля employmentId: передайте должность и/или грейд, чтобы назначить их, либо null, чтобы снять; если не передано ни одно из этих полей — ошибка StaffEmploymentInputRequired.

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

string
обязательно
Внешний идентификатор активной записи трудоустройства. Значение в пути должно быть URL-encoded.
integer | null
ID целевой должности. Должность должна принадлежать школе. Передаётся ровно один параметр из пары toPositionId / toPositionExtId. Значение null снимает должность — трудоустройство остаётся в департаменте без должности. Оба поля пары одновременно передавать нельзя.
string
Внешний идентификатор (extId) целевой должности — альтернатива toPositionId.
integer | null
ID целевого грейда. Передаётся ровно один параметр из пары toGradeId / toGradeExtId. Значение null снимает грейд.
string
Внешний идентификатор (extId) целевого грейда — альтернатива toGradeId.
string
Дата смены должности в формате ISO 8601. Должна быть не раньше startAt текущей записи, иначе вернётся StaffEmploymentInvalidTransitionDate. По умолчанию — текущий момент.

Уволить сотрудника

Требуется аутентификация и право «Управление персоналом» (StaffManage). Закрывает активную запись трудоустройства: проставляет finishAt, переводит статус в Terminated и снимает сотрудника с руководства департаментами. В ответе возвращается закрытая запись.
Увольнение с последнего активного трудоустройства автоматически переводит пользователя в статус Terminated — доступ к платформе закрывается: вход запрещён, активные сессии завершаются. Повторный найм (hire) пользователя со статусом Terminated автоматически возвращает ему статус Active.
Защиты при увольнении с последнего активного трудоустройства: нельзя уволить самого себя — пользователя, от имени которого выполняется запрос (StaffCannotTerminateSelf), и владельца школы (StaffCannotTerminateSchoolOwner). При сверке полного списка сотрудников пропускайте этих пользователей.
Увольнение вступает в силу в момент вызова: запись сразу получает статус Terminated, а при увольнении с последнего трудоустройства сразу закрывается доступ — даже если finishAt указан в будущем. Отложенного увольнения нет, поэтому вызывайте terminate в день фактического увольнения.

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

integer
обязательно
ID увольняемой активной записи трудоустройства.
string
Дата увольнения в формате ISO 8601, сохраняется в записи. Должна быть не раньше startAt трудоустройства, иначе вернётся StaffEmploymentInvalidTransitionDate. По умолчанию — текущий момент.

Уволить по внешнему идентификатору

Требуется аутентификация и право «Управление персоналом» (StaffManage). Аналог увольнения по employmentId, но активная запись трудоустройства находится по внешнему идентификатору extId в рамках школы. Тело запроса — как у обычного увольнения, без поля employmentId. Действуют те же защиты и та же логика перевода пользователя в статус Terminated при увольнении с последнего активного трудоустройства.

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

string
обязательно
Внешний идентификатор активной записи трудоустройства. Значение в пути должно быть URL-encoded.
string
Дата увольнения в формате ISO 8601, сохраняется в записи. Должна быть не раньше startAt трудоустройства, иначе вернётся StaffEmploymentInvalidTransitionDate. По умолчанию — текущий момент.

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

Модуль staff доступен только для школ сегмента Corporate. Для чтения списка требуется право «Просмотр персонала» (StaffView), для операций найма, изменения условий, перевода, повышения и увольнения — право «Управление персоналом» (StaffManage).
Сервисный пользователь должен быть аутентифицирован по токену и иметь соответствующие права доступа к указанной школе.

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