CCrmStatus::GetList: получение справочников в CRM Битрикс

Область применения и ключевые сущности

Метод используется для получения списка статусов в следующих контекстах:

• Статусы лидов (STATUS) — определяют этап обработки лида: новый, в работе, конвертирован, нерелевантный и др.. Семантика статуса (новый, в работе, закрыт) хранится в поле STATUS_SEMANTIC_ID.
• Стадии сделок (DEAL_STAGE) — этапы воронки продаж, отображаемые в канбане. Для сделок с несколькими направлениями идентификатор имеет вид DEAL_STAGE_XX, где XX — ID направления.
• Источники лидов/сделок (SOURCE) — каналы привлечения клиентов.
• Типы компаний (COMPANY_TYPE) — классификация компаний (клиент, партнер, конкурент и т.д.).
• Типы контактов (CONTACT_TYPE) — аналогичная классификация для контактов.
• Типы сделок (DEAL_TYPE) — классификация сделок (продажа, услуга и т.п.).
• Обращения (HONORIFIC) — варианты обращения в карточке лида/контакта.
• Количество сотрудников (EMPLOYEES) — диапазоны численности персонала компании.
• Сфера деятельности (INDUSTRY) — отрасль компании-клиента.

Также метод применим к стадиям смарт-процессов (DYNAMIC_{entityTypeId}_STAGE_{categoryId}) и другим справочникам, которые могут быть расширены в проекте.

Параметры метода

Метод имеет следующую сигнатуру:

php

public static function GetList($arSort = array(), $arFilter = array())

Параметр $arSort (сортировка)

Определяет порядок сортировки элементов справочника. Представляет собой ассоциативный массив, где ключ — поле сортировки, значение — направление (ASC или DESC). Поддерживаемые ключи:

• ID — уникальный идентификатор записи
• ENTITY_ID — символьный код справочника
• STATUS_ID — символьный код значения
• NAME — название значения
• SORT — порядок сортировки (используется чаще всего)
• SYSTEM — флаг системного значения (Y/N)
• CATEGORY_ID — идентификатор категории
• SEMANTICS — семантика статуса

Если параметр не задан, используется сортировка по CS.ID DESC.

Параметр $arFilter (фильтрация)

Позволяет отфильтровать результаты по одному или нескольким критериям. Поддерживаемые ключи:

• ID — фильтр по уникальному идентификатору
• ENTITY_ID — фильтр по типу справочника (основной и наиболее часто используемый критерий)
• STATUS_ID — фильтр по символьному коду значения
• NAME — фильтр по названию (с поддержкой поисковых шаблонов)
• SORT — фильтр по значению сортировки
• SYSTEM — фильтр по системному флагу (Y или N)
• CATEGORY_ID — фильтр по идентификатору категории
• SEMANTICS — фильтр по семантике

Возвращаемое значение

Метод возвращает объект результата запроса CDBResult, который содержит записи таблицы b_crm_status. Перебор результатов осуществляется через метод fetch() в цикле while.

Практические примеры

Пример 1. Получение всех статусов лида

php

// Подключаем модуль CRM
if (\Bitrix\Main\Loader::includeModule('crm')) {
    $leadStatuses = array();
    $dbResult = CCrmStatus::GetList(
        array('SORT' => 'ASC'),           // сортировка по порядку
        array('ENTITY_ID' => 'STATUS')    // фильтр по типу справочника
    );
    
    while ($status = $dbResult->fetch()) {
        $leadStatuses[$status['STATUS_ID']] = $status['NAME'];
    }
    
    // Результат: ['NEW' => 'Новый', 'IN_PROCESS' => 'В работе', ...]
    print_r($leadStatuses);
}

Пример 2. Получение стадий сделок

php

$dealStages = array();
$dbResult = CCrmStatus::GetList(
    array('SORT' => 'ASC'),
    array('ENTITY_ID' => 'DEAL_STAGE')
);

while ($stage = $dbResult->fetch()) {
    $dealStages[$stage['STATUS_ID']] = array(
        'NAME' => $stage['NAME'],
        'SORT' => $stage['SORT'],
        'COLOR' => $stage['COLOR'] ?? ''      // цвет в канбане
    );
}

Пример 3. Получение источников с полным набором полей

php

