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

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

В CRM Битрикс24 есть фиксированный набор сущностей: лиды, сделки, контакты, компании. Когда бизнес-процесс не ложится ни на одну из них — например, учёт объектов недвижимости, заявок на ремонт, рекламаций — начинается подгонка сделок под чужую задачу. Поля называются не тем, что они значат, стадии воронки описывают не продажу, а что-то другое. Смарт-процессы решают эту проблему, но их настройка по умолчанию покрывает 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 (process), S (success), F (failure). Аналитика 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_* строкового типа с сериализацией).