Метод user.get возвращает список пользователей портала Битрикс24 с гибкой фильтрацией и сортировкой. Он лежит в основе синхронизации сотрудников с внешними системами, подстановки исполнителей задач и построения справочников. Разберём синтаксис фильтров, постраничную выборку и работу с уволенными сотрудниками.
Базовый вызов user.get
Без параметров user.get возвращает активных пользователей порциями по 50 записей. Все аргументы опциональны: фильтр, сортировка и постраничная навигация.
POST https://portal.bitrix24.ru/rest/1/xxxx/user.get.json
{ "FILTER": { "ACTIVE": true }, "SORT": "LAST_NAME", "ORDER": "ASC" }
Каждый пользователь описывается набором полей: ID, NAME, LAST_NAME, EMAIL, WORK_POSITION, UF_DEPARTMENT (массив ID подразделений), ACTIVE и другие. Полный перечень доступных полей отдаёт метод user.fields.
UF_DEPARTMENT связывает сотрудника с оргструктурой. Именно по нему строят выборки «все из отдела продаж», сопоставляя с данными метода department.get.Синтаксис фильтров
Объект FILTER поддерживает префиксы операторов перед именем поля — как в других списочных методах Битрикс24.
| Префикс | Значение |
|---|---|
% | Подстрока (LIKE) |
= | Точное совпадение |
>, < | Больше / меньше |
>=, <= | Не меньше / не больше |
! | Не равно |
Например, поиск по части фамилии и конкретному подразделению:
{ "FILTER": { "%LAST_NAME": "Ивано", "UF_DEPARTMENT": 15, "ACTIVE": true } }
Условия внутри FILTER объединяются по И. Для сложной логики ИЛИ выполняйте несколько запросов или используйте user.search.
Поиск: user.search
Метод user.search предназначен для «человеческого» поиска по нескольким полям сразу и учитывает расширенные атрибуты профиля. Он удобнее там, где пользователь вводит строку в поле поиска интерфейса.
- Ищет по имени, фамилии, должности, email, телефону;
- Поддерживает фильтрацию по подразделению через
UF_DEPARTMENT; - Возвращает те же поля, что и user.get.
Для строгих интеграционных выборок (по точному ID, статусу, дате) предпочтителен user.get с явным FILTER. Для интерактивного автопоиска — user.search.
Постраничная выборка
user.get отдаёт максимум 50 записей за вызов. Чтобы получить следующую порцию, передайте параметр start — смещение, кратное 50.
{ "FILTER": { "ACTIVE": true }, "start": 50 }
В ответе присутствует поле total — общее число записей под фильтр, и next — значение start для следующей страницы, если она есть.
batch (до 50 команд), либо используйте start: -1 чтобы отключить подсчёт total и ускорить каждый запрос.Уволенные и особые категории
По умолчанию user.get возвращает только активных сотрудников. Чтобы получить уволенных, явно снимите фильтр по активности или запросите неактивных:
{ "FILTER": { "ACTIVE": false } }
Дополнительные категории учётных записей:
- Экстранет-пользователи — внешние участники групп;
- Приглашённые — ещё не подтвердившие регистрацию;
- Email-пользователи — созданные для CRM без входа на портал.
Параметр ADMIN_MODE: "Y" заставляет метод вернуть данные с правами администратора (если у аккаунта интеграции они есть) — это снимает ограничения видимости, наложенные настройками приватности профилей.
Практика синхронизации
Типовые задачи, которые закрывает user.get при интеграции:
- Справочник исполнителей. Выгрузить активных сотрудников для подстановки в RESPONSIBLE_ID при постановке задач;
- Сопоставление с внешней системой. Хранить пары «email → ID пользователя», чтобы связывать записи;
- Оргструктура. Строить дерево «отдел → сотрудники» через UF_DEPARTMENT и department.get;
- Актуализация. Периодически сверять статус ACTIVE, чтобы не назначать задачи уволенным.
Для надёжного сопоставления опирайтесь на ID, а не на email или ФИО — они могут меняться. Email используйте как вторичный ключ при первичной привязке.
Итог
Метод user.get с фильтрами, сортировкой и постраничной навигацией — рабочий инструмент для синхронизации сотрудников и построения справочников. Для интерактивного поиска подойдёт user.search, для массовой выгрузки — batch и отключение подсчёта total. Не забывайте про уволенных, режим ADMIN_MODE и опору на стабильный ID при сопоставлении.
Мы настраиваем двустороннюю синхронизацию пользователей Битрикс24 с 1С, ERP и корпоративными каталогами: сопоставление по ключам, обработку увольнений и переводов между отделами, устойчивую пакетную выгрузку. В результате справочники в системах не расходятся, а задачи и заявки всегда уходят актуальным сотрудникам.
Частые вопросы
Сколько записей возвращает user.get за один вызов?
Максимум 50. Для следующей порции передайте параметр start со смещением, кратным 50. Общее число записей под фильтр приходит в поле total.
Как искать пользователя по части фамилии?
Используйте префикс % перед полем: {"FILTER": {"%LAST_NAME": "Ивано"}}. Это выборка по подстроке, аналог LIKE.
Чем user.search отличается от user.get?
user.search рассчитан на интерактивный поиск сразу по нескольким полям профиля, а user.get даёт строгую фильтрацию по конкретным полям для интеграционных выборок.
Как получить уволенных сотрудников?
По умолчанию отдаются только активные. Передайте {"FILTER": {"ACTIVE": false}}, чтобы получить неактивных пользователей.
Как связать сотрудника с подразделением?
Поле UF_DEPARTMENT содержит массив ID подразделений. Сопоставьте его с оргструктурой, полученной методом department.get.
Как ускорить полную выгрузку пользователей?
Запрашивайте страницы пакетом через batch и используйте start: -1, чтобы отключить подсчёт total. Это снижает нагрузку на каждый запрос.
По какому полю сопоставлять пользователей с внешней системой?
Опирайтесь на стабильный ID пользователя. Email и ФИО могут меняться, поэтому их используйте как вторичный ключ при первичной привязке.
Поможем с настройкой и поддержкой Для разработчиков
Поможем с настройкой, доработкой и поддержкой Для разработчиков.