$sources = array();
$dbResult = CCrmStatus::GetList(
    array('SORT' => 'ASC'),
    array('ENTITY_ID' => 'SOURCE')
);

while ($source = $dbResult->fetch()) {
    $sources[$source['STATUS_ID']] = array(
        'NAME' => $source['NAME'],
        'NAME_INIT' => $source['NAME_INIT'],   // исходное название
        'SYSTEM' => $source['SYSTEM'],         // системный ли статус
        'SORT' => $source['SORT']
    );
}

Пример 4. Сложный фильтр: все системные статусы сделок

php

$systemDealStages = array();
$dbResult = CCrmStatus::GetList(
    array('SORT' => 'ASC'),
    array(
        'ENTITY_ID' => 'DEAL_STAGE',
        'SYSTEM' => 'Y'                         // только системные статусы
    )
);

while ($stage = $dbResult->fetch()) {
    $systemDealStages[$stage['STATUS_ID']] = $stage['NAME'];
}

Пример 5. Получение конкретного статуса по ID

php

$specificStatus = null;
$dbResult = CCrmStatus::GetList(
    array(),
    array(
        'ENTITY_ID' => 'STATUS',
        'STATUS_ID' => 'CONVERTED'              // статус "Конвертирован"
    )
);

if ($status = $dbResult->fetch()) {
    $specificStatus = $status['NAME'];
    echo "Название статуса: " . $specificStatus;
}

Пример 6. Фильтрация по нескольким критериям

php

$filteredStatuses = array();
$dbResult = CCrmStatus::GetList(
    array('SORT' => 'ASC'),
    array(
        'ENTITY_ID' => 'DEAL_STAGE',
        'SYSTEM' => 'N',                         // только пользовательские
        '!STATUS_ID' => 'WON'                    // исключая успешную стадию
    )
);

while ($stage = $dbResult->fetch()) {
    $filteredStatuses[$stage['STATUS_ID']] = $stage['NAME'];
}

Альтернативные методы

Для работы со справочниками также доступны:

• CCrmStatus::GetStatusList($entityId) — возвращает массив STATUS_ID => NAME для указанного справочника.
• CCrmStatus::GetStatusListEx($entityId) — возвращает расширенный массив с дополнительными полями (SORT, SYSTEM, COLOR и др.).
• CCrmStatus::GetStatus($entityId, $statusId) — получает конкретную запись по идентификатору сущности и статуса с кешированием на уровне статического свойства.
• CCrmStatus::GetEntityTypes() — возвращает описание всех типов справочников.

Метод GetStatusListEx предпочтительнее, если требуется получить не только названия, но и мета-информацию, так как он инкапсулирует логику формирования справочников и может использовать кеширование.

Особенности и рекомендации

1. Обязательное подключение модуля: Перед вызовом любого метода CRM необходимо подключить модуль через CModule::IncludeModule('crm') или \Bitrix\Main\Loader::includeModule('crm').

2. Структура таблицы b_crm_status: Основные поля: ID, ENTITY_ID (код справочника), STATUS_ID (код значения), NAME (название), SORT (порядок), SYSTEM (флаг системности). Поле NAME_INIT хранит исходное системное название и может использоваться для сброса изменений.

3. Порядок сортировки: Рекомендуется сортировать по полю SORT, так как это поле отражает порядок, заданный пользователем в настройках CRM.

4. Кеширование: При частых вызовах одного и того же справочника внутри одного запроса рекомендуется использовать кеширование результатов на уровне приложения.

5. Производительность: CCrmStatus::GetList выполняет прямой запрос к базе данных без встроенного кеширования. При интенсивном использовании данных справочников рассмотрите кеширование через статические переменные или механизмы кеширования Битрикс.

6. Работа со смарт-процессами: Для смарт-процессов идентификатор ENTITY_ID формируется по шаблону DYNAMIC_{entityTypeId}_STAGE_{categoryId}. Значение entityTypeId можно получить из адресной строки при просмотре списка элементов смарт-процесса.

Заключение

CCrmStatus::GetList — это основной инструмент для программного доступа к справочникам CRM в коробочной версии Битрикс24. Он обеспечивает гибкую фильтрацию и сортировку, позволяя получать любые справочные данные: от статусов лидов до стадий сделок и типов компаний. Понимание этого метода необходимо каждому разработчику, работающему с CRM-модулем Битрикс.