Данные и отправка
Обновлено
Какие данные уходят в RetailCRM
| Данные заявки | Поле или результат в заказе CRM |
|---|---|
| Имя из роли «Имя» | firstName — первое слово, lastName — оставшаяся часть |
| Телефон и email из соответствующих ролей | phone, email |
| Значение роли «Комментарий» | customerComment; также остаётся в общем тексте полей |
| Заполненные поля формы | managerComment: названия и значения обычным текстом |
| Прикреплённые файлы | Имена и публичные ссылки в managerComment; сами файлы в CRM не загружаются |
| Номер заявки, название формы, дата создания | Текст в managerComment |
| Поле, выбранное в «Поле с суммой» | Одна позиция items: название формы, цена из поля, количество 1 |
| Товары корзины при включённой настройке | Текст в managerComment, если его предоставляет другой плагин |
| Параметры группы «Куда» | Магазин, orderType, orderMethod, status, managerId |
| Идентификатор заявки и установки | externalId для поиска заказа при повторе |
Поля типов html, step и captcha в комментарий не попадают. Пустые значения пропускаются. Произвольные поля CRM плагин не заполняет. Значение роли «Компания» не передаётся в отдельное поле компании CRM, но соответствующее заполненное поле формы входит в общий комментарий.
Роли контактных полей
В редакторе полей формы настройка «Роль поля» определяет назначение значения. Для интеграции используются «Имя», «Телефон», «Email» и «Комментарий». Если у нескольких полей одна роль, берётся первое непустое значение.
Для полей типов phone и email соответствующая роль определяется и без явного выбора. Простое название текстового поля «Телефон» само по себе роль не назначает.
Если имя, телефон или email отсутствуют в значениях ролей, плагин пытается дополнить их из связанного контакта Вебасиста. Имя, телефон и email ограничиваются 255 символами каждый.
UTM-данные
Плагин ищет поля формы по их названиям: сравнение выполняется после удаления пробелов по краям и приведения к нижнему регистру.
| Название поля формы | Поле источника заказа |
|---|---|
utm_source |
source.source |
utm_medium |
source.medium |
utm_campaign |
source.campaign |
utm_term |
source.keyword |
utm_content |
source.content |
Передаются только непустые значения, не более 255 символов каждое. Сам плагин не собирает метки из адреса посетителя: для передачи они должны быть сохранены в полях заявки.
Как выбирается клиент
Сначала плагин проверяет сохранённую связь контакта Вебасиста с клиентом RetailCRM. Если клиент существует, используется эта связь. Если CRM вернула отсутствие клиента, связь удаляется и выполняется поиск по телефону и email. Сетевая ошибка проверки не считается удалением клиента.
Если сохранённой связи нет:
- Для поиска по телефону используются последние десять цифр. Номера короче десяти цифр и распознанные заглушки в поиске не участвуют.
- Email сравнивается без учёта регистра и пробелов по краям.
- При совпадении по обоим признакам выбирается общий клиент. Если таких клиентов несколько — с наименьшим ID.
- Если совпадение есть только по одному признаку, выбирается клиент с наименьшим ID среди найденных.
- Если телефон и email найдены у разных клиентов без общего совпадения, плагин не прикрепляет ни одного и показывает предупреждение в карточке заявки.
При нескольких кандидатах карточка предупреждает о похожих клиентах. Объединять дубли нужно в CRM. Если поиск по телефону возвращает более двух страниц результатов, плагин также не выбирает клиента и показывает предупреждение.
Существующие карточки клиентов плагин не изменяет. Если клиент не прикреплён, заказ передаётся с контактными данными, а создание клиента выполняет RetailCRM. При конфликте телефона и email связь с автоматически созданным клиентом не запоминается; проверьте клиента заказа в CRM.
Плагин рассчитан на один аккаунт CRM для установки Вебасиста. Перед переключением на другой аккаунт разработчику необходимо проверить и сбросить старые связи контактов: автоматического сброса при смене адреса в коде нет.
Отправка и восстановление после ошибки
Плагин хранит состояние передачи отдельно от заявки. Ошибка CRM не удаляет заявку и не меняет её поля или статус.
| Состояние в карточке | Что делать |
|---|---|
| «Отправить в RetailCRM» | Нажать для первой ручной отправки |
| «Отправляется в RetailCRM…» | Дождаться результата; параллельная отправка блокируется |
| «Не отправлено: …» | Устранить причину и нажать «Повторить» |
| «Заказ №… создан» | Перейти по ссылке «Открыть в RetailCRM» и проверить заказ |
При повторе сначала ищется заказ по externalId в магазине первой попытки. Если заказ уже был создан, но ответ потерялся, плагин сохраняет найденный заказ вместо создания нового. При сетевой ошибке поиска новая отправка останавливается. Изменение магазина в настройках формы не меняет магазин уже начатой передачи.
Передачу со статусом ожидания можно повторить после истечения 120 секунд с её последнего обновления. Для появления актуального состояния заново откройте карточку. Успешно переданная заявка не отправляется повторно, в том числе после изменения её полей.
Фоновой очереди и периодического повтора по cron нет. Неудачную передачу можно повторить кнопкой; ещё одну попытку также может запустить последующее подходящее событие статуса.
В карточке заявки показаны номер заказа RetailCRM, ссылка перехода, время отправки и клиент CRM.
Для разработчика
Автоматическая отправка подключена к событиям request_after_create и request_after_status_change. Если событие передано с skip_notifications, автоматической отправки не будет. Ручная отправка не зависит от этого флага.
Вызовы API выполняются на сервере. Ключ передаётся заголовком X-API-KEY. На отдельный запрос отводится до пяти секунд; общий бюджет передачи при создании — восемь секунд, при смене статуса и вручную — двадцать. Это ограничения ожидания, а не обещание времени создания заказа.
Подключение, проверка и справочники доступны администратору приложения. Ручной обработчик требует доступ к бэкенду «Заявок» и POST-запрос.
Диагностика записывается в журнал requests/plugins/retailcrm.log относительно каталога журналов Webasyst. Плагин скрывает текущий ключ API в выводимых ошибках и своих сообщениях журнала.
externalId состоит из первых десяти символов MD5 корневого пути установки, дефиса и ID заявки. При переносе установки в другой каталог идентификатор изменится; перед повтором незавершённых отправок разработчику следует проверить уже созданные заказы.