Работа с делами (активностями) в CRM Битрикс24 через ORM

16 июля 2026

Полезное

Введение

При разработке на «коробочной» версии Битрикс24 часто возникает задача программного получения всех дел и активностей, связанных с различными сущностями CRM — лидами, сделками, контактами и компаниями. Универсальным инструментом для этого является ORM-класс \Bitrix\Crm\ActivityTable, который предоставляет доступ к таблице b_crm_act, где хранятся все типы активностей: звонки, встречи, задачи, письма, напоминания и другие действия.

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

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

Звонки — все исходящие и входящие звонки с данными о длительности, статусе и ответственном
Задачи — задачи, созданные в контексте сущности CRM, с дедлайнами и статусами выполнения
Встречи — запланированные встречи с указанием времени, места и участников
Напоминания — дела типа "Связаться с клиентом" с планируемой датой выполнения
Письма — отправленные и полученные письма, связанные с сущностью
Прочие активности — любые другие действия, зарегистрированные в карточке сущности

Типы сущностей CRM (OWNER_TYPE_ID)

Для правильной фильтрации важно знать идентификаторы типов сущностей:

OWNER_TYPE_ID	Сущность
1	Лид
2	Сделка
3	Контакт
4	Компания

ORM-метод ActivityTable::getList

ORM-класс \Bitrix\Crm\ActivityTable предоставляет метод getList() для выборки активностей с гибкой фильтрацией и сортировкой.

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

php

public static function getList(array $parameters = array())

Параметр $parameters

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

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

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

=ID — идентификатор активности
=OWNER_ID — идентификатор владельца (компании, контакта, сделки, лида)
=OWNER_TYPE_ID — тип владельца (1-4)
=TYPE_ID — тип активности (1 — встреча, 2 — звонок, 3 — задача, 4 — письмо, 5 — другое, 6 — напоминание)
=PROVIDER_ID — провайдер активности (например, VOXIMPLANT_CALL для звонков, CRM_TASKS_TASK для задач)
=STATUS — статус выполнения (0 — новое, 1 — в работе, 2 — завершено, 3 — отложено)
=COMPLETED — флаг завершенности (Y/N)
=RESPONSIBLE_ID — идентификатор ответственного
=DIRECTION — направление (0 — входящее, 1 — исходящее)
=CREATED — дата создания (с поддержкой операторов >=, <=, >, <)
=DEADLINE — срок выполнения
=SUBJECT — тема активности (поиск по точному совпадению)
%SUBJECT — поиск по теме с использованием LIKE (для частичного совпадения)
Важно: Все поля из таблицы b_crm_act могут использоваться в фильтре. Полный список полей приведен в разделе "Поля таблицы".

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

Указывается массив с полем сортировки и направлением (ASC или DESC):

php

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

Поддерживаемые поля для сортировки: ID, CREATED, DEADLINE, STATUS, RESPONSIBLE_ID, TYPE_ID и другие.

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

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

php

'select' => ['ID', 'SUBJECT', 'CREATED', 'STATUS', 'RESPONSIBLE_ID']

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

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

php

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

`runtime` — динамические поля (JOIN)

Для подключения связанных таблиц:

php

'runtime' => [
    new \Bitrix\Main\Entity\ReferenceField(
        'RESPONSIBLE_USER',
        \Bitrix\Main\UserTable::class,
        ['=this.RESPONSIBLE_ID' => 'ref.ID']
    ),
],

Поля таблицы b_crm_act

