Дела

Получить дела по основному владельцу

Такой вариант получает дела, у которых указанная CRM-сущность является основным владельцем. Например, если дело напрямую принадлежит сделке.

<?php

use Bitrix\Main\Loader;

const CRM_DEAL_TYPE_ID = 2;

Loader::includeModule('crm');

/**
 * Получает дела, у которых сущность является основным владельцем.
 */
function fetchActivitiesByOwner(int $owner_id, int $owner_type_id): array
{
    $activities = [];

    $activity_result = CCrmActivity::GetList(
        ['ID' => 'ASC'],
        [
            'OWNER_ID' => $owner_id,
            'OWNER_TYPE_ID' => $owner_type_id,
        ],
        false,
        false,
        ['*']
    );

    while ($activity = $activity_result->Fetch()) {
        $activities[] = $activity;
    }

    return $activities;
}

$activities = fetchActivitiesByOwner($deal_id, CRM_DEAL_TYPE_ID);

Но этот способ не всегда возвращает всё, что пользователь видит в карточке. Например, звонок может отображаться и в сделке, и в контакте, но в полях самого дела будет только один основной OWNER_ID.

Изменить дело

Например, можно отметить дело как завершённое. В примере каждая операция вынесена в отдельную функцию, чтобы код было проще читать и переиспользовать.

<?php

use Bitrix\Main\Loader;

Loader::includeModule('crm');

/**
 * Отмечает дело как завершённое.
 */
function completeActivity(int $activity_id): void
{
    CCrmActivity::Update(
        $activity_id,
        [
            'COMPLETED' => 'Y',
        ],
        false
    );
}

completeActivity($activity_id);

Удалить дело

Если удаление не прошло, ошибки можно получить через CCrmActivity::GetErrorMessages().

<?php

use Bitrix\Main\Loader;

Loader::includeModule('crm');

/**
 * Удаляет дело.
 */
function deleteActivity(int $activity_id): bool
{
    return CCrmActivity::Delete($activity_id);
}

/**
 * Получает ошибки удаления дела.
 */
function fetchActivityErrorMessages(): array
{
    return CCrmActivity::GetErrorMessages();
}

$is_deleted = deleteActivity($activity_id);

if ($is_deleted) {
    // Дело удалено
} else {
    $error_messages = fetchActivityErrorMessages();

    var_dump($error_messages);
}

Получить дела, которые видны в карточке

Если нужно получить именно те дела, которые отображаются в карточке, лучше искать через BINDINGS. Так можно учесть дополнительные привязки дела к CRM-сущностям.

<?php

use Bitrix\Main\Loader;

const CRM_DEAL_TYPE_ID = 2;

Loader::includeModule('crm');

/**
 * Получает дела, которые привязаны к карточке через bindings.
 */
function fetchActivitiesByBindings(int $owner_id, int $owner_type_id): array
{
    $activities = [];

    $activity_result = CCrmActivity::GetList(
        ['ID' => 'ASC'],
        [
            'BINDINGS' => [
                [
                    'OWNER_ID' => $owner_id,
                    'OWNER_TYPE_ID' => $owner_type_id,
                ],
            ],
        ],
        false,
        false,
        ['*']
    );

    while ($activity = $activity_result->Fetch()) {
        $activities[] = $activity;
    }

    return $activities;
}

$activities = fetchActivitiesByBindings($deal_id, CRM_DEAL_TYPE_ID);

Получить привязки дела

Привязки показывают, с какими CRM-сущностями связано дело. Именно они объясняют, почему одно и то же дело может быть видно в нескольких карточках.

<?php

use Bitrix\Main\Loader;

Loader::includeModule('crm');

/**
 * Получает список привязок дела.
 */
function fetchActivityBindings(int $activity_id): array
{
    return CCrmActivity::GetBindings($activity_id);
}

$activity_bindings = fetchActivityBindings($activity_id);

Добавить привязку к делу

Например, можно добавить привязку дела к сделке. После сохранения дело начнёт отображаться в дополнительной карточке.

<?php

use Bitrix\Main\Loader;

const CRM_DEAL_TYPE_ID = 2;

Loader::includeModule('crm');

/**
 * Получает список привязок дела.
 */
function fetchActivityBindings(int $activity_id): array
{
    return CCrmActivity::GetBindings($activity_id);
}

/**
 * Добавляет новую привязку к списку привязок дела.
 */
