Разработка кастомных роботов CRM Битрикс24

Разработка кастомных роботов CRM Битрикс24

Стандартных роботов не хватает: нужно при переходе сделки на стадию «Победа» автоматически создать проект в Jira, отправить данные клиента в ERP и выставить счёт через 1С. Ни один из этих сценариев не покрывается встроенными действиями. Пишем кастомный робот.

Архитектура кастомных роботов

Роботы в Битрикс24 — это надстройка над движком бизнес-процессов (bizproc). Кастомный робот регистрируется как действие бизнес-процесса (CBPActivity) с особым флагом FILTER, который ограничивает его область применения (CRM, конкретные типы сущностей).

Два способа создать кастомный робот:

1. Через REST API — метод bizproc.robot.add. Регистрирует внешний вебхук как робота. Битрикс24 вызывает URL при срабатывании, передаёт данные сущности, получает ответ. Подходит для облачного Битрикс24, не требует доступа к файловой системе.

2. Через PHP-модуль — создаётся класс, наследующий \Bitrix\Bizproc\Activity\BaseActivity. Регистрируется в RegisterModuleDependences на событие OnBizProcActivityList. Доступен только на коробочном Битрикс24 с доступом к серверу.

Разработка через REST API (облако и коробка)

Это предпочтительный способ для облачных порталов. Схема работы:

Переход сделки на стадию
  → Битрикс24 вызывает вебхук робота (POST)
  → Внешний сервер обрабатывает данные
  → Сервер возвращает результат в Битрикс24 через callback
  → Битрикс24 продолжает выполнение воркфлоу

Регистрация робота через REST:

$client->call('bizproc.robot.add', [
    'CODE'         => 'MY_CUSTOM_ROBOT',
    'HANDLER'      => 'https://my-server.com/bitrix-robot-handler',
    'AUTH_USER_ID' => 1,
    'NAME'         => 'Создать проект в Jira',
    'PROPERTIES'   => [
        'project_key' => [
            'Name'     => 'Ключ проекта Jira',
            'Type'     => 'string',
            'Required' => 'Y',
        ],
    ],
    'RETURN_PROPERTIES' => [
        'issue_id' => [
            'Name' => 'ID задачи в Jira',
            'Type' => 'string',
        ],
    ],
    'DOCUMENT_TYPE' => ['crm', 'CCrmDocumentDeal', 'DEAL'],
]);

Параметр DOCUMENT_TYPE определяет, для каких сущностей доступен робот. Для смарт-процессов тип выглядит как ['crm', 'Bitrix\Crm\Integration\BizProc\Document\Dynamic', 'DYNAMIC_{TYPE_ID}'].

Обработчик вебхука

Битрикс24 отправляет на URL обработчика POST-запрос с полями:

{
  "event": "onBpActivityExecute",
  "data": {
    "WORKFLOW_ID": "...",
    "DOCUMENT_ID": ["crm", "CCrmDocumentDeal", "DEAL_123"],
    "PROPERTIES": {
      "project_key": "SALES"
    },
    "auth": { "access_token": "...", "domain": "portal.bitrix24.ru" }
  }
}

Обработчик должен вернуть ответ в течение 5 секунд — иначе Битрикс24 считает вызов зависшим. Для долгих операций используется асинхронный режим: обработчик сразу возвращает {"status": "async"}, выполняет работу в фоне, затем сообщает результат через bizproc.event.send.

Разработка через PHP-модуль (коробочный Битрикс24)

Для коробки создаётся локальный модуль или компонент с регистрацией активности:

// local/php_interface/init.php
AddEventHandler('bizproc', 'OnBizProcActivityList', function(&$arActivities) {
    $arActivities['MyCustomRobot'] = [
        'NAME'        => 'Создать проект в Jira',
        'DESCRIPTION' => 'Создаёт проект в Jira по данным сделки',
        'TYPE'        => ['activity', 'robot_activity'],
        'CLASS'       => 'MyJiraRobot',
        'JSCLASS'     => 'BizProcActivity',
        'CATEGORY'    => ['ID' => 'integration'],
        'ROBOT_SETTINGS' => [
            'CATEGORY' => 'employee',
            'RETURN'   => ['ISSUE_ID' => ['Name' => 'ID задачи', 'Type' => 'string']],
        ],
        'FILTER'      => ['INCLUDE' => [['crm', 'CCrmDocumentDeal', 'DEAL']]],
    ];
});

Класс MyJiraRobot наследует \Bitrix\Bizproc\Activity\BaseActivity и реализует метод execute(), который вызывается при срабатывании робота.

Реальный кейс: робот синхронизации с ERP

Задача: производственная компания, 150 сделок в месяц. При переходе сделки в стадию «Заказ подтверждён» нужно:

1. Создать заказ в ERP (SOAP API)
2. Записать номер заказа ERP обратно в поле сделки UF_CRM_ERP_ORDER_ID
3. Уведомить ответственного в Битрикс24 о результате

Решение: REST-робот на отдельном PHP-сервере. Обработчик принимает данные сделки, вызывает SOAP API ERP в асинхронном режиме (задача в очереди Redis), при получении ответа от ERP обновляет поле сделки через crm.deal.update и отправляет уведомление через im.notify.system.add.

Проблема в процессе: ERP иногда отвечает за 30–40 секунд. Синхронный режим не работал — Битрикс24 помечал вызов как зависший. Переход на асинхронный режим с bizproc.event.send решил проблему. Добавили retry-логику на случай недоступности ERP с повтором через 5 минут.

Результат: ручной ввод заказов в ERP исчез полностью. Время от подтверждения сделки до появления заказа в ERP — 1–3 минуты.

Сроки разработки

Итоговые сроки разработки кастомного робота — 1–2 недели с учётом проектирования, разработки и тестирования в реальной воронке.