Поле	Тип	Описание
`ID`	int	Уникальный идентификатор
`TYPE_ID`	tinyint	Тип активности (1-6)
`PROVIDER_ID`	varchar(100)	Провайдер активности
`PROVIDER_TYPE_ID`	varchar(100)	Тип провайдера
`PROVIDER_GROUP_ID`	varchar(100)	Группа провайдера
`OWNER_ID`	int	ID владельца (лида, сделки, контакта, компании)
`OWNER_TYPE_ID`	int	Тип владельца (1-4)
`ASSOCIATED_ENTITY_ID`	int	ID связанной сущности
`SUBJECT`	varchar(512)	Тема активности
`DESCRIPTION`	longtext	Описание
`DESCRIPTION_TYPE`	tinyint	Тип описания (1 — текст, 2 — HTML)
`COMPLETED`	char(1)	Завершено (`Y`/`N`)
`IS_HANDLEABLE`	char(1)	Доступно для обработки
`RESPONSIBLE_ID`	int	Ответственный
`PRIORITY`	int	Приоритет
`NOTIFY_TYPE`	int	Тип уведомления
`NOTIFY_VALUE`	int	Значение уведомления
`LOCATION`	varchar(256)	Место проведения
`CREATED`	datetime	Дата создания
`LAST_UPDATED`	datetime	Дата последнего обновления
`START_TIME`	datetime	Время начала
`END_TIME`	datetime	Время окончания
`DEADLINE`	datetime	Срок выполнения
`CALENDAR_EVENT_ID`	int	ID события календаря
`PARENT_ID`	int	ID родительской активности
`THREAD_ID`	int	ID потока
`URN`	varchar(64)	Уникальный идентификатор
`ORIGIN_ID`	varchar(255)	ID во внешней системе
`ORIGINATOR_ID`	varchar(255)	Идентификатор внешней системы
`AUTHOR_ID`	int	Автор
`EDITOR_ID`	int	Редактор
`RESULT_STATUS`	int	Статус результата
`RESULT_STREAM`	int	Поток результата
`RESULT_SOURCE_ID`	varchar(255)	ID источника результата
`RESULT_MARK`	int	Оценка результата
`RESULT_VALUE`	decimal(18,4)	Значение результата
`RESULT_SUM`	decimal(18,4)	Сумма результата
`RESULT_CURRENCY_ID`	char(3)	Валюта результата
`AUTOCOMPLETE_RULE`	int	Правило автозавершения
`SEARCH_CONTENT`	mediumtext	Поисковый контент
`SETTINGS`	text	Настройки (сериализованный массив)
`STORAGE_ELEMENT_IDS`	text	ID файлов
`PROVIDER_PARAMS`	longtext	Параметры провайдера
`STORAGE_TYPE_ID`	tinyint	Тип хранилища

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

Метод возвращает объект \Bitrix\Main\ORM\Query\Result, который содержит записи таблицы b_crm_act. Перебор результатов осуществляется через метод fetch() в цикле while.

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

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

php

// Подключаем модуль CRM
if (\Bitrix\Main\Loader::includeModule('crm')) {
    $entityId = 12345;
    $entityTypeId = 2; // 2 — Сделка
    
    $result = \Bitrix\Crm\ActivityTable::getList([
        'filter' => [
            '=OWNER_ID' => $entityId,
            '=OWNER_TYPE_ID' => $entityTypeId,
        ],
        'order' => ['CREATED' => 'DESC'],
    ]);
    
    while ($activity = $result->fetch()) {
        echo 'ID: ' . $activity['ID'] . "\n";
        echo 'Тема: ' . $activity['SUBJECT'] . "\n";
        echo 'Создано: ' . $activity['CREATED']->toString() . "\n";
        echo 'Статус: ' . $activity['STATUS'] . "\n";
        echo '---' . "\n";
    }
}

Пример 2. Получение только звонков

php

$result = \Bitrix\Crm\ActivityTable::getList([
    'filter' => [
        '=OWNER_ID' => $entityId,
        '=OWNER_TYPE_ID' => $entityTypeId,
        '=PROVIDER_ID' => 'VOXIMPLANT_CALL',  // только звонки
    ],
    'order' => ['CREATED' => 'DESC'],
    'limit' => 50,
]);

