Получение списка элементов смарт-процесса через API в Битрикс24

Перед использованием кода убедитесь, что ядро Битрикс подключено. Если оно не подключено, добавьте в начало:

php

require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_before.php");

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

Метод Service\Container::getInstance()->getFactory($typeId) используется для работы с элементами смарт-процессов в следующих контекстах:

• Получение списка элементов — выборка всех элементов процесса с фильтрацией по любым полям
• Фильтрация по пользовательским полям (UF-поля) — поиск элементов по уникальным идентификаторам, номерам или статусам
• Фильтрация по стандартным полям — ID, заголовок, дата создания, ответственный и т.д.
• Интеграция с внешними системами — выгрузка данных из смарт-процессов в сторонние сервисы
• Автоматизация бизнес-процессов — получение элементов для дальнейшей обработки или модификации
• Аналитика — сбор статистики по количеству элементов, стадиям и воронкам

Основные поля элемента смарт-процесса

Обратите внимание: структура полей зависит от настроек конкретного смарт-процесса. Ниже приведены основные системные поля.

Поле	Описание
ID	Уникальный идентификатор элемента
TITLE	Название элемента
CREATED_DATE	Дата и время создания
MODIFY_DATE	Дата и время последнего изменения
CREATED_BY	ID пользователя, создавшего элемент
MODIFY_BY	ID пользователя, изменившего элемент
ASSIGNED_BY_ID	ID ответственного пользователя
STAGE_ID	Идентификатор стадии (воронки)
CATEGORY_ID	Идентификатор категории смарт-процесса
UF_CRM_*	Пользовательские поля (динамические, создаются в настройках процесса)

Метод получения фабрики и списка элементов

Для работы с элементами смарт-процесса используется фабрика, получаемая через контейнер сервисов. Класс \Bitrix\Crm\Service\Container предоставляет метод getFactory() для создания экземпляра фабрики по идентификатору типа CRM.

Сигнатура метода

php

public function getFactory(int $typeId): ?\Bitrix\Crm\Service\Factory

Метод возвращает объект фабрики или null, если тип не найден.

Метод Factory::getItems()

Для получения списка элементов используется метод getItems() фабрики.

php

public function getItems(array $parameters = []): array

Параметр $parameters

Метод принимает ассоциативный массив со следующими ключами:

filter — фильтрация записей

Важно! Для фильтрации по пользовательским полям используйте их точные имена (например, UF_CRM_6_SNOMER2).

Основные поддерживаемые ключи для фильтрации:

• =ID — идентификатор элемента
• =TITLE — заголовок элемента
• =CREATED_BY — ID создателя
• =ASSIGNED_BY_ID — ID ответственного
• =STAGE_ID — идентификатор стадии
• =CATEGORY_ID — идентификатор категории
• >=CREATED_DATE — дата создания (от)
• <=CREATED_DATE — дата создания (до)
• =UF_CRM_* — пользовательское поле (точное совпадение)
• %UF_CRM_* — пользовательское поле (поиск по подстроке)

select — выбираемые поля

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

php

'select' => ['ID', 'TITLE', 'ASSIGNED_BY_ID', 'UF_CRM_6_SNOMER2']

order — сортировка

php

'order' => ['CREATED_DATE' => 'DESC']  // сначала новые

limit и offset — ограничения

Для постраничной навигации:

php

'limit' => 50,
'offset' => 0

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

Пример 1. Получение всех элементов смарт-процесса

php

<?php
require_once $_SERVER['DOCUMENT_ROOT'] . '/bitrix/modules/main/include/prolog_before.php';

use Bitrix\Main\Loader;
use Bitrix\Crm\Service\Container;

$typeId = 134; // Идентификатор типа смарт-процесса

$factory = Container::getInstance()->getFactory($typeId);

if (!$factory) {
    die('Смарт-процесс с таким ID не найден');
}

$allItems = $factory->getItems([
    'order' => ['CREATED_DATE' => 'DESC'],
    'limit' => 100,
]);

foreach ($allItems as $item) {
    $data = $item->getData();
    echo 'ID: ' . $data['ID'] . ', TITLE: ' . $data['TITLE'] . "\n";
}
?>

Пример 2. Фильтрация по пользовательскому полю (точное совпадение)

php

<?php
$typeId = 134;
$factory = Container::getInstance()->getFactory($typeId);

$items = $factory->getItems([
    'filter' => [
        'UF_CRM_6_SNOMER2' => 'k378ck', // Фильтрация по пользовательскому полю
    ],
]);

