Передаваемые данные

Подключение и направление обмена

Плагин использует API v4 amoCRM или Kommo с долгосрочным Bearer-токеном. Адрес и токен задаются в настройках плагина; порядок подключения — в статье «Установка и первые шаги».

Обмен направлен из «Заявок» в CRM. В плагине нет входящих вебхуков, фоновой очереди, команд cron/CLI или собственных MCP-инструментов. Встраивать вызовы в тему сайта не требуется: отправка выполняется по событиям приложения и кнопкой в карточке.

Содержимое отправки

Поля типов HTML, шаг и CAPTCHA в примечание не включаются. Произвольное сопоставление каждого поля формы с отдельным полем CRM не предусмотрено. Компания из формы не создаётся отдельной сущностью CRM; её заполненное поле может попасть в текст примечания.

UTM и источник

Плагин распознаёт поля формы по названию, без учёта регистра и пробелов по краям:

utm_source
utm_medium
utm_campaign
utm_content
utm_term
utm_referrer
referrer

Значения передаются в дополнительные поля сделки, только если CRM вернула соответствующий код в верхнем регистре, например UTM_SOURCE. Новые поля в CRM плагин не создаёт. Как заполненные поля заявки эти значения также входят в примечание. Если чтение списка полей CRM завершилось ошибкой, в карточке появляется предупреждение «UTM переданы только в примечании» с причиной.

В режиме «В Неразобранное» дополнительно отправляются идентификатор источника, название «Заявки:» с именем формы и метаданные: идентификатор и имя формы, страница отправки, IP, время создания и источник перехода. Если адрес страницы или источник не найден либо некорректен, используются адрес сайта/установки, а в крайнем случае https://localhost/. Для отсутствующего IP используется 0.0.0.0.

Корзина магазина

Плагин «Заказы из заявок» может передать текст корзины с товарами и ценами. В форме должен быть настроен сбор корзины этим плагином, а на вкладке «amoCRM» включена настройка «Передавать товары корзины в комментарии».

Позиции добавляются текстом к примечанию, а не как товары каталога CRM. Этот переключатель управляет всем дополнительным текстом от события request_extra_text, а не только корзиной. Для разработчика: событие получает request_id, form и массив lines по ссылке; плагин amoCRM принимает непустые скалярные строки и обрезает каждую до 1000 символов.

Как выбирается контакт

Имя, телефон и email извлекаются из ролей полей формы. Для полей типов email и телефон роль определяется также по типу поля. Если одной роли соответствуют несколько полей, берётся первое непустое значение. Недостающие имя, телефон и email могут быть взяты из связанного контакта Webasyst.

Порядок поиска:

1. Проверяется сохранённая связь с контактом CRM для контакта Webasyst. Если связанный контакт существует, используется он.
2. При отсутствии действующей связи выполняется поиск по телефону и email. Телефон сравнивается по последним десяти цифрам, email — без учёта регистра.
3. При совпадении обоих признаков используется контакт из их пересечения. Если совпадения есть только по одному признаку, используется найденный контакт.
4. При отсутствии совпадений создаётся контакт. Имя берётся из имени клиента, затем телефона, затем email; если всё пусто — «Посетитель».

Телефоны короче шести цифр и распознанные номера-заглушки не участвуют в поиске. Наличие телефона-заглушки не означает, что он удаляется из данных нового контакта.

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

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

Существующие имя, телефон и email контакта плагин не изменяет. Если для контакта Webasyst уже сохранена действующая связь, новый поиск по изменившимся данным заявки не выполняется.

Повторная отправка и ограничения

Журнал отправок хранится по номеру заявки. Пока попытка выполняется, повторный запуск блокируется; успешно отправленная заявка больше не выгружается. Если попытка осталась незавершённой более 120 секунд, её можно повторить из карточки.

При повторе после ошибки плагин ищет сделку по точному служебному тегу заявки. Если запись найдена, она используется вместо создания новой; плагин пробует прикрепить примечание и восстанавливает результат в журнале. Служебный тег имеет вид заявка-<идентификатор установки>-<номер заявки>. Сохраняйте его в CRM: он нужен для поиска результата прошлой попытки.

Это защита от повторных событий и потерянного ответа, а не безусловная гарантия отсутствия дублей при любых изменениях данных CRM или переносе сайта.

При ошибке сети или API причина показывается в карточке, рядом доступна «Повторить». Автоматического повтора по расписанию нет. Следующее подходящее событие также может повторить неуспешную отправку.

Примечание создаётся отдельным запросом после сделки. Если этот запрос не удался, сделка всё равно отмечается отправленной, а в карточке показывается предупреждение. Отдельной кнопки для повторного прикрепления примечания нет. Аналогично, если ответ Неразобранного не содержит номера сделки, текст не прикрепляется; ссылка ведёт на воронку.

Доступ и диагностика для разработчика

Проверка подключения и загрузка справочников требуют прав администратора приложения «Заявки». Действие ручной отправки проверяет право доступа к бэкенду приложения. Запросы бэкенда защищаются механизмом CSRF Webasyst.

Для диагностики используется журнал wa-log/requests/plugins/amocrm.log. Клиент API не записывает заголовки авторизации и исходные ответы в журнал, а из текстов ошибок API скрывает значение используемого токена.

Автоматические обработчики создания и изменения статуса пропускают событие, если в его параметрах установлен skip_notifications. Это следует учитывать при создании или изменении заявок собственным кодом.