Как встроить приложение в карточку CRM Битрикс24
Приложение можно открыть прямо в карточке сделки: добавить вкладку с данными или действие в меню карточки. Для общего справочника и настроек удобнее отдельный пункт приложения. Место показа выбирают до разработки экрана, поскольку от него зависит контекст, который получит приложение.
Менеджеру нужно видеть в сделке результат проверки поставки. Если вынести его в отдельный отчёт, придётся снова искать заказ. Вкладка позволяет показать связанный экран рядом с данными сделки: приложение получает ID текущей карточки и загружает нужную информацию. Связь со складом для такого сценария разрабатывают отдельно.
Выберите место по задаче сотрудника
Вкладка CRM_DEAL_DETAIL_TAB подходит, когда экран нужен во время работы с одной сделкой. Пункт CRM_DEAL_DETAIL_TOOLBAR добавляет действие в меню верхней кнопки карточки сделки. Для общего раздела с настройками, справочником или отчётом есть LEFT_MENU. Это разные точки встраивания: пункт в левом меню не превращает экран в вкладку сделки.
Если требуется лишь узнать код поля или просмотреть данные CRM, сначала проверьте, достаточно ли штатного экрана или обычного запроса к API Битрикс24. Встраивание имеет смысл, когда сотрудник должен выполнять действие в привычном месте и без повторного поиска карточки.
Как приложение добавляет вкладку сделки
Разработчик готовит страницу обработчика, доступную Битрикс24 по публичному HTTPS-адресу и разрешённую для открытия во фрейме. Для регистрации вкладки CRM приложению нужны права placement и crm; право crm также понадобится для чтения сделки. placement.bind вызывает администратор или сотрудник с разрешением создавать приложения для всех в рамках локального приложения. Вызов идёт из контекста приложения: входящий вебхук вернёт WRONG_AUTH_TYPE.
| Параметр | Что указать | Результат |
|---|---|---|
| PLACEMENT | CRM_DEAL_DETAIL_TAB | Вкладка в карточке сделки |
| HANDLER | Публичный HTTPS-адрес страницы приложения | Битрикс24 откроет эту страницу во фрейме |
| TITLE | Короткое понятное название вкладки | Сотрудник увидит его в ряду вкладок или под «Ещё» |
Официальный пример регистрирует вкладку при установке приложения и завершает установку после настройки. Успешный ответ placement.bind сам по себе ещё не означает, что вкладка уже видна сотрудникам. Сначала подтвердите завершение установки и доступ пользователя к приложению.
Что происходит при открытии вкладки
Битрикс24 отправляет обработчику POST-запрос и открывает полученную страницу во фрейме. Сначала обработчик сверяет APPLICATION_TOKEN с сохранённым при установке значением для этого портала; токен нельзя записывать в общий журнал. Для вкладки сделки в PLACEMENT_OPTIONS приходит JSON-строка с ID текущей сделки. После проверки запроса обработчик разбирает её и проверяет ID, затем приложение может вызвать crm.item.get с entityTypeId=2. Одного ID недостаточно, чтобы обойти права CRM: метод возвращает данные в рамках доступа пользователя.
Приложение TrueTell «Поля CRM — поиск кодов и экспорт» служит реальным примером. В его коде предусмотрены вкладки сделок, лидов, контактов и компаний: при открытии выбирается соответствующий тип полей. Снимок ниже показывает рабочий экран приложения с поиском технического кода поля. Он не показывает всю карточку Битрикс24 и не подтверждает работу вкладки на каждом клиентском портале.
Страница виджета должна разрешать показ во фрейме Битрикс24. Если сервер отдаёт запрещающие X-Frame-Options или Content-Security-Policy, сотрудник увидит пустую область даже при верной регистрации.
Как проверить вкладку на тестовом портале
Сначала проверьте через placement.get, что приложение зарегистрировало нужный код точки и правильный адрес обработчика. Убедитесь, что установка завершена. Затем войдите под сотрудником, которому доступно приложение и разрешено читать контрольную сделку, откройте карточку и найдите вкладку. Если её не видно в ряду, загляните под «Ещё».
Откройте две разные контрольные сделки и убедитесь, что виджет показывает данные именно той карточки, из которой запущен. Повторите проверку под пользователем с более узкими правами. Если он видит вкладку, но не данные, разделите проблему доступа к приложению и отказ REST в чтении сделки. Токены авторизации и данные клиентов в диагностические снимки и общий журнал не переносите.
Частые вопросы о встраивании приложения в CRM
Можно ли добавить вкладку сделки одним входящим вебхуком?
Нет. placement.bind работает в контексте приложения; вызов через входящий вебхук возвращает WRONG_AUTH_TYPE. Сначала нужно приложение с правами на размещение виджета.
Какая точка встраивания нужна для вкладки сделки?
Для вкладки карточки сделки используйте CRM_DEAL_DETAIL_TAB. При регистрации приложение передаёт этот код как PLACEMENT, адрес своей страницы как HANDLER и название вкладки как TITLE.
Получит ли вкладка все поля сделки автоматически?
Нет. При открытии Битрикс24 передаёт контекст, в том числе ID сделки в PLACEMENT_OPTIONS. Если приложению нужны поля, оно отдельно вызывает crm.item.get с entityTypeId=2 и правами пользователя, открывшего вкладку.
Почему вкладка зарегистрирована, но её не видно?
Проверьте, завершена ли установка приложения и открыт ли к нему доступ сотруднику. Затем ищите вкладку под «Ещё», если ряд вкладок переполнен. Регистрацию и адрес обработчика проверьте методом placement.get.
Чем вкладка отличается от пункта в левом меню?
Вкладка открывается внутри конкретной карточки и получает её ID. LEFT_MENU открывает общий экран приложения в главном меню; его выбирают для справочника, панели или отчёта, который не начинается с одной сделки.
Что делать, если вместо приложения пустая область?
Проверьте доступность HTTPS-адреса обработчика, его ответ на POST и заголовки X-Frame-Options и Content-Security-Policy. Если они запрещают показ страницы во фрейме Битрикс24, виджет не появится, даже когда регистрация успешна.
Документация Битрикс24 проверена 1 ноября 2026 года. Порядок регистрации и набор точек сверены с официальными материалами; новую вкладку в клиентском портале для этой статьи не устанавливали. Возможности примера TrueTell проверены по коду приложения и существующему снимку тестового портала.