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

Розробка користувацьких карточок CRM у Bitrix24

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

Два рівні налаштування

Bitrix24 пропонує два способи змінити карточку 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: 'Калькулятор маржі'
});

Після реєстрації в карточці з'явиться нова вкладка. При відкритті Bitrix24 завантажить 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.