Розробка кастомних роботів 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.ua" }
  }
}

Обробник повинен повернути відповідь протягом 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 тижні з урахуванням проєктування, розробки та тестування в реальній воронці.