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

Розробка користувацьких типів CRM-сутностей у Bitrix24

У CRM Bitrix24 є фіксований набір сутностей: ліди, угоди, контакти, компанії. Коли бізнес-процес не вписується ні в одну з них — наприклад, облік об'єктів нерухомості, запити на ремонт, рекламації — ви починаєте підганяти угоди під чужу задачу. Поля названі не тим, що вони означають, стадії воронки описують не продаж, а щось інше. Смарт-процеси вирішують цю проблему, але їхня настройка за замовчуванням охоплює 60% випадків. Решта 40% потребує розробки.

Смарт-процеси: що під капотом

Смарт-процес (Smart Process Automation, SPA) — це користувацький тип CRM-сутності. Створюється через CRM → Параметри → Автоматизація → Смарт-процеси. Кожен смарт-процес отримує числовий entityTypeId (починаючи з 128) і зберігає елементи в таблиці b_crm_dynamic_items_{entityTypeId}.

Програмно смарт-процес описується класом \Bitrix\Crm\Service\Factory\Dynamic. Фабрика керує життєвим циклом елементів: створення, оновлення, видалення, переміщення по стадіях. Для отримання фабрики:

$factory = \Bitrix\Crm\Service\Container::getInstance()
    ->getFactory($entityTypeId);

Що доступно з коробки:

• Користувацькі поля (UF-поля) будь-яких типів — рядок, число, дата, прив'язка до CRM-елемента, файл
• Воронка зі стадіями та семантикою (в роботі / успіх / невдача)
• Роботи та бізнес-процеси на кожній стадії
• Карточка елемента з налаштовуваними розділами
• Канбан та список з фільтрацією
• Шкала часу та історія змін
• Права доступу через ролі CRM

Коли стандартного смарт-процесу недостатньо

Три сценарії, при яких потрібна розробка:

1. Зв'язки між сутностями. Стандартний смарт-процес підтримує прив'язку до угоди, контакту, компанії. Але якщо потрібен зв'язок «багато-до-багатьох» між двома смарт-процесами (наприклад, «Об'єкт» та «Дефект» — у одного об'єкта багато дефектів, один дефект може відноситися до кількох об'єктів), доведеться створювати проміжну сутність або реалізувати зв'язок через REST-обробники та користувацькі поля типу crm_multifield.

2. Обчислювані поля. UF-поля не підтримують формули. Якщо поле «Рентабельність» = (Виручка - Собівартість) / Виручка * 100, його значення потрібно перераховувати обробником на подію onAfterUpdate. Реєстрація обробника:

$eventManager = \Bitrix\Main\EventManager::getInstance();
$eventManager->registerEventHandler(
    'crm',
    'onAfterCrmDynamicItemUpdate_128',
    'local',
    '\\Local\\Handler',
    'recalculateMargin'
);

3. Користувацька валідація. Стандартна перевірка — обов'язковість поля. Якщо потрібна бізнес-валідація (наприклад, дата завершення не раніше дати початку, сума позицій дорівнює загальній сумі), вона реалізується через обробник onBeforeCrmDynamicItemUpdate, який може скасувати збереження та повернути помилку.

Проектування полів та стадій

Перед створенням смарт-процесу складіть карту полів. Розрізняйте:

• Основні поля — відображаються в карточці та списку, беруть участь у фільтрації. Оптимально 10–15 полів.
• Служебні поля — використовуються роботами та обробниками, приховані з інтерфейсу через налаштування карточки.
• Архівні поля — дані для історії, не індексуються.

Стадії воронки проектуються за принципом необоротності: елемент рухається зліва направо, повернення на попередню стадію — винятки, а не норма. Кожна стадія має означати конкретну дію: «На узгодженні у юриста», а не «В процесі».

Семантика стадій критична: поля STAGE_SEMANTIC_ID приймають значення P (процес), S (успіх), F (невдача). Аналітика CRM будується на цій семантиці — воронка конверсій, середній цикл, прогноз. Без семантики звіти будуть порожніми.

Інтеграція через REST API

Для зовнішніх систем смарт-процеси доступні через REST:

• crm.type.list — список всіх типів сутностей
• crm.item.add?entityTypeId=128 — створення елемента
• crm.item.list?entityTypeId=128&filter[STAGE_ID]=DT128_1:NEW — фільтрація по стадії
• crm.item.update — оновлення з автоматичним запуском роботів

Формат STAGE_ID для смарт-процесів: DT{entityTypeId}_{categoryId}:{STATUS_CODE}. Це не очевидно та часто викликає помилки при інтеграції — стадії угод та смарт-процесів форматуються по-різному.

Міграція даних з «костильних» угод

Якщо ваш бізнес уже використовує угоди не за призначенням, міграція на смарт-процес включає:

1. Створення смарт-процесу з аналогічними полями
2. Відображення стадій старої воронки на стадії нового типу
3. Пакетний перенос даних через crm.item.add у циклі (ліміт REST — 50 запитів/сек, batch до 50 команд)
4. Переналаштування роботів та бізнес-процесів
5. Переключення інтеграцій на новий entityTypeId

Що часто упускають

Смарт-процеси не підтримують товарні позиції з коробки в хмарній версії — тільки в коробочній через доробку. Якщо елементу потрібна таблична частина (позиції замовлення, перелік робіт), реалізуйте її через пов'язані елементи іншого смарт-процесу або через користувацьке поле типу JSON (зберігання в UF_CRM_* рядкового типу з серіалізацією).