REST API Битрикс24: создаём сделку из формы сайта без потери данных

01

Что должна делать интеграция формы и CRM

REST API Битрикс24 позволяет сайту создать сущность CRM по событию формы. Для отдела продаж обычно удобнее сразу создавать сделку: менеджер видит сумму или интерес, источник обращения, ответственного и историю дальнейшей работы. Но технически успешный ответ API ещё не означает, что процесс настроен правильно. Сделка без телефона, страницы входа и рекламной метки превращается в запись, которую трудно обработать и почти невозможно корректно связать с рекламой.

Надёжный маршрут выглядит так: посетитель заполняет форму, сайт валидирует данные и защищает отправку от ботов, сервер собирает контекст, ищет или создаёт контакт, затем создаёт сделку и фиксирует результат в логе. Пользователю при этом показывают понятное сообщение об успешной отправке независимо от внутреннего номера сделки. Если CRM временно недоступна, заявка не должна исчезнуть: её нужно сохранить в очереди или журнале для повторной отправки.

Маркетологу важно заранее решить, какая форма создаёт какую сделку. Заявка «Заказать звонок» и расчёт корзины не обязаны попадать в одну воронку и иметь одинаковое название. Руководитель продаж должен определить стадию, ответственного и правило обработки повторных обращений. Разработчик реализует этот сценарий через API Битрикс24, но не должен угадывать бизнес-логику по полям формы.

Не передавайте URL вебхука в JavaScript страницы: любой посетитель сможет увидеть ключ и создавать записи в вашем портале. Вызов к CRM выполняется только на сервере сайта. Для PHP-проектов на 1С-Битрикс это обычно обработчик формы или отдельный сервисный класс с тайм-аутом, логированием и повторной попыткой.

03

Сначала согласуйте карту данных, потом подключайте вебхук

Самая частая причина плохой интеграции — разработчик получает просьбу «отправить форму в CRM» без расшифровки полей. В итоге в сделке появляются имя, телефон и название сайта, а всё ценное для продаж и маркетинга остаётся в браузере. До начала работ соберите карту: поле формы, название поля CRM, формат, обязательность и правило заполнения. Особенно внимательно отнеситесь к спискам, датам, деньгам и пользовательским полям: API ждёт внутренние идентификаторы или определённый формат, а не подпись, которую видит менеджер.

Название сделки лучше формировать по шаблону: «Расчёт стоимости — Компания — site.ru» или «Заказ №12345 — сайт». В описание можно собрать комментарий клиента, URL страницы, реферер, тип формы и технический идентификатор отправки. Телефон и email должны быть у контакта, а не дублироваться произвольным текстом в сделке. Если контакт уже есть, связка с ним позволит менеджеру увидеть предыдущие обращения.

UTM не стоит пытаться записать только в название сделки. Передайте их в отдельные пользовательские поля либо в согласованные поля CRM и сохраните также первую и последнюю метку, если это предусмотрено вашей моделью атрибуции. Для проверки доступных полей и форматов используйте официальную документацию метода crm.deal.add.

04

Какие поля передавать в сделку из формы

Минимальный набор зависит от процесса продаж, однако две категории данных обязательны почти всегда: данные человека для обратной связи и контекст обращения. Если сохранить только телефон, менеджер не узнает, какую услугу смотрел посетитель и с какой рекламы пришёл. Если сохранить только UTM без телефона, заявка не имеет операционной ценности. Поля должны быть видимы менеджеру в карточке, а не спрятаны в техническом логе сайта.

Для форм заказа добавьте состав корзины, стоимость, способ доставки и номер заказа. Для B2B-заявки важнее компания, должность, интересующая услуга и регион. Не создавайте десятки пользовательских полей «на всякий случай»: согласуйте, какие из них используются в фильтрах, отчётах и автоматизациях. Остальные детали можно передать в описание в структурированном виде.

Отдельно задайте происхождение значения. Например, поле «Источник» может быть фиксированным значением «Сайт», а UTM Source — значением из URL. Если метки отсутствуют, поле не должно получать строку «undefined» или «не определено» без согласованного правила.

05

Контакт, дубли и воронка: решения, которые нельзя оставлять «по умолчанию»

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

Повторная заявка не всегда является дублем. Посетитель мог оставить запрос на другую услугу, оформить второй заказ или вернуться спустя месяц. Поэтому правило «не создавать сделки при совпадении телефона» часто ведёт к потерянным обращениям. Практичнее создавать новую сделку, но связывать её с существующим контактом; исключение — технический повтор одной отправки формы. Его определяют по идентификатору отправки или короткому временному окну, а не только по номеру телефона.

Также согласуйте категорию и стадию. Сделка, попавшая в неверную воронку, может не попасть в роботы, отчёты и очередь нужной команды. Ответственный задаётся либо конкретным сотрудником, либо бизнес-правилом: регион, услуга, источник, свободная очередь. Проверьте, что у технического пользователя вебхука есть права на создание сделок, контактов и чтение полей.

06

Порядок настройки: от вебхука до тестовой сделки

