Модуль интеграции — это способ подключить к RetailCRM внешний сервис: службу доставки, платёжную систему, склад или собственную учётную систему. Модуль регистрируется через API, объявляет свои возможности и получает единую точку настройки в интерфейсе CRM.
Зачем нужен модуль интеграции
Прямые вызовы API v5 подходят для разовой синхронизации, но полноценная интеграция требует, чтобы RetailCRM "знала" о вашем сервисе: показывала его в списке подключений, хранила настройки, отображала статус доставки или оплаты. Для этого сервис оформляют как интеграционный модуль.
- Единая карточка подключения в разделе интеграций;
- Хранение настроек аккаунта на стороне RetailCRM;
- Регистрация возможностей: доставка, оплата, склад, транспорт сообщений;
- Ссылка на страницу настройки (connect/account), размещённую на вашем сервере.
Разница принципиальная: без модуля ваш сервис остаётся для RetailCRM "невидимым" внешним потребителем API, а с модулем становится полноценным элементом системы. Менеджер видит подключение, администратор управляет настройками, а статусы доставки и оплаты отображаются в карточке заказа. Это особенно важно, когда интеграцией пользуются несколько сотрудников и нужна прозрачность, кто и что подключил.
Регистрация через API
Модуль регистрируется и обновляется методом POST /api/v5/integration-modules/{code}/edit, где {code} — уникальный код модуля. В теле передаётся JSON-описание с параметром integrationModule.
POST /api/v5/integration-modules/my-delivery/edit
Минимальный набор полей манифеста:
| Поле | Назначение |
|---|---|
code | Уникальный код модуля |
integrationCode | Код интеграции |
active | Признак активности |
name | Название для интерфейса |
baseUrl | Базовый адрес вашего сервиса |
accountUrl | Страница настройки аккаунта |
integrations | Объявляемые возможности |
Объявление возможностей
В блоке integrations модуль сообщает, что именно он умеет. RetailCRM использует это, чтобы правильно отобразить модуль и подключить нужные механизмы.
- delivery — интеграция службы доставки: расчёт стоимости, статусы, трек-номера;
- payment — платёжная интеграция: создание платежа и проверка статуса;
- store — складская интеграция: остатки и синхронизация каталога;
- mgTransport — транспорт сообщений для Message Gateway.
Каждая возможность требует своего набора обработчиков на стороне сервиса — например, для доставки RetailCRM будет обращаться к вашим эндпоинтам расчёта и отслеживания. Объявляйте только те возможности, которые реально реализованы, иначе интерфейс покажет нерабочие функции.
Страница подключения и настройки
Модуль ссылается на страницы, размещённые на вашем сервере: connect (первичное подключение) и account (настройки конкретного аккаунта). Через них проходит связывание учётной записи RetailCRM с вашим сервисом.
- Пользователь открывает страницу подключения из интерфейса CRM;
- Ваш сервис получает параметры аккаунта и предлагает авторизацию или ввод настроек;
- После подтверждения сервис вызывает
integration-modules/{code}/editи активирует модуль для этого аккаунта; - Дальнейший обмен данными идёт через API v5 с ключом, привязанным к аккаунту.
Обмен данными
После активации модуль обменивается данными с RetailCRM по двум направлениям. Исходящие изменения (новые заказы, смена статуса) сервис получает, опрашивая историю через API — orders/history и customers/history. Входящие данные (обновление статуса доставки, трек-номер, остатки) сервис отправляет соответствующими методами API v5.
- Синхронизация статусов — обновление статуса доставки в заказе;
- Остатки — передача складских остатков методами работы с товарами;
- Платежи — фиксация оплаты и её статуса.
Для устойчивого обмена реализуют очередь задач и повторные попытки: сеть и внешние сервисы иногда недоступны, и потеря событий недопустима. Опрос истории строят инкрементально — сохраняют идентификатор последнего обработанного изменения и запрашивают только новые записи, а не всю историю целиком. Так обмен остаётся быстрым даже при десятках тысяч заказов и не упирается в лимиты API. Массовые операции группируют в пакетные методы там, где они доступны, чтобы уменьшить число запросов.
Тестирование и отладка
Разработку модуля ведут на тестовом аккаунте RetailCRM, чтобы не затронуть боевые данные. Полезные приёмы:
- Логируйте вызовы API — и запросы к RetailCRM, и её обращения к вашим эндпоинтам;
- Проверяйте манифест — ошибка в
integrationsприводит к тому, что возможность не появляется в интерфейсе; - Отрабатывайте ошибки — коды ответа API и лимиты запросов нужно обрабатывать явно;
- Идемпотентность — повторная обработка одного события не должна дублировать данные.
Отдельное внимание — воспроизводимости сбоев. Сохраняйте не только факт ошибки, но и тело запроса и ответа, чтобы позже повторить проблемный сценарий на тестовом аккаунте. Перед публичным запуском полезно прогнать модуль на потоке реальных, но обезличенных заказов: это выявляет крайние случаи с пустыми полями и нестандартными данными, которые не воспроизводятся на "чистых" тестовых заказах.
Итог
Модуль интеграции превращает разрозненные вызовы API в управляемое подключение: с карточкой в интерфейсе, хранением настроек, объявленными возможностями и безопасным обменом данными. Ключевые этапы — регистрация через integration-modules/{code}/edit, страницы connect/account и устойчивый обмен с очередью и повторами.
Мы проектируем и разрабатываем такие модули под конкретные бизнес-задачи: от службы доставки до обмена с 1С и B2B-порталом. Берём на себя архитектуру, безопасность ключей и отказоустойчивость обмена, чтобы интеграция работала стабильно под нагрузкой.
Частые вопросы
Каким методом регистрируется модуль интеграции?
Методом POST /api/v5/integration-modules/{code}/edit, где code — уникальный код модуля. В теле передаётся JSON-манифест с описанием возможностей.
Обязательно ли оформлять интеграцию как модуль?
Для разовой синхронизации достаточно прямых вызовов API. Но для постоянного подключения модуль удобнее: он даёт карточку в интерфейсе, хранение настроек и объявление возможностей.
Какие возможности можно объявить в модуле?
Основные — доставка, оплата, склад и транспорт сообщений для Message Gateway. Объявляйте только реально реализованные, чтобы в интерфейсе не появлялись нерабочие функции.
Где размещаются страницы connect и account?
На вашем сервере. RetailCRM ссылается на них из карточки модуля, а через них проходит связывание аккаунта CRM с вашим сервисом.
Как модуль узнаёт об изменениях в заказах?
Через опрос истории методами orders/history и customers/history. RetailCRM использует модель истории изменений вместо классических push-вебхуков для основных сущностей.
Как безопасно хранить API-ключи аккаунтов?
Ключи хранят в зашифрованном виде и строго разграничивают по аккаунтам. Это исключает пересечение данных разных клиентов при мультиаккаунтной работе модуля.
Как избежать дублирования данных при обмене?
Реализуйте идемпотентную обработку событий: повторная обработка одного и того же изменения не должна создавать дубли. Дополнительно помогает очередь задач с повторными попытками.
Поможем с настройкой и поддержкой Для разработчиков
Поможем с настройкой, доработкой и поддержкой Для разработчиков.