function addActivityBinding(array $activity_bindings, int $owner_id, int $owner_type_id): array
{
    $activity_bindings[] = [
        'OWNER_ID' => $owner_id,
        'OWNER_TYPE_ID' => $owner_type_id,
    ];

    return $activity_bindings;
}

/**
 * Сохраняет список привязок дела.
 */
function saveActivityBindings(int $activity_id, array $activity_bindings): void
{
    CCrmActivity::SaveBindings($activity_id, $activity_bindings, false, false, true);
}

$activity_bindings = fetchActivityBindings($activity_id);
$activity_bindings = addActivityBinding($activity_bindings, $deal_id, CRM_DEAL_TYPE_ID);

saveActivityBindings($activity_id, $activity_bindings);

Коротко про OWNER_ID и BINDINGS

• OWNER_ID — основной владелец дела.
• OWNER_TYPE_ID — тип CRM-сущности владельца.
• BINDINGS — дополнительные привязки, через которые дело видно в других карточках.
• Если нужно получить только “родные” дела сущности — можно фильтровать по OWNER_ID.
• Если нужно получить то, что видно в карточке, — лучше смотреть в сторону BINDINGS.

Список событий CRM activity

Для дел CRM есть отдельные события, которые можно использовать при добавлении, изменении и удалении дела.

На практике чаще всего нужны два сценария: отреагировать на изменение дела или остановить удаление дела при определённых условиях.

Обработчик после добавления дела

Такой обработчик можно использовать, если нужно выполнить свою логику после создания дела.

<?php

use Bitrix\Main\EventManager;

$event_manager = EventManager::getInstance();

/**
 * Регистрирует обработчик после добавления дела.
 */
function registerActivityAddHandler(EventManager $event_manager): void
{
    $event_manager->addEventHandlerCompatible(
        'crm',
        'OnActivityAdd',
        'handleActivityAdd'
    );
}

/**
 * Обрабатывает добавление дела.
 */
function handleActivityAdd(int $activity_id, array $activity_fields): void
{
    // Здесь можно добавить свою логику после создания дела
}

registerActivityAddHandler($event_manager);

Обработчик после изменения дела

Этот вариант подходит, если нужно реагировать на изменение полей дела: завершение, смену ответственного, изменение связей или других данных.

<?php

use Bitrix\Main\EventManager;

$event_manager = EventManager::getInstance();

/**
 * Регистрирует обработчик после изменения дела.
 */
function registerActivityUpdateHandler(EventManager $event_manager): void
{
    $event_manager->addEventHandlerCompatible(
        'crm',
        'OnActivityUpdate',
        'handleActivityUpdate'
    );
}

/**
 * Обрабатывает изменение дела.
 */
function handleActivityUpdate(int $activity_id, array $activity_fields): void
{
    // Здесь можно добавить свою логику после изменения дела
}

registerActivityUpdateHandler($event_manager);

Обработчик перед удалением дела

Событие OnBeforeActivityDelete удобно использовать, если удаление нужно проверить или запретить.

<?php

use Bitrix\Main\EventManager;

$event_manager = EventManager::getInstance();

/**
 * Регистрирует обработчик перед удалением дела.
 */
function registerBeforeActivityDeleteHandler(EventManager $event_manager): void
{
    $event_manager->addEventHandlerCompatible(
        'crm',
        'OnBeforeActivityDelete',
        'handleBeforeActivityDelete'
    );
}

/**
 * Проверяет возможность удаления дела.
 */
function handleBeforeActivityDelete(int $activity_id): bool
{
    $has_delete_access = false;

    if (!$has_delete_access) {
        return false;
    }

    return true;
}

registerBeforeActivityDeleteHandler($event_manager);

Обработчик после удаления дела

Событие OnActivityDelete можно использовать для логирования или очистки своих связанных данных после успешного удаления дела.

<?php

use Bitrix\Main\EventManager;

$event_manager = EventManager::getInstance();

/**
 * Регистрирует обработчик после удаления дела.
 */
function registerActivityDeleteHandler(EventManager $event_manager): void
{
    $event_manager->addEventHandlerCompatible(
        'crm',
        'OnActivityDelete',
        'handleActivityDelete'
    );
}

/**
 * Обрабатывает удаление дела.
 */
function handleActivityDelete(int $activity_id): void
{
    // Здесь можно добавить логирование или очистку связанных данных
}

registerActivityDeleteHandler($event_manager);

• Официальная документация: CCRMActivity
• Официальная документация: события CRM
• Bitrix24: Книга разработчика — Дело / Общее API