Входящий вебхук создают в Битрикс24 от имени пользователя с минимально достаточными правами. Для такой задачи ему нужны права на CRM и конкретные сущности, но не административный доступ ко всему порталу. URL вебхука содержит секрет: храните его в настройках вне публичного репозитория и не отправляйте в браузер, почту или систему аналитики. При подозрении на утечку вебхук следует заменить, а не пытаться «спрятать» старую ссылку.

На стороне сайта сначала сделайте серверный обработчик, затем подключайте его к конкретной форме. Обработчик должен валидировать обязательные поля, проверять согласие, ограничивать повторные запросы и только после этого вызывать CRM. Установите короткий тайм-аут: пользователь не должен ждать минуту из-за недоступного внешнего сервиса. Ошибку CRM отделяйте от ошибки формы — иначе команда будет искать проблему не в том месте.

Для отладки полезен отдельный тестовый сценарий или тестовая воронка. Он позволяет не засорять боевую очередь и увидеть все поля до запуска рекламы. После проверки переключайте настройки на рабочую воронку по согласованному чек-листу.

1. 1

   Подготовьте поля CRM. Создайте пользовательские поля для UTM и страницы, настройте видимость и права.

2. 2

   Создайте вебхук. Выдайте только необходимые права и сохраните URL в защищённой конфигурации сайта.

3. 3

   Соберите контекст формы. Зафиксируйте данные формы, метки, реферер и уникальный ID отправки до вызова API.

4. 4

   Настройте поиск контакта. Нормализуйте телефон, найдите совпадение и определите действие для найденной записи.

5. 5

   Создайте и проверьте сделку. Передайте поля, прочитайте ответ API, сохраните ID и обработайте ошибку.

07

Как принять работу: тестируйте не один запрос, а весь маршрут

Приёмка интеграции начинается с таблицы сценариев. Один успешный тест с вашим телефоном не показывает, что корректно работают UTM, дубли, пустой email, повторная отправка и недоступность CRM. Пройдите сценарии с сотрудником продаж: он должен открыть созданную сделку и без объяснений понять, кто обратился, откуда пришёл и что запросил. Затем маркетолог сверяет метки с URL тестового перехода и проверяет, попадают ли обращения в нужный отчёт.

Попросите разработчика показать серверный лог на тестовой заявке. В нём должны быть дата, технический ID отправки, результат валидации, HTTP-код и ID созданной сущности. Секрет вебхука, полный телефон и другие персональные данные не следует выводить в открытом виде. Лог нужен не для ежедневного ручного контроля, а чтобы быстро локализовать проблему, если заявка пропадёт.

Проверьте события после создания сделки: назначение ответственного, роботы, уведомления и обязательные поля на стадии. Иногда API создаёт запись правильно, но автоматизация сразу переносит её в другую стадию или не даёт менеджеру начать работу. Это уже не ошибка формы, но для бизнеса результат одинаково плохой.

08

Ошибки, из-за которых формы «работают», а заявки теряются

Внешне форма может показывать сообщение «Спасибо», хотя запрос к CRM завершился ошибкой. Причины типовые: вебхук удалён или создан от уволенного пользователя, изменились права, переименовали или удалили пользовательское поле, сервер не может установить соединение, а код не проверяет ответ API. Поэтому статус успеха для посетителя нельзя считать доказательством появления сделки. Проверяйте ID в ответе CRM и ведите технический журнал.

Вторая группа ошибок связана с маркетинговыми данными. UTM считывают только в момент отправки, хотя посетитель перешёл на целевую страницу, затем несколько раз сменил URL. Или метки подставляются из URL без очистки и ломают запрос из-за неподходящего формата. Контекст нужно сохранить при первом визите по согласованному сроку и перед отправкой валидировать.

Наконец, опасна работа с персональными данными. Не отправляйте форму в CRM до фиксации согласия, не пишите в логи полный текст обращения без необходимости и ограничьте доступ к журналам. Если форма связана с рекламными системами и коллтрекингом, документируйте, какие идентификаторы передаются и кто имеет к ним доступ.

09

Когда достаточно настройки, а когда нужен подрядчик

Простая форма с одной воронкой и двумя-тремя полями может быть настроена быстро, если в портале уже определены поля, права и ответственные. Но даже в этом случае владельцу сайта важно зафиксировать маршрут данных и пройти тесты до запуска рекламы. Иначе источник лидов окажется неизвестным, а техническая ошибка проявится только после потери нескольких обращений.

Подключайте разработчика, когда требуется поиск и объединение контактов, передача корзины и товаров, распределение между менеджерами, сохранение первой и последней UTM, работа с несколькими доменами или очередь повторной отправки. Отдельная задача нужна, если формы сделаны сторонним сервисом, а сайт на 1С-Битрикс должен принимать и обогащать данные на своей стороне.

Для контроля результата достаточно трёх вопросов: создаётся ли нужная сделка, видит ли менеджер полный контекст обращения и можно ли восстановить заявку при сбое CRM. Если на один из них нет уверенного ответа, не начинайте трафик с предположения, что интеграция работает. Сначала согласуйте карту полей и критерии приёмки, затем внесите изменения и повторите сценарии на боевых настройках.