Разработка кастомных смарт-процессов Битрикс24

Разработка кастомных смарт-процессов Битрикс24

Смарт-процессы — это CRM-сущности, которые создаёте вы, а не разработчики Битрикс. Не лид и не сделка, а «Договор», «Заявка на закупку», «Рекламация», «Проект», «Арендатор» — под специфику вашего бизнеса. Технически это динамические CRM-сущности (\Bitrix\Crm\Service\Factory), хранящиеся в таблицах b_crm_dynamic_items_{entityTypeId}.

Что можно создать через конструктор Б24

В настройках CRM → «Смарт-процессы» менеджер создаёт новый тип: добавляет пользовательские поля, настраивает воронку стадий, включает нужные блоки (контакт, компания, товары, документы). Это работает для простых случаев.

Кастомная разработка нужна, когда:

• Поля смарт-процесса должны вычисляться автоматически.
• Создание элемента запускает цепочку действий (создать связанный элемент, уведомить, зарегистрировать в 1С).
• Нужна нестандартная карточка с кастомным UI.
• Требуется интеграция смарт-процесса с внешней системой.

Создание смарт-процесса через REST API

Создаём тип программно — удобно для деплоя между окружениями:

$result = $b24->callMethod('crm.type.add', [
    'fields' => [
        'title'                  => 'Рекламация',
        'isUseInUserfieldEnabled' => true,
        'isLinkWithProductsEnabled' => true,
        'isStagesEnabled'        => true,
        'isRobotsEnabled'        => true,
        'isBizProcEnabled'       => true,
    ],
]);
$entityTypeId = $result['result']['type']['entityTypeId']; // например, 1052

После получения entityTypeId добавляем пользовательские поля:

$b24->callMethod('crm.type.fields.add', [
    'entityTypeId' => $entityTypeId,
    'fields'       => [
        'fieldName'  => 'CLAIM_NUMBER',
        'userTypeId' => 'string',
        'listLabel'  => 'Номер рекламации',
        'isRequired' => true,
    ],
]);

Автоматическая нумерация элементов

Типовая задача: «Рекламация №РК-2024-0042». Реализуется через обработчик события onCrmDynamicItemBeforeAdd:

AddEventHandler('crm', 'onCrmDynamic' . $entityTypeId . 'ItemBeforeAdd', function(\Bitrix\Main\Event $event) {
    $item = $event->getParameter('item');
    $year = date('Y');

    // Атомарный счётчик в Redis или таблице
    $seq = incrementSequence("claim_{$year}");
    $item->set('UF_CRM_CLAIM_NUMBER', sprintf('РК-%d-%04d', $year, $seq));
});

Связанные сущности и каскадные действия

При создании рекламации автоматически:

1. Создаётся задача для отдела качества.
2. Прикрепляется связанная сделка (если рекламация по заказу).
3. Уведомляется ответственный менеджер.

AddEventHandler('crm', 'onCrmDynamic' . $entityTypeId . 'ItemAdd', function(\Bitrix\Main\Event $event) use ($b24) {
    $item    = $event->getParameter('item');
    $dealId  = $item->get('OPPORTUNITY'); // кастомное поле связанной сделки

    // Создаём задачу
    $b24->callMethod('tasks.task.add', [
        'fields' => [
            'TITLE'       => 'Обработать рекламацию ' . $item->get('UF_CRM_CLAIM_NUMBER'),
            'RESPONSIBLE_ID' => getQualityDeptHead(),
            'DEADLINE'    => date('Y-m-d\TH:i:s', strtotime('+2 business days')),
            'UF_CRM_TASK' => ["D_{$dealId}"],
        ],
    ]);

    // Уведомление через бота
    notifyManager($item->get('ASSIGNED_BY_ID'), "Новая рекламация: " . $item->get('UF_CRM_CLAIM_NUMBER'));
});

Кастомные роботы для смарт-процесса

Роботы — это действия, которые CRM выполняет автоматически при смене стадии. Стандартные роботы (отправить email, поставить задачу) — из коробки. Кастомный робот создаётся через REST:

$b24->callMethod('bizproc.robot.add', [
    'CODE'     => 'send_to_1c',
    'HANDLER'  => 'https://your-server.com/robot/send-to-1c',
    'AUTH_USER_ID' => 1,
    'NAME'     => ['ru' => 'Отправить в 1С'],
    'PROPERTIES' => [
        'document_type' => ['Name' => 'Тип документа', 'Type' => 'select', 'Options' => ['claim' => 'Рекламация', 'refund' => 'Возврат']],
    ],
    'RETURN_PROPERTIES' => [
        'external_id' => ['Name' => 'ID в 1С', 'Type' => 'string'],
    ],
]);

Когда CRM выполняет робота, Б24 POST'ит на HANDLER данные элемента. Обработчик выполняет логику (запрос к 1С), возвращает JSON с RETURN_PROPERTIES. Б24 записывает возвращённые данные в поля элемента.

Кастомная карточка через Placement

Стандартная карточка смарт-процесса не всегда удобна. Для сложного UI — встраиваем собственный интерфейс через placement.bind с типом CRM_DYNAMIC_DETAIL_TOOLBAR:

$b24->callMethod('placement.bind', [
    'PLACEMENT' => 'CRM_DYNAMIC_' . $entityTypeId . '_DETAIL_TOOLBAR',
    'HANDLER'   => 'https://your-server.com/app/claim-detail',
    'TITLE'     => 'Дополнительные данные',
]);

Открывается как боковая панель (слайдер) в карточке смарт-процесса — ваш SPA с кастомным интерфейсом.

Права доступа

Права на смарт-процесс настраиваются через CRM-роли (crm.type.userfield.access.set) или через приложение. Для сложной матрицы: читать — все менеджеры, редактировать — только ответственный и руководитель, удалять — только администратор. Проверяем через user.current и department.get при каждом запросе.

Интеграция с внешними системами

Сроки

Итого: 2–4 недели в зависимости от числа роботов и наличия кастомного UI.