while ($call = $result->fetch()) {
    $direction = $call['DIRECTION'] == 1 ? 'Исходящий' : 'Входящий';
    echo $direction . ' звонок: ' . $call['SUBJECT'] . "\n";
    echo 'Длительность: ' . ($call['END_TIME'] && $call['START_TIME'] 
        ? $call['END_TIME']->getTimestamp() - $call['START_TIME']->getTimestamp() . ' сек' 
        : 'неизвестно') . "\n";
}

Пример 3. Получение активных дел (в работе)

php

$result = \Bitrix\Crm\ActivityTable::getList([
    'filter' => [
        '=OWNER_ID' => $entityId,
        '=OWNER_TYPE_ID' => $entityTypeId,
        '=STATUS' => 1,  // 1 — В работе
        '=COMPLETED' => 'N',
    ],
    'order' => ['DEADLINE' => 'ASC'],
]);

while ($activity = $result->fetch()) {
    echo 'Дело: ' . $activity['SUBJECT'] . "\n";
    echo 'Срок: ' . ($activity['DEADLINE'] ? $activity['DEADLINE']->toString() : 'не указан') . "\n";
}

Пример 4. Получение активностей с фильтром по дате

php

$dateFrom = new \Bitrix\Main\Type\DateTime('2024-01-01 00:00:00');
$dateTo = new \Bitrix\Main\Type\DateTime('2024-12-31 23:59:59');

$result = \Bitrix\Crm\ActivityTable::getList([
    'filter' => [
        '=OWNER_ID' => $entityId,
        '=OWNER_TYPE_ID' => $entityTypeId,
        '>=CREATED' => $dateFrom,
        '<=CREATED' => $dateTo,
    ],
    'order' => ['CREATED' => 'DESC'],
]);

Пример 5. Получение активностей с JOIN на пользователей

php

$result = \Bitrix\Crm\ActivityTable::getList([
    'filter' => [
        '=OWNER_ID' => $entityId,
        '=OWNER_TYPE_ID' => $entityTypeId,
    ],
    'order' => ['CREATED' => 'DESC'],
    'select' => ['*'],
    'runtime' => [
        new \Bitrix\Main\Entity\ReferenceField(
            'RESPONSIBLE_USER',
            \Bitrix\Main\UserTable::class,
            ['=this.RESPONSIBLE_ID' => 'ref.ID']
        ),
    ],
]);

while ($activity = $result->fetch()) {
    $responsibleName = trim(
        $activity['RESPONSIBLE_USER']['NAME'] 
        . ' ' . $activity['RESPONSIBLE_USER']['LAST_NAME']
    );
    echo 'Ответственный: ' . ($responsibleName ?: $activity['RESPONSIBLE_ID']) . "\n";
}

Пример 6. Получение активностей с детализацией типа

php

$result = \Bitrix\Crm\ActivityTable::getList([
    'filter' => [
        '=OWNER_ID' => $entityId,
        '=OWNER_TYPE_ID' => $entityTypeId,
    ],
    'order' => ['CREATED' => 'DESC'],
]);

$typeMap = [
    1 => 'Встреча',
    2 => 'Звонок',
    3 => 'Задача',
    4 => 'Письмо',
    5 => 'Другое',
    6 => 'Напоминание',
];

$statusMap = [
    0 => 'Новое',
    1 => 'В работе',
    2 => 'Завершено',
    3 => 'Отложено',
];

$directionMap = [
    0 => 'Входящее',
    1 => 'Исходящее',
    2 => 'Исходящее',
];

