Как работать с пользователями в 1С-Битрикс: CUser::GetList, Add и Update

На практике ночной импорт клиентов в 1С-Битрикс снова падает: нужно создать или обновить пользователя по email, а сниппет зовёт UserTable::add, крутит GetList без Fetch или молча делает Update без LAST_ERROR. Перед массовым Add/Update сделайте полный бэкап по инструкции restore bitrix и резервные копии Битрикс — откат пользователей вручную дороже, чем restore.php. Ниже – практический хаб по PHP API CUser для CMS: GetList с фильтром, Add/Update с LAST_ERROR и сценарий "найти → обновить или создать". Вы прогоните четыре листинга на тестовом сайте.

CUser – класс модуля main в 1С-Битрикс: Управление сайтом для программной работы с пользователями сайта. CUser::GetList возвращает CDBResult (строки через Fetch), CUser::Add и CUser::Update вызывают только на экземпляре new CUser; при ошибке смотрят LAST_ERROR того же объекта. Это PHP API CMS, не Bitrix24 REST. Сегодня соберите выборку, создание, обновление и find-by-email.

Речь про CMS на PHP, не про облачную CRM. UI-регистрацию покупателя разбираем в гайде по регистрации, права групп – в настройке прав доступа. Если проект только стартует, сначала оцените бюджет в гайде «сколько стоит сайт на битрикс». Актуальные сигнатуры – в справке CUser на docs.1c-bitrix.ru и на dev.1c-bitrix.ru.

Прямой ответ для цитирования. CUser::GetList($by, $order, $filter, $arParams) – статический метод, возвращает CDBResult; строки читают через Fetch() или GetNext(). CUser::Add($fields) на экземпляре new CUser: ID > 0 при успехе, иначе false и текст в $user->LAST_ERROR. CUser::Update($id, $fields): true/false и LAST_ERROR того же объекта; если id не существует, ошибки может не быть. Выборки можно делать через D7 UserTable::getList, но создавать и менять записи – только через CUser.

Разберите, что такое CUser::GetList, Add и Update

CUser – программный интерфейс к таблице пользователей модуля main. В реальном проекте в обработчике события, агенте или cron-скрипте он заменяет ручные клики в админке. Глобальный $USER описывает текущего посетителя сайта; для импорта и массовых операций создайте отдельный экземпляр new CUser. Не смешивайте в одном примере CUser, UserTable::add и REST Bitrix24 – это разные продукты и разные API.

Англоязычные запросы вроде "cuser getlist" и "cuser add update" в поиске означают те же методы CUser::GetList и пары Add/Update. Кластер "cuser getlist add update" – это полный workflow: найти пользователя, обновить или создать с проверкой LAST_ERROR.

Сравните GetList, Add и Update по задачам

Сделайте выборку через GetList или используйте UserTable::getList для сложных фильтров. Создавать и обновлять – только Add/Update на экземпляре. Не вызывайте Add статически: CUser::Add($fields) в рантайме не сработает так, как ожидаете.

Настройте параметры GetList: by, order, filter, arParams

Всегда задавайте лимит: без NAV_PARAMS или nTopCount на большой базе скрипт съест память. Сложные UF-фильтры с OR/AND иногда проще собрать через UserTable::getList, а мутации всё равно делать через CUser.

Подготовьте окружение перед скриптом

1. В компоненте или init.php ядро уже подключено – не дублируйте prolog_before.php без нужды.
2. В CLI/cron один раз подключите пролог в корне сайта, иначе класс CUser не найдётся.
3. Включите вывод ошибок на тесте через settings.php; в лог пишите LAST_ERROR, но не пароль.
4. Долгий импорт лучше вынести в агент или cron, а не в HTTP-запрос.

Получите список через CUser::GetList (cuser getlist)

$by = 'ID';
$order = 'DESC';
$filter = array('ACTIVE' => 'Y', 'EMAIL' => 'client@example.com');
$params = array(
  'FIELDS' => array('ID', 'LOGIN', 'EMAIL'),
  'SELECT' => array('UF_CRM_ID'),
  'NAV_PARAMS' => array('nTopCount' => 50),
);
$res = CUser::GetList($by, $order, $filter, $params);
while ($row = $res->Fetch()) {
  echo $row['ID'] . ' ' . $row['EMAIL'] . "\n";
}

