Оглавление
event
PHP: Работа с активностями (делами) компаний в Битрикс24
Примеры PHP-кода для получения и создания активностей (дел) компаний в Битрикс24: получение списка дел, создание звонков и встреч, фильтрация по типам.
Описание
Активности (дела) в Битрикс24 — это запланированные или завершенные действия, связанные с элементами CRM: звонки, встречи, письма, задачи. Данный раздел содержит примеры PHP-кода для работы с активностями компаний. Вы можете использовать эти примеры для получения истории взаимодействий с клиентами, автоматического создания напоминаний и планирования действий в бизнес-процессах.
Активности позволяют отслеживать всю коммуникацию с компанией и планировать будущие взаимодействия, что критично для управления клиентскими отношениями.
Примеры использования
Пример 1: Получение активностей компании
Этот пример показывает, как получить список активностей (всех дел), связанных с компанией.
- Установлен лимит: не больше 500 активностей (лимит можно изменить в строке 28-31)
use Bitrix\Crm\ActivityTable;
use Bitrix\Main\Loader;
Loader::includeModule('crm');
// ВХОДНОЙ ПАРАМЕТР: ID компании
$companyId = "{{CompanyID}}";
// Валидация входных данных
if (empty($companyId)) {
$this->WriteToTrackingService("[ERROR] Не передан ID компании");
$rootActivity = $this->GetRootActivity();
$rootActivity->SetVariable("Status", "INPUT_ERROR");
$rootActivity->SetVariable("ErrorMessage", "Отсутствует обязательный параметр CompanyID");
return;
}
$companyId = (int)$companyId;
try {
if (!Loader::includeModule('crm')) {
$this->WriteToTrackingService("[ERROR] Модуль CRM не установлен");
$rootActivity = $this->GetRootActivity();
$rootActivity->SetVariable("Status", "MODULE_ERROR");
return;
}
// ПОЛУЧЕНИЕ ДАННЫХ: Выборка активностей компании
$activities = ActivityTable::getList([
'filter' => [
'=OWNER_TYPE_ID' => \CCrmOwnerType::Company,
'=OWNER_ID' => $companyId
],
'select' => ['ID'], // Выбираем только ID для оптимизации запроса
'order' => ['DEADLINE' => 'DESC'],
'limit' => 500,
'cache' => ['ttl' => 3600]
])->fetchAll();
if (empty($activities)) {
$rootActivity = $this->GetRootActivity();
$rootActivity->SetVariable("ActivityIDs", array());
$rootActivity->SetVariable("FoundCount", 0);
$rootActivity->SetVariable("Status", "NOT_FOUND");
return;
}
$activityIDs = array();
foreach ($activities as $activity) {
$activityIDs[] = $activity['ID'];
}
// Проверка лимита
if (count($activities) >= 500) {
$this->WriteToTrackingService("[WARNING] Достигнут лимит выборки 500 записей, возможны необработанные активности");
}
// ВЫХОДНЫЕ ПАРАМЕТРЫ: Массив ID активностей и статус
$rootActivity = $this->GetRootActivity();
$rootActivity->SetVariable("ActivityIDs", $activityIDs);
$rootActivity->SetVariable("FoundCount", count($activityIDs));
$rootActivity->SetVariable("Status", "SUCCESS");
} catch (\Exception $e) {
$this->WriteToTrackingService("[CRITICAL] Ошибка получения активностей: " . $e->getMessage());
$rootActivity = $this->GetRootActivity();
$rootActivity->SetVariable("Status", "DB_ERROR");
$rootActivity->SetVariable("ErrorMessage", $e->getMessage());
}
Входные параметры:
| Параметр | Тип | Описание | Обязательный |
|---|---|---|---|
| CompanyID | int/string | ID компании | Да |
Выходные переменные:
| Переменная | Тип | Описание |
|---|---|---|
| ActivityIDs | array | Массив ID активностей компании |
| FoundCount | int | Количество найденных активностей |
| Status | string | Статус выполнения: SUCCESS, NOT_FOUND, INPUT_ERROR, MODULE_ERROR, DB_ERROR |
| ErrorMessage | string | Описание ошибки (заполняется при ошибках) |
Возможные ошибки:
| Статус | Причина | Решение |
|---|---|---|
| INPUT_ERROR | Не передан CompanyID | Передать ID компании |
| MODULE_ERROR | Модуль CRM не установлен | Проверить установку модуля |
| NOT_FOUND | Активности не найдены | Проверить наличие дел у компании |
| DB_ERROR | Ошибка при работе с базой данных | Проверить логи системы |
Рекомендации по использованию:
- Всегда проверяйте переменную
Statusв следующих шагах БП - Используйте фильтр
COMPLETEDдля разделения завершённых и активных дел - Для получения конкретных типов активностей используйте фильтр
TYPE_ID - Типы активностей:
\CCrmActivityType::Call(звонок),\CCrmActivityType::Meeting(встреча),\CCrmActivityType::Email(письмо)
Пример 2: Получение незавершённых активностей (звонков) с фильтрацией по типу
Этот пример демонстрирует получение только незавершённых активностей определённого типа.
- Установлен лимит: не больше 500 активностей (лимит можно изменить в строке 35-38)
use Bitrix\Crm\ActivityTable;
use Bitrix\Main\Loader;
Loader::includeModule('crm');
// ВХОДНЫЕ ПАРАМЕТРЫ: ID компании и тип активности
$companyId = "{{CompanyID}}";
$activityTypeId = 2; // 1-Встреча, 2-Звонок, 4-Email
// Валидация входных данных
if (empty($companyId) || empty($activityTypeId)) {
$this->WriteToTrackingService("[ERROR] Не переданы обязательные параметры CompanyID или ActivityTypeID");
$rootActivity = $this->GetRootActivity();
$rootActivity->SetVariable("Status", "INPUT_ERROR");
$rootActivity->SetVariable("ErrorMessage", "Отсутствуют параметры для фильтрации");
return;
}
$companyId = (int)$companyId;
$activityTypeId = (int)$activityTypeId;
try {
if (!Loader::includeModule('crm')) {
$this->WriteToTrackingService("[ERROR] Модуль CRM не установлен");
$rootActivity = $this->GetRootActivity();
$rootActivity->SetVariable("Status", "MODULE_ERROR");
return;
}
// ФИЛЬТРАЦИЯ: Выборка незавершённых активностей по типу
$activities = ActivityTable::getList([
'filter' => [
'=OWNER_TYPE_ID' => \CCrmOwnerType::Company,
'=OWNER_ID' => $companyId,
'=TYPE_ID' => $activityTypeId,
'=COMPLETED' => 'N' // Только незавершённые активности
],
'select' => ['ID'], // Выбираем только ID для оптимизации запроса
'order' => ['DEADLINE' => 'DESC'],
'limit' => 500,
'cache' => ['ttl' => 3600]
])->fetchAll();
if (empty($activities)) {
$rootActivity = $this->GetRootActivity();
$rootActivity->SetVariable("ActivityIDs", array());
$rootActivity->SetVariable("FoundCount", 0);
$rootActivity->SetVariable("Status", "NOT_FOUND");
return;
}
$activityIDs = array();
foreach ($activities as $activity) {
$activityIDs[] = $activity['ID'];
}
if (count($activities) >= 500) {
$this->WriteToTrackingService("[WARNING] Достигнут лимит выборки, возможны необработанные записи");
}
// ВЫХОДНЫЕ ПАРАМЕТРЫ: Массив ID активностей и статус
$rootActivity = $this->GetRootActivity();
$rootActivity->SetVariable("ActivityIDs", $activityIDs);
$rootActivity->SetVariable("FoundCount", count($activityIDs));
$rootActivity->SetVariable("Status", "SUCCESS");
} catch (\Exception $e) {
$this->WriteToTrackingService("[CRITICAL] Ошибка фильтрации активностей: " . $e->getMessage());
$rootActivity = $this->GetRootActivity();
$rootActivity->SetVariable("Status", "DB_ERROR");
$rootActivity->SetVariable("ErrorMessage", $e->getMessage());
}
Входные параметры:
| Параметр | Тип | Описание | Обязательный |
|---|---|---|---|
| CompanyID | int/string | ID компании | Да |
| ActivityTypeID | int/string | ID типа активности (1-Встреча, 2-Звонок, 4-Email). Как узнать? | Да |
Выходные переменные:
| Переменная | Тип | Описание |
|---|---|---|
| ActivityIDs | array | Массив ID активностей указанного типа |
| FoundCount | int | Количество найденных активностей |
| Status | string | Статус выполнения операции |
| ErrorMessage | string | Описание ошибки |
Возможные ошибки:
| Статус | Причина | Решение |
|---|---|---|
| INPUT_ERROR | Не переданы обязательные параметры | Передать CompanyID и ActivityTypeID |
| MODULE_ERROR | Модуль CRM не установлен | Проверить установку модуля |
| NOT_FOUND | Незавершённые активности указанного типа не найдены | Проверить наличие активных дел |
| DB_ERROR | Ошибка при выполнении запроса к БД | Проверить логи системы |
Типы активностей в Битрикс24:
| ID | Константа | Описание |
|---|---|---|
| 1 | \CCrmActivityType::Meeting | Встреча |
| 2 | \CCrmActivityType::Call | Звонок |
| 4 | \CCrmActivityType::Email | |
| 6 | \CCrmActivityType::Task | Задача |
Рекомендации по использованию:
- Используйте константы
\CCrmActivityType::*для типобезопасности - Фильтр
'=COMPLETED' => 'N'возвращает только активные (незавершённые) дела - Для получения истории (завершённых дел) используйте
'=COMPLETED' => 'Y' - Комбинируйте фильтры для точного поиска (тип + статус + период)
- Этот пример идеален для получения актуальных задач по работе с компанией
Пример 3: Production-ready создание активности (исходящего звонка) для компании
Продвинутый пример создания новой активности с полной валидацией и обработкой ошибок.
use Bitrix\Crm\ActivityTable;
use Bitrix\Main\Type\DateTime;
use Bitrix\Main\Loader;
Loader::includeModule('crm');
// ВХОДНЫЕ ПАРАМЕТРЫ: Данные для создания активности
$companyId = "{{CompanyID}}";
$responsibleId = "{{ResponsibleUserID}}";
$subject = "{{Subject}}";
$description = "{{Description}}";
// Валидация входных данных
if (empty($companyId) || empty($responsibleId)) {
$this->WriteToTrackingService("[ERROR] Не переданы обязательные параметры CompanyID или ResponsibleUserID");
$rootActivity = $this->GetRootActivity();
$rootActivity->SetVariable("Status", "INPUT_ERROR");
$rootActivity->SetVariable("ErrorMessage", "Отсутствуют обязательные параметры");
return;
}
$companyId = (int)$companyId;
$responsibleId = (int)$responsibleId;
// Установка значений по умолчанию
if (empty($subject)) {
$subject = "Плановый звонок клиенту";
}
try {
if (!Loader::includeModule('crm')) {
$this->WriteToTrackingService("[ERROR] Модуль CRM не установлен");
$rootActivity = $this->GetRootActivity();
$rootActivity->SetVariable("Status", "MODULE_ERROR");
return;
}
// СЛОЖНАЯ ЛОГИКА: Подготовка данных для создания активности
$deadline = new DateTime();
$deadline->add("+1 day"); // Активность на завтра
$fields = array(
'OWNER_TYPE_ID' => \CCrmOwnerType::Company,
'OWNER_ID' => $companyId,
'TYPE_ID' => \CCrmActivityType::Call,
'SUBJECT' => $subject,
'DESCRIPTION' => $description,
'DEADLINE' => $deadline,
'COMPLETED' => 'N',
'PRIORITY' => \CCrmActivityPriority::Medium,
'RESPONSIBLE_ID' => $responsibleId,
'AUTHOR_ID' => $responsibleId,
'DIRECTION' => \Bitrix\Crm\ActivityDirection::Outgoing
);
// СОЗДАНИЕ: Добавление активности
$result = ActivityTable::add($fields);
if (!$result->isSuccess()) {
$errors = $result->getErrorMessages();
$this->WriteToTrackingService("[ERROR] Ошибка создания активности: " . implode(", ", $errors));
$rootActivity = $this->GetRootActivity();
$rootActivity->SetVariable("Status", "CREATE_ERROR");
$rootActivity->SetVariable("ErrorMessage", implode(", ", $errors));
return;
}
$newActivityId = $result->getId();
// ВЫХОДНЫЕ ПАРАМЕТРЫ: ID созданной активности и статус
$rootActivity = $this->GetRootActivity();
$rootActivity->SetVariable("NewActivityID", $newActivityId);
$rootActivity->SetVariable("Status", "SUCCESS");
$this->WriteToTrackingService("[SUCCESS] Активность создана. ID: " . $newActivityId);
} catch (\Exception $e) {
$this->WriteToTrackingService("[CRITICAL] Ошибка при создании активности: " . $e->getMessage());
$rootActivity = $this->GetRootActivity();
$rootActivity->SetVariable("Status", "DB_ERROR");
$rootActivity->SetVariable("ErrorMessage", $e->getMessage());
}
Входные параметры:
| Параметр | Тип | Описание | Обязательный |
|---|---|---|---|
| CompanyID | int/string | ID компании | Да |
| ResponsibleUserID | int/string | ID ответственного пользователя | Да |
| Subject | string | Тема активности | Нет |
| Description | string | Описание активности | Нет |
Выходные переменные:
| Переменная | Тип | Описание |
|---|---|---|
| NewActivityID | int | ID созданной активности |
| Status | string | Статус выполнения операции |
| ErrorMessage | string | Описание ошибки (если есть) |
Возможные ошибки:
| Статус | Причина | Решение |
|---|---|---|
| INPUT_ERROR | Не переданы обязательные параметры | Передать CompanyID и ResponsibleUserID |
| MODULE_ERROR | Модуль CRM не установлен | Проверить установку модуля |
| CREATE_ERROR | Ошибка при создании активности | Проверить корректность данных и права доступа |
| DB_ERROR | Ошибка при работе с базой данных | Проверить логи системы |
Рекомендации по использованию:
- Всегда указывайте
DEADLINEдля активности - это критично для планирования - Используйте
DIRECTIONдля указания направления (входящий/исходящий звонок) - Для создания встречи измените
TYPE_IDна\CCrmActivityType::Meeting - Проверяйте права пользователя на создание активностей
- Используйте
PRIORITYдля установки приоритета: High, Medium, Low
Фича примера кода №3:
Данный пример демонстрирует production-ready подход с:
- Полной валидацией всех обязательных параметров
- Установкой значений по умолчанию для опциональных полей
- Детальной обработкой ошибок на всех этапах
- Логированием успешного создания с ID активности
- Гибкой настройкой срока выполнения (deadline)
Этот код можно использовать как основу для автоматического создания напоминаний и планирования взаимодействий с клиентами.
Общие рекомендации по использованию
- Валидация: Всегда проверяйте обязательные параметры (CompanyID, ResponsibleUserID) перед операциями
- Статусы: Проверяйте переменную
Statusв следующих шагах БП для обработки различных сценариев - Типы активностей: Используйте константы
\CCrmActivityType::*для типобезопасности - Фильтрация: Комбинируйте фильтры (тип + статус + период) для точного поиска
- Производительность: Используйте кеширование для часто запрашиваемых данных
- Безопасность: Всегда приводите ID к типу int перед использованием
Связанные статьи
- Коды полей и идентификаторы - справочник кодов полей
- Получение компаний - выборка компаний
- Работа с комментариями компаний - добавление комментариев
- Работа с реквизитами компаний - управление реквизитами
Хотите следить за обновлениями?