while ($activity = $result->fetch()) {
    $typeName = $typeMap[$activity['TYPE_ID']] ?? 'Тип ' . $activity['TYPE_ID'];
    if ($activity['PROVIDER_ID'] == 'VOXIMPLANT_CALL') {
        $typeName = 'Звонок (VoIP)';
    } elseif ($activity['PROVIDER_ID'] == 'CRM_TASKS_TASK') {
        $typeName = 'Задача';
    } elseif ($activity['PROVIDER_ID'] == 'CRM_TODO') {
        $typeName = 'Напоминание';
    }
    
    echo 'ID: ' . $activity['ID'] . "\n";
    echo 'Тип: ' . $typeName . "\n";
    echo 'Тема: ' . $activity['SUBJECT'] . "\n";
    echo 'Статус: ' . ($statusMap[$activity['STATUS']] ?? $activity['STATUS']) . "\n";
    echo 'Направление: ' . ($directionMap[$activity['DIRECTION']] ?? '') . "\n";
    echo 'Создано: ' . $activity['CREATED']->toString() . "\n";
    echo '---' . "\n";
}

Пример 7. Получение активностей с расшифровкой настроек (SETTINGS)

php

$result = \Bitrix\Crm\ActivityTable::getList([
    'filter' => [
        '=OWNER_ID' => $entityId,
        '=OWNER_TYPE_ID' => $entityTypeId,
        '=TYPE_ID' => 6,  // Напоминания
    ],
]);

while ($activity = $result->fetch()) {
    $settings = unserialize($activity['SETTINGS'], ['allowed_classes' => false]);
    echo 'Дело: ' . $activity['SUBJECT'] . "\n";
    
    if (is_array($settings)) {
        echo 'Настройки: ' . implode(', ', array_keys($settings)) . "\n";
    }
}

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

php

$now = new \Bitrix\Main\Type\DateTime();

$result = \Bitrix\Crm\ActivityTable::getList([
    'filter' => [
        '=OWNER_ID' => $entityId,
        '=OWNER_TYPE_ID' => $entityTypeId,
        '=COMPLETED' => 'N',
        '<DEADLINE' => $now,  // срок истек
    ],
    'order' => ['DEADLINE' => 'ASC'],
]);

while ($activity = $result->fetch()) {
    echo 'Просрочено: ' . $activity['SUBJECT'] . "\n";
    echo 'Срок был: ' . $activity['DEADLINE']->toString() . "\n";
}

Пример 9. Поиск активностей по тексту

php

$result = \Bitrix\Crm\ActivityTable::getList([
    'filter' => [
        '=OWNER_ID' => $entityId,
        '=OWNER_TYPE_ID' => $entityTypeId,
        '%SUBJECT' => 'звонок',  // LIKE поиск
    ],
    'order' => ['CREATED' => 'DESC'],
]);

while ($activity = $result->fetch()) {
    echo $activity['SUBJECT'] . ' (' . $activity['CREATED']->toString() . ")\n";
}

Пример 10. Получение активностей конкретного ответственного

php

$responsibleId = 1787;

$result = \Bitrix\Crm\ActivityTable::getList([
    'filter' => [
        '=OWNER_ID' => $entityId,
        '=OWNER_TYPE_ID' => $entityTypeId,
        '=RESPONSIBLE_ID' => $responsibleId,
        '=COMPLETED' => 'N',  // только активные
    ],
    'order' => ['DEADLINE' => 'ASC'],
]);

while ($activity = $result->fetch()) {
    echo $activity['SUBJECT'] . ' (срок: ' . $activity['DEADLINE']->toString() . ")\n";
}

Пример 11. Группировка активностей по ответственным

php

$result = \Bitrix\Crm\ActivityTable::getList([
    'filter' => [
        '=OWNER_ID' => $entityId,
        '=OWNER_TYPE_ID' => $entityTypeId,
    ],
    'order' => ['CREATED' => 'DESC'],
    'select' => ['ID', 'SUBJECT', 'RESPONSIBLE_ID', 'STATUS'],
]);

$activitiesByUser = [];
while ($activity = $result->fetch()) {
    $userId = $activity['RESPONSIBLE_ID'];
    if (!isset($activitiesByUser[$userId])) {
        $activitiesByUser[$userId] = 0;
    }
    $activitiesByUser[$userId]++;
}

foreach ($activitiesByUser as $userId => $count) {
    echo 'Пользователь ' . $userId . ': ' . $count . " дел\n";
}

