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

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

Стандартная карточка сделки в Битрикс24 — универсальный интерфейс под все отрасли сразу. В результате менеджер по продажам оборудования видит те же поля, что и менеджер по аренде. Поля не сгруппированы по смыслу, вычисляемых значений нет, условная логика отображения отсутствует. Кастомная карточка решает конкретную задачу: показать менеджеру ровно то, что нужно на текущей стадии работы.

Два уровня кастомизации

Битрикс24 предлагает два способа изменить карточку CRM-сущности, и они принципиально разные по глубине.

Уровень 1: настройка через интерфейс. В карточке сделки (контакта, смарт-процесса) нажмите «Настроить карточку» → «Настроить поля и разделы». Здесь можно:

• Переименовать разделы
• Перетащить поля между секциями
• Скрыть ненужные поля
• Задать обязательность полей по стадиям (для сделок)

Это бесплатно и покрывает ~40% запросов. Но нельзя: добавить вычисляемые поля, условную логику, кастомные виджеты, данные из внешних систем.

Уровень 2: разработка через REST Placement API. Это встраивание произвольного HTML/JS-контента в определённые зоны карточки. Именно здесь начинается настоящая кастомизация.

Placement API: точки встраивания

Карточка CRM-сущности содержит несколько зон (placement), в которые можно встроить кастомный контент:

• CRM_DEAL_DETAIL_TAB — вкладка в карточке сделки. Полноценная область для любого UI.
• CRM_DEAL_DETAIL_ACTIVITY — блок в таймлайне. Подходит для вывода кастомных действий.
• CRM_CONTACT_DETAIL_TAB, CRM_COMPANY_DETAIL_TAB — аналогично для контактов и компаний.
• CRM_DYNAMIC_ITEM_DETAIL_TAB — вкладка в карточке смарт-процесса.

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

BX24.callMethod('placement.bind', {
    PLACEMENT: 'CRM_DEAL_DETAIL_TAB',
    HANDLER: 'https://your-app.com/deal-tab.html',
    TITLE: 'Калькулятор маржи'
});

После регистрации в карточке появится новая вкладка. При открытии Битрикс24 загрузит HANDLER в iframe и передаст контекст: ENTITY_ID (ID сделки), AUTH_ID, REFRESH_ID.

Глубокое погружение: кастомная вкладка с данными

Рассмотрим типичный кейс — вкладка «Финансы» в карточке сделки, которая показывает: сумму по товарным позициям, себестоимость из внешней 1С, маржу, историю оплат.

Шаг 1: получение данных сделки

BX24.init(function() {
    var dealId = BX24.placement.info().options.ID;

    BX24.callBatch({
        deal: ['crm.deal.get', {id: dealId}],
        products: ['crm.deal.productrows.get', {id: dealId}]
    }, function(result) {
        var deal = result.deal.data();
        var products = result.products.data();
        renderFinanceTab(deal, products);
    });
});

Шаг 2: запрос себестоимости из внешнего API. Вкладка делает запрос к вашему бэкенду, передавая артикулы товарных позиций. Бэкенд проксирует запрос к 1С или ERP и возвращает себестоимость.

Шаг 3: рендеринг. Рассчитываете маржу на клиенте и выводите таблицу. Для визуального соответствия используйте CSS-переменные Б24 или библиотеку @bitrix24/b24-ui.

Условная логика отображения полей

Частый запрос: скрывать/показывать поля в зависимости от значения другого поля. Например, поле «Причина отказа» видно только на стадии «Провалена». Стандартный функционал позволяет сделать поле обязательным по стадии, но не скрыть его.

Решение — кастомный обработчик через placement CRM_DEAL_DETAIL_TAB или встраивание JS-кода через пользовательский тип поля. В коробочной версии доступна модификация шаблона компонента bitrix:crm.deal.detail с добавлением JS-логики в script.js.

Для облачной версии единственный чистый способ — placement с полной перерисовкой нужной секции полей. Это означает: вы забираете данные через REST, рендерите поля с условной логикой в своём iframe, а при сохранении отправляете изменения обратно через crm.deal.update.

Виджеты в таймлайне

Placement CRM_*_DETAIL_ACTIVITY встраивает блок прямо в ленту активностей карточки. Подходит для:

• Вывода статуса доставки (данные из API транспортной компании)
• Показа баланса клиента из бухгалтерской системы
• Отображения последних тикетов из helpdesk

Виджет обновляется при каждом открытии карточки. Для кэширования используйте BX24.appOption — хранилище приложения на стороне Б24.

Производительность

Iframe-вкладки загружаются при активации (клик по табу). Для тяжёлых вкладок это нормально — пользователь не ждёт загрузки того, что не открывал. Но если вы встраиваете виджет в основную область карточки — он грузится сразу. Каждый REST-запрос из iframe — это сетевой round-trip. Используйте BX24.callBatch для объединения запросов: один batch вместо пяти последовательных вызовов.

Ограничения облачной версии

В облаке нельзя модифицировать стандартные секции карточки — только добавлять новые вкладки и виджеты. Нельзя убрать стандартные поля из основного вида (только скрыть через настройку карточки). Для полного контроля над интерфейсом карточки — коробочная версия с переопределением шаблона компонента crm.deal.detail.