🪪Доступ сотрудников по API: приглашение и блокировка

Доступ сотрудников по API

Если сотрудники заводятся в HR-, CRM- или учётной системе, доступ к Sensei можно открывать и закрывать оттуда автоматически: пригласить нового сотрудника, заблокировать уволенного, вернуть доступ вернувшемуся, поменять отделы. Правила те же, что в кабинете: человек сам принимает приглашение, блокировка сразу закрывает кабинет, ботов в мессенджерах и MCP, разблокировка занимает место тарифа.

Подготовка

1. В Настройки → Интеграции, карточка «API для внешних систем», выпустите токен с правом employees:write; только для просмотра хватит employees:read. Нужен тариф «Бизнес» и выше.
2. Передавайте токен в заголовке Authorization: Bearer mcp_….

Сотрудника в адресе указывают по email или по id, например /api/employees/anna@company.ru/block. Администраторов организации API не меняет: их приглашают, блокируют и назначают только в кабинете.

Методы

• GET /api/employees — список сотрудников; фильтры status, email, department_id, постранично (page, size до 500). Без фильтра — все, включая заблокированных.
• GET /api/employees/{id|email} — один сотрудник.
• POST /api/employees — пригласить нового.
• POST /api/employees/{id|email}/invite-link — новая ссылка-приглашение.
• POST /api/employees/{id|email}/invite — повторить письмо-приглашение (не чаще 3 раз в час).
• POST /api/employees/{id|email}/block — закрыть доступ.
• POST /api/employees/{id|email}/unblock — вернуть доступ.
• PATCH /api/employees/{id|email} — отделы (department_ids), роль (EMPLOYEE или MANAGER), телефон.
• GET /api/employees/departments — отделы организации и их id.

Пригласить сотрудника

POST https://sensei.red/api/employees
Authorization: Bearer mcp_ВАШ_ТОКЕН
Content-Type: application/json

{
  "email": "anna@company.ru",
  "full_name": "Анна Петрова",
  "department_ids": ["id отдела"],
  "send_invite": false
}

В ответе — карточка сотрудника со статусом PENDING и поле invite_url: ссылка-приглашение, действует 7 дней. Отправьте её человеку любым каналом — в мессенджер, по SMS, из CRM. По умолчанию ("send_invite": true) Sensei ещё и пришлёт приглашение на email. Если сотрудник с таким email уже есть, ответ — 409; заблокированному доступ возвращает /unblock.

Что видит человек по ссылке

1. Страницу приглашения с кнопкой «Принять приглашение». Само открытие ссылки ничего не активирует — превью в мессенджере её не израсходует.
2. После кнопки — пароль: новый сотрудник задаёт его, а если у человека уже есть аккаунт Sensei, вводит свой пароль от него.
3. Дальше он сразу попадает в кабинет, статус меняется на ACTIVE.

Ссылка даёт право задать пароль новому аккаунту — отправляйте её только самому сотруднику. Прежние ссылки работают, пока приглашение не принято; пока сотрудник заблокирован, ссылки не действуют.

Кто уже принял приглашение, на /invite-link получает адрес входа ("kind": "login") вместо ссылки активации.

Закрыть и вернуть доступ

• /block сразу закрывает кабинет, ботов в мессенджерах и MCP. Данные и история обучения сохраняются, место в тарифе освобождается.
• /unblock возвращает доступ и снова занимает место. Кто ещё не принимал приглашение, возвращается в PENDING — отправьте ему новую ссылку.
• Повторные вызовы безопасны: заблокированный остаётся заблокированным, ничего не ломается.

Статусы и ошибки

• ACTIVE — доступ открыт, PENDING — приглашение не принято, BLOCKED — доступ закрыт.
• 401 — токен неверный или отозван либо выпустивший его администратор заблокирован или лишён прав; 403 — нет нужного права, тариф ниже «Бизнеса», закончились места тарифа или это администратор; 404 — сотрудник не найден; 409 — email уже есть, сотрудник заблокирован или удалил свой аккаунт; 429 — больше 120 запросов в минуту на токен.

Каждое изменение через API записывается в Настройки → Журнал действий, автором указан токен.