Пример 12. Получение активностей с названием владельца

php

$result = \Bitrix\Crm\ActivityTable::getList([
    'filter' => [
        '=OWNER_ID' => $entityId,
        '=OWNER_TYPE_ID' => $entityTypeId,
    ],
    'select' => ['*'],
    'runtime' => [
        new \Bitrix\Main\Entity\ReferenceField(
            'OWNER_ENTITY',
            \Bitrix\Crm\CompanyTable::class,
            ['=this.OWNER_ID' => 'ref.ID']
        ),
    ],
]);

while ($activity = $result->fetch()) {
    echo 'Владелец: ' . ($activity['OWNER_ENTITY']['TITLE'] ?? 'неизвестно') . "\n";
    echo 'Дело: ' . $activity['SUBJECT'] . "\n";
    echo '---' . "\n";
}

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

Обязательное подключение модуля: Перед вызовом любого метода CRM необходимо подключить модуль через \Bitrix\Main\Loader::includeModule('crm').
Типы сущностей (OWNER_TYPE_ID):
- 1 — Лид
- 2 — Сделка
- 3 — Контакт
- 4 — Компания
Типы активностей (TYPE_ID):
- 1 — Встреча
- 2 — Звонок
- 3 — Задача
- 4 — Письмо
- 5 — Другое
- 6 — Напоминание
Статусы дел (STATUS):
- 0 — Новое
- 1 — В работе
- 2 — Завершено
- 3 — Отложено
Направление (DIRECTION):
- 0 — Входящее
- 1 — Исходящее
- 2 — Исходящее
Провайдеры (PROVIDER_ID):
- VOXIMPLANT_CALL — звонки
- CRM_TASKS_TASK — задачи
- CRM_ACTIVITY_EMAIL — письма
- CRM_TODO — напоминания
Работа с датами: Поля CREATED, DEADLINE, START_TIME, END_TIME возвращают объекты \Bitrix\Main\Type\DateTime. Для вывода используйте метод toString(), для сравнения — методы getTimestamp().
Поле SETTINGS: Содержит сериализованный массив дополнительных параметров. Для расшифровки используйте unserialize($activity['SETTINGS'], ['allowed_classes' => false]).
Производительность: При получении большого количества активностей обязательно используйте параметры limit и offset. Также рекомендуется использовать select для выбора только необходимых полей.
Поиск по LIKE: Для поиска по тексту в полях SUBJECT, DESCRIPTION, SEARCH_CONTENT используйте оператор % в фильтре.
Связь с другими таблицами: Для получения дополнительной информации (ФИО пользователей, названия компаний) используйте runtime с ReferenceField.
Особенности звонков: Для звонков поле END_TIME - START_TIME дает длительность разговора. Поле SETTINGS может содержать ключ MISSED_CALL для пропущенных звонков.
Особенности задач: Для задач с PROVIDER_ID = 'CRM_TASKS_TASK' поле ASSOCIATED_ENTITY_ID содержит ID задачи из модуля задач.
Альтернативные методы: Для работы с активностями также доступен метод CCrmActivity::GetList(), но использование ORM предпочтительнее из-за лучшей типизации и поддержки.

Заключение

\Bitrix\Crm\ActivityTable::getList() — это основной ORM-инструмент для программного доступа к активностям CRM в коробочной версии Битрикс24. Он обеспечивает гибкую фильтрацию и сортировку, позволяя получать любые типы активностей: звонки, встречи, задачи, письма и напоминания. Понимание этого метода необходимо каждому разработчику, работающему с CRM-модулем Битрикс, особенно при реализации таймлайнов, отчетов по активности и интеграций с внешними системами. ORM-подход предоставляет более удобный и безопасный способ работы с данными по сравнению с устаревшими методами.

Начните сотрудничество с индивидуальной консультации по подбору инструментов и услуг.

Заказать услугу

Комментарии

Загрузка комментариев...

Назад к списку