Семейство user.* даёт REST-доступ к сотрудникам портала Битрикс24: получению текущего пользователя, поиску по фильтрам, чтению профилей и — при наличии прав — созданию и правке учётных записей.
Скоуп user и состав методов
Методы входят в скоуп user. Базовый набор:
| Метод | Назначение |
|---|---|
user.current | профиль текущего пользователя (по токену) |
user.get | выборка сотрудников с фильтром |
user.search | поиск по имени, должности, отделу |
user.add | пригласить/создать пользователя |
user.update | изменить профиль |
user.fields | список доступных полей |
user.fields — он вернёт актуальный набор системных и пользовательских полей вашего портала, включая привязку к отделам UF_DEPARTMENT.Текущий пользователь
Метод user.current не требует параметров и возвращает профиль владельца токена. Это удобная точка входа для приложений: узнать, кто авторизован, его ID, e-mail, отделы и права.
GET /rest/1/xxxx/user.current.json
В ответе — поля ID, NAME, LAST_NAME, EMAIL, WORK_POSITION, UF_DEPARTMENT (массив ID отделов) и другие. Для вебхука «текущим» будет пользователь, от имени которого вебхук создан.
Выборка user.get: фильтры и сортировка
user.get принимает FILTER, SORT, ORDER и параметр листания start. Пример — активные сотрудники нужного отдела:
POST /rest/1/xxxx/user.get.json
{"FILTER":{"ACTIVE":true,"UF_DEPARTMENT":5},"SORT":"LAST_NAME","ORDER":"ASC"}
Частые поля фильтра:
ACTIVE— только активные (не уволенные) учётки;UF_DEPARTMENT— принадлежность отделу;NAME,LAST_NAME,EMAIL— по полям профиля (поддерживают маску%);USER_TYPE—employeeилиextranet.
Метод возвращает до 50 записей; далее листаем через start, ориентируясь на next. Параметр ADMIN_MODE=true (при правах администратора) снимает часть ограничений видимости.
Поиск сотрудников
user.search предназначен для нечёткого поиска по видимым текущему пользователю данным. Он удобнее user.get, когда нужно найти человека по фрагменту ФИО или должности:
{"FILTER":{"FIND":"Иванов"},"SORT":"LAST_NAME","ORDER":"asc"}
Поле FIND ищет сразу по нескольким полям профиля. В отличие от user.get, метод учитывает права видимости — сотрудник экстранета не «увидит» лишнего.
user.get с фильтром по ID — это быстрее и однозначнее, чем полнотекстовый поиск.Создание и обновление
Изменять учётные записи можно только с правами администратора портала. user.add создаёт (или приглашает) сотрудника:
POST /rest/1/xxxx/user.add.json
{"NAME":"Пётр","LAST_NAME":"Сидоров","EMAIL":"p.sidorov@example.com","WORK_POSITION":"Менеджер","UF_DEPARTMENT":[5],"EXTRANET":"N"}
user.update меняет поля существующего пользователя по ID. Отдел UF_DEPARTMENT — множественное поле, всегда передавайте его массивом.
batch.Пользовательские поля и производительность
Кроме системных, у профиля есть пользовательские поля (UF), их список даёт user.userfields.list. Через них хранят табельные номера, коды из внешних систем, дополнительные контакты — и по ним же удобно связывать сотрудника с записями в 1С или CRM.
При выгрузке всего штата помните о лимитах REST (около 2 запросов в секунду). Стратегия та же, что и для других списков: batch для группировки, start для листания и точечные фильтры, чтобы не тянуть лишние записи.
Итог
Семейство user.* покрывает и чтение (current, get, search), и управление (add, update) сотрудниками. Ключевые детали — множественное UF_DEPARTMENT, права администратора для правки и аккуратное листание больших выборок.
Мы связываем справочник сотрудников Битрикс24 с кадровыми и учётными системами: единый источник данных, автоматическое заведение и деактивация, привязка по внешним ключам. Поможем спроектировать такой обмен и держать его стабильным.
Частые вопросы
Как узнать, кто авторизован в приложении?
Вызовите user.current без параметров — метод вернёт профиль владельца токена: ID, имя, e-mail, отделы. Для вебхука это создавший его пользователь.
Как получить сотрудников конкретного отдела?
Используйте user.get с фильтром UF_DEPARTMENT равным ID отдела и, при необходимости, ACTIVE=true, чтобы исключить уволенных.
Чем user.search отличается от user.get?
user.search — нечёткий поиск по полю FIND с учётом прав видимости, удобен для поиска по фрагменту ФИО. user.get — точная выборка по конкретным полям фильтра.
Сколько пользователей возвращается за один запрос?
До 50 записей. Для следующей страницы передавайте параметр start со значением из поля next в ответе метода.
Как записать сотрудника в несколько отделов?
UF_DEPARTMENT — множественное поле, передавайте массив ID отделов при user.add или user.update.
Нужны ли особые права для user.add?
Да, создавать и менять учётные записи может только администратор портала. Обычный пользователь получит ошибку доступа при вызове user.add и user.update.
Где хранить внешний идентификатор сотрудника?
В пользовательском поле (UF). Список таких полей даёт user.userfields.list; по UF удобно связывать профиль с записями в 1С или CRM.
Как отличить сотрудника от экстранет-пользователя?
По полю USER_TYPE (employee или extranet) либо флагу экстранета в фильтре. Права видимости у экстранет-пользователей ограничены.
Поможем с настройкой и поддержкой Для разработчиков
Поможем с настройкой, доработкой и поддержкой Для разработчиков.