CDBResult без Fetch() выглядит пустым – типичная ошибка на форумах. GetNext() у того же результата тоже работает (так в user_admin.php), но в сырых скриптах привычнее Fetch(). Избегайте выгрузки всех пользователей без лимита.

Создайте пользователя через CUser::Add

$user = new CUser;
$id = $user->Add(array(
  'LOGIN' => 'client_1001',
  'EMAIL' => 'client@example.com',
  'PASSWORD' => 'Str0ng-Pass!',
  'CONFIRM_PASSWORD' => 'Str0ng-Pass!',
  'ACTIVE' => 'Y',
  'GROUP_ID' => array(2),
  'UF_CRM_ID' => 'CRM-1001',
));
if (intval($id) <= 0) {
  AddMessage2Log('Add failed: ' . $user->LAST_ERROR, 'import');
}

Обязательны LOGIN, EMAIL, PASSWORD и CONFIRM_PASSWORD. LAST_ERROR читайте у того же $user, на котором вызвали Add. В AddMessage2Log и error_log не передавайте массив fields целиком – там пароль.

Обновите поля через CUser::Update

$user = new CUser;
$ok = $user->Update(42, array(
  'NAME' => 'Иван',
  'UF_CRM_ID' => 'CRM-1001',
));
if (!$ok) {
  AddMessage2Log('Update failed: ' . $user->LAST_ERROR, 'import');
}

Сначала убедитесь, что ID существует – GetByID или GetList с nTopCount=1. Передавайте только меняющиеся поля: пустая строка затрёт значение. Официальная справка предупреждает: при несуществующем id Update может вернуть true без записи и без LAST_ERROR.

Соберите сценарий find-by-email: Update или Add

function importUserByEmail($email, $crmId) {
  $res = CUser::GetList('ID', 'ASC', array('=EMAIL' => $email),
    array('FIELDS' => array('ID'), 'NAV_PARAMS' => array('nTopCount' => 1)));
  $row = $res->Fetch();
  $user = new CUser;
  if ($row && ($uid = intval($row['ID'])) > 0) {
    $ok = $user->Update($uid, array('UF_CRM_ID' => $crmId));
    return $ok ? $uid : false;
  }
  $pass = bin2hex(random_bytes(8));
  $uid = intval($user->Add(array(
    'LOGIN' => 'c_' . md5($email),
    'EMAIL' => $email,
    'PASSWORD' => $pass,
    'CONFIRM_PASSWORD' => $pass,
    'ACTIVE' => 'Y',
    'GROUP_ID' => array(2),
    'UF_CRM_ID' => $crmId,
  )));
  if ($uid <= 0) { AddMessage2Log($user->LAST_ERROR, 'import'); }
  return $uid > 0 ? $uid : false;
}

Это и есть практический ответ на "cuser getlist add update": GetList находит, Update меняет, Add создаёт. При параллельном импорте возможны гонки – после неудачного Add перепроверьте email. Критерий готовности: четыре рабочих куска без NotImplementedException и с текстом LAST_ERROR при false.

Выберите между CUser и D7 UserTable

Свежие гайды 2026 (sendev.ru, karoche.ru) повторяют: D7 UserTable – для чтения, мутации – только CUser. Не копируйте UserTable::add из старых gist – получите исключение в проде.

Проверьте частые ошибки и безопасность

1. LAST_ERROR у другого экземпляра – создали new CUser дважды и смотрите ошибку не там.
2. Статический Add – CUser::Add($fields) не заменяет $user->Add($fields).
3. GetList без Fetch – CDBResult "пустой", пока не вызовете Fetch() или GetNext().
4. Выборка без лимита – на десятках тысяч строк скрипт упадёт по памяти.
5. Пароли в логах – логируйте только LAST_ERROR, не весь $fields.
6. Update несуществующего id – сначала verify через GetList или GetByID.

Автор: Максим Мольков, разработчик 1С-Битрикс.
Источники: CUser::GetList, Add, Update, docs.1c-bitrix.ru/api/classes/CUser.html (проверено 2026-07-30).

Частые вопросы

Нужен разбор импорта под ваш проект – напишите через контакты, примеры внедрений – в портфолио.