Интеграция с Битрикс24
Обновлено
Входящий вебхук
Плагин обращается к REST API портала через входящий вебхук. «Входящий» — название со стороны Битрикс24: данные идут с сайта на портал. Обратного обмена статусами нет.
В настройках плагина указан путь создания вебхука в Битрикс24: «Разработчикам» → «Другое» → «Входящий вебхук». Требуются права «CRM» и «Пользователи». Владелец вебхука должен иметь доступ к действиям, которые выполняет плагин.
В поле «Адрес вебхука Битрикс24» нужен полный адрес вида:
https://portal.bitrix24.ru/rest/1/WEBHOOK_TOKEN/Пример показывает формат: замените домен, номер пользователя и токен данными своего вебхука. Не дописывайте имя метода, .json или параметры запроса. Адрес содержит секретный токен. Используйте HTTPS; при проверке HTTP-адреса плагин предупреждает о передаче токена открытым текстом.
Один вебхук используется всеми формами установки. Настройки не предусматривают отдельного портала для каждой формы.
Что проверяет «Проверить подключение»
Кнопка находится на общей странице плагина. Она вызывает profile и crm.lead.fields, показывает портал и пользователя, от имени которого работает вебхук. Проверка не создаёт лид, сделку или контакт и не сохраняет введённый адрес.
Успешная проверка не заменяет пробную отправку: она не проверяет создание сделки, доступ ко всем справочникам и заполнение обязательных полей CRM. Для проверки выбранного сценария отправьте тестовую заявку.
Какие данные уходят
| Данные заявки | Куда передаются |
|---|---|
| Название по шаблону | Название лида или сделки (TITLE) |
| Название формы и номер заявки | Описание источника (SOURCE_DESCRIPTION) |
| Заполненные поля | Комментарий (COMMENTS) строками «Поле: значение»; HTML-блоки, шаги и CAPTCHA пропускаются |
| Файлы | Имена файлов и ссылки на файлы сайта в комментарии; сами файлы в CRM не загружаются |
| Имя, телефон, email | Поля лида; при создании нового контакта — поля контакта; найденный контакт прикрепляется к записи |
| Компания | Название компании в лиде (COMPANY_TITLE); отдельная компания CRM не создаётся |
| Выбранный источник и ответственный | Поля лида или сделки и создаваемого контакта |
| Поле с суммой и выбранная валюта | Сумма и валюта лида или сделки (OPPORTUNITY, CURRENCY_ID) |
| UTM-поля | Штатные UTM-поля CRM, если названия полей формы совпадают с utm_source, utm_medium, utm_campaign, utm_content, utm_term без учёта регистра |
| Номер и дата создания заявки | Заключительная строка комментария |
| Идентификатор установки и заявки | Внешние идентификаторы записи для поиска после неудачной попытки |
Произвольного сопоставления полей формы с пользовательскими полями CRM в настройках нет. Значения полей остаются в комментарии, а перечисленные специальные данные дополнительно попадают в соответствующие поля CRM.
Данные человека извлекаются из ролей полей формы средствами приложения «Заявки». Если имени, телефона или email в форме нет, плагин дополняет их из связанного контакта Webasyst, когда он доступен. Данные формы имеют приоритет.
Корзина магазина
При включённой настройке «Передавать товары корзины в комментарии» плагин получает дополнительный текст через событие request_extra_text приложения «Заявки». Плагин «Заказы из заявок» может передать через него список товаров с ценами и сумму корзины.
Корзина дописывается текстом в комментарий. Она не превращается в товарные строки сделки и не задаёт автоматически её сумму: для суммы служит настройка «Поле с суммой».
Как выбирается контакт
- Если у контакта Webasyst уже есть сохранённая связь с контактом портала, плагин проверяет существование этого контакта и использует связь.
- Если связи нет или контакт на портале удалён, выполняется поиск контактов по телефону и email через
crm.duplicate.findbycomm. - Сначала выбирается контакт, совпавший по обоим признакам. При нескольких подходящих контактах выбирается контакт с меньшим ID; в карточке заявки появляется предупреждение о похожих контактах.
- Если телефон и email найдены у разных контактов без общего совпадения, контакт не прикрепляется. Менеджер выбирает его на портале; новый контакт при таком конфликте не создаётся.
- Если совпадений нет, для сделки разрешено создание контакта настройкой «Создавать контакт для сделки, если на портале его нет». Для создания нужно хотя бы имя, телефон или email.
Лид не создаёт новый контакт: данные человека записываются в сам лид, найденный контакт прикрепляется. Существующие контакты не обновляются и не объединяются плагином.
При поиске телефона учитываются варианты записи с цифрами, знаком +, российскими префиксами 8 и +7. По слишком коротким номерам и распознаваемым заглушкам, например +7 (000) 000-00-00, поиск не выполняется. Это не запрещает передать введённый телефон в поля создаваемой записи.
Ошибки и повторение
После ошибки заявка остаётся в приложении «Заявки». В её блоке «Битрикс24» появляется «Не отправлено: …» и кнопка «Повторить», если адрес вебхука задан в допустимом формате.
Повторная попытка сначала ищет запись, которую портал мог создать, но ответ о которой не дошёл до сайта. Для разработчика: поиск использует ORIGINATOR_ID = webasyst.requests и ORIGIN_ID, сформированный из идентификатора установки и номера заявки. Найденная запись отмечается отправленной вместо создания новой.
После успешной отправки новые срабатывания ничего не создают и не обновляют. Если запись удалить непосредственно в CRM, локальная отметка об успехе остаётся и повторного создания не будет.
Автоматической очереди с повтором по расписанию нет. После ошибки можно нажать «Повторить» или дождаться следующего настроенного перехода статуса. Незавершённая отправка блокирует новую попытку; спустя 120 секунд её можно перехватить повторной отправкой.
Журнал плагина для разработчика: wa-log/requests/plugins/b24crm.log. Сетевые ошибки, ответы REST с ошибками и внутренние исключения записываются туда.
Доступы и ограничения
Настройка подключения, проверка связи и загрузка списков доступны администратору приложения «Заявки». Ручная отправка проверяет право доступа к бэкенду приложения.
Плагин не содержит команд cron/CLI, MCP-инструментов, хелперов для темы или собственных шаблонов витрины. После настройки формы вставлять дополнительный код в тему для передачи в CRM не требуется.