Заголовки запроса
string
обязательно
API-токен сервисного пользователя в формате
Bearer YOUR_TOKEN. Токен выпускает владелец школы в кабинете:
Управление → Школа → Для разработчиков → API-ключи — подробнее в разделе «Аутентификация».integer
обязательно
Числовой ID продавца — аккаунта, которому принадлежит школа. Скопируйте его на странице API-ключи в
карточке «Данные для интеграции → Идентификаторы». По этому ID проверяются права токена.
integer
обязательно
Числовой ID школы, берётся там же, где
Seller-Id. Значение должно совпадать со школой продавца — иначе
вернётся ошибка 400 с cause: "ForbiddenSchoolMismatch".SchoolManageUsers).
Параметры запроса
Для определения существующего пользователя — передайте хотя бы один из ниже перечисленных параметров, в противном случае пользователь будет создаваться при каждом запросе.
В случае если пользователь найден по указанным ниже полям — произойдет только его обновление.
В случае создания — логин и пароль для входа отправятся новому пользователю автоматически (каналы
отправки — как в
user/create). Задать свой пароль через апсерт нельзя:
поле password поддерживается только в user/create.Как ищется существующий пользователь. Из логинов в поиске участвует только один — первый непустой в
порядке
phone → email → domain. Если он не найден, поиск продолжается по tgId, затем по extId; первое
совпадение и обновляется. Например, если переданы phone и email, а в школе есть пользователь только с таким
email (телефон у него другой или не задан), он не будет найден по email — апсерт попытается создать нового
пользователя и вернёт ошибку EmailIsBusy. Ошибки EmailIsBusy / PhoneIsBusy / TgIdIsBusy / ExtIdIsBusy при
обновлении также означают, что переданное значение уже принадлежит другому пользователю школы. Для стабильной
синхронизации передавайте extId — постоянный идентификатор из вашей системы.string
Email адрес пользователя. Должен быть валидным email форматом. При передаче пустой строки — преобразуется в
null.string
Номер телефона пользователя. Должен быть в международном формате (например, +9876543210). При передаче пустой строки
— преобразуется в
null.string
Доменный логин пользователя. До 65 символов: латинские буквы, цифры,
_ и точки — точка не может быть первой/последней и не может
идти подряд (автоматически приводится к нижнему
регистру). Должен быть уникальным в рамках школы. Если не передан при создании — генерируется автоматически в
формате id12345. Используется для входа наряду с email и phone.integer
Telegram ID пользователя. Целое число или
null. Логином не является.string
Внешний идентификатор пользователя из вашей системы (например, GUID из CRM/1С). Строка до 50 символов
без
/ и пробелов или null. Логином не является — используется только для связи и поиска.Дополнительные параметры
enum
Статус учётной записи:
Active, OnLeave, Banned, Blocked или Terminated.
OnLeave — информационный (доступ не блокирует, управляется модулем
отсутствий); Banned, Blocked и Terminated закрывают доступ: вход
запрещён, активные сессии завершаются, зачисления блокируются. Terminated управляется автоматически модулем
трудоустройств; при снятии бана (Banned → Active) фактический
статус пересчитывается автоматически. Статус Deleted зарезервирован системой. Подробнее — в
user/create и user/update.Булево поле
banned из запроса удалено — блокировка управляется только через status. В ответе поля
banned и active по-прежнему присутствуют как производные от status.Параметры профиля
object
Объект с данными профиля пользователя.
При создании пользователя автоматически создается связанный профиль с указанными данными. Если профиль не указан,
создается пустой профиль, поля
firstName и lastName будут заполнены пользователем при первом входе в аккаунт.Дополнительные агрегаты (extra)
object
Контейнер связанных данных, применяемых вместе с апсертом. Сейчас содержит блок
staff.employments —
массив трудоустройств (от 1 до 10): департамент, должность, вид и тип занятости. Доступно только для
корпоративных школ. Если апсерт приводит к созданию пользователя — блок обязателен (сотрудник не может
существовать без трудоустройства). Для существующего пользователя трудоустройства применяются идемпотентно:
повторная передача той же активной пары департамент + должность не создаёт дубль.Состав полей элемента employments — как в
user/create:
extId, positionId/positionExtId, departmentId/departmentExtId, kind, type, startAt, rate.Данные, которых нет в этой схеме (город, произвольный статус из CRM и т.п.), передаются через
кастомные поля.
Требования к правам доступа
Для создания или обновления пользователя требуется право «Управление пользователями школы»
(
SchoolManageUsers).При установке блокирующего статуса (
Banned/Blocked/Terminated) все активные сессии пользователя
автоматически завершаются — это
реализовано для обеспечения безопасности.Обновлено: 2026-09-25 13:43 UTC