foreach ($items as $item) {
    $data = $item->getData();
    echo 'Найден элемент: ' . $data['TITLE'] . ' (ID: ' . $data['ID'] . ')' . "\n";
}
?>

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

php

<?php
$items = $factory->getItems([
    'filter' => [
        '=STAGE_ID' => 'WON',              // Фильтр по стадии "Успешно"
        '=ASSIGNED_BY_ID' => 60,           // Фильтр по ответственному
    ],
    'order' => ['CREATED_DATE' => 'ASC'],
]);
?>

Пример 4. Выборка конкретных полей для оптимизации

php

<?php
$items = $factory->getItems([
    'select' => ['ID', 'TITLE', 'ASSIGNED_BY_ID', 'UF_CRM_6_SNOMER2', 'STAGE_ID'],
    'filter' => [
        '>=CREATED_DATE' => '01.07.2026 00:00:00',
        '<=CREATED_DATE' => '31.07.2026 23:59:59',
    ],
    'limit' => 50,
]);
?>

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

php

<?php
$elementId = 12345;

$items = $factory->getItems([
    'filter' => [
        '=ID' => $elementId,
    ],
    'limit' => 1,
]);

if ($items->count() > 0) {
    $item = $items->getFirst();
    $data = $item->getData();
    echo 'Элемент найден: ' . $data['TITLE'];
} else {
    echo 'Элемент не найден';
}
?>

Пример 6. Постраничная навигация (пагинация)

php

<?php
$page = 1;
$pageSize = 20;

$items = $factory->getItems([
    'offset' => ($page - 1) * $pageSize,
    'limit' => $pageSize,
    'order' => ['CREATED_DATE' => 'DESC'],
]);

foreach ($items as $item) {
    $data = $item->getData();
    // Обработка элемента
}
?>

Пример 7. Поиск по подстроке в пользовательском поле

php

<?php
$items = $factory->getItems([
    'filter' => [
        '%UF_CRM_6_SNOMER2' => 'k37', // Поиск по части значения
    ],
]);
?>

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

1. Проверка существования фабрики

Всегда проверяйте, вернула ли фабрика объект, перед вызовом методов:

php

$factory = Container::getInstance()->getFactory($typeId);
if (!$factory) {
    // Обработка ошибки
}

2. Правильное именование пользовательских полей

Пользовательские поля имеют формат UF_CRM_*. Точное имя поля можно посмотреть в настройках смарт-процесса или в таблице b_crm_field.

php

'filter' => [
    'UF_CRM_6_SNOMER2' => $value, // Замените на ваше имя поля
]

3. Работа с коллекцией элементов

Метод getItems() возвращает массив элементов. Для получения данных используйте метод getData() у каждого элемента:

php

$items = $factory->getItems([...]);
foreach ($items as $item) {
    $data = $item->getData();        // Ассоциативный массив всех полей
    $id = $item->getId();            // Альтернативный способ получения ID
    $title = $item->getTitle();      // Альтернативный способ получения заголовка
}

4. Производительность

При большом количестве элементов обязательно используйте limit и offset:

php

$params = [
    'filter' => $filter,
    'order' => ['CREATED_DATE' => 'DESC'],
    'limit' => 100,
    'offset' => 0,
];

5. Формат даты

При фильтрации по дате используйте формат 'd.m.Y H:i:s':

php

$filter = [
    '>=CREATED_DATE' => '17.07.2026 00:00:00',
    '<=CREATED_DATE' => '17.07.2026 23:59:59',
];

Заключение

Service\Container::getInstance()->getFactory($typeId)->getItems() — это основной инструмент для программного доступа к элементам смарт-процессов в коробочной версии Битрикс24. Он обеспечивает гибкую фильтрацию и сортировку, позволяя получать элементы по идентификаторам, пользовательским полям, стадиям и другим параметрам.

Ключевые моменты:

1. Идентификатор типа ($typeId) можно узнать в настройках смарт-процесса или через API

2. Всегда проверяйте существование фабрики перед работой с ней

3. Для фильтрации по пользовательским полям используйте точные имена вида UF_CRM_*

4. Используйте select для оптимизации запросов, если не нужны все поля

5. Применяйте limit и offset для постраничной навигации при большом количестве элементов

Понимание этого метода необходимо каждому разработчику, работающему с пользовательскими смарт-процессами в Битрикс24, особенно при реализации интеграций, автоматизированных отчётов и внешних выгрузок.