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

Розробка кастомних смарт-процесів Bitrix24

Смарт-процеси — це 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.