MODX и самописные сайты не имеют готового модуля RetailCRM, поэтому интеграцию собирают на REST API v5. Это даёт полный контроль: вы сами решаете, что и когда отправлять. Разберём базовые методы, формат каталога и обратную синхронизацию.
Подход к интеграции без модуля
Когда коробочного коннектора нет, задача сводится к нескольким вызовам REST API v5. Все запросы идут на https://аккаунт.retailcrm.ru/api/v5/ с параметром apiKey.
- Заказы —
POST /orders/createи/orders/edit. - Каталог — файл ICML, который отдаёт ваш сайт по URL.
- Обратный обмен —
/orders/historyпо расписанию или webhooks из CRM.
Ключевой принцип — везде использовать стабильный externalId: для заказа это его ID в вашей базе, для товара — артикул или внутренний ID. По нему CRM отличает создание от изменения.
API-ключ и права
В RetailCRM создайте ключ в Настройки → Интеграция → Ключи доступа к API. Тип — с ограничением по магазину, метод доступа — только необходимые группы методов.
| Группа методов | Нужна для |
|---|---|
| Заказы | Создание и обновление заказов |
| Клиенты | Сведение покупателей без дублей |
| Справочники | Чтение статусов, типов оплат и доставок |
| Загрузка каталога | Приём ICML |
Передача заказов
При оформлении заказа сайт отправляет POST-запрос. Тело содержит клиента, состав, оплату и доставку. Минимальный пример полей:
POST /api/v5/orders/create?apiKey=KEY&site=my_shop
order[externalId]=1024&order[firstName]=Иван&order[phone]=+7900...&order[items][0][offer][externalId]=SKU-15&order[items][0][quantity]=2
В ответ CRM вернёт id заказа и признак success. Сохраните связь ID сайта и ID CRM, чтобы последующие правки уходили в /orders/edit, а не создавали дубль.
Каталог в формате ICML
Каталог передаётся не через API, а файлом ICML — это XML со структурой categories и offers. Ваш сайт должен генерировать его по расписанию и отдавать по публичному URL.
<offer id="15" productId="7"><price>1990</price><name>Товар</name><categoryId>3</categoryId></offer>
- У каждого
offerобязателен уникальныйid— тот же, что вы шлёте в составе заказа. productIdгруппирует торговые предложения одного товара.- Файл должен быть в UTF-8 и валидным XML — CRM отклонит битую выгрузку целиком.
URL файла указывают в Администрирование → Магазины в поле адреса каталога ICML.
Обратная синхронизация статусов
Чтобы сайт узнавал о смене статуса и оплаты в CRM, есть два пути.
- Опрос истории — по cron дёргать
/orders/historyс сохранением меткиsinceId, чтобы забирать только новые изменения. - Webhooks — настроить в CRM отправку уведомлений на ваш endpoint при изменении заказа.
Опрос истории надёжнее при нестабильном хостинге: даже если сайт был недоступен, при следующем запуске он заберёт все накопившиеся изменения по sinceId.
Типовые ошибки самописной интеграции
| Ошибка | Как избежать |
|---|---|
| Дубли заказов | Всегда слать стабильный externalId и хранить связь ID |
| Потеря изменений | Использовать sinceId при опросе истории |
| Блокировка по лимиту | Очередь и повторные попытки при ответе 503/429 |
| Каталог не грузится | Валидировать ICML и проверять доступность URL |
Для MODX практично оформить обмен как отдельный сниппет или консольный скрипт, вызываемый по cron, а не встраивать логику прямо в шаблоны страниц.
Итог
Интеграция MODX или самописного сайта с RetailCRM — это несколько методов API v5 плюс ICML для каталога. Гибкость полная, но и ответственность на вас: стабильный externalId, очередь запросов, sinceId для истории и валидный XML. Именно эти детали отделяют устойчивый обмен от периодических дублей и потерь.
Мы проектируем и разрабатываем такие интеграции по API под конкретную бизнес-логику сайта, включая миграцию накопленных заказов в CRM без потерь.
Частые вопросы
Есть ли готовый модуль RetailCRM для MODX?
Официального коробочного модуля нет. Интеграцию собирают на REST API v5: заказы через orders/create, каталог через ICML, обратный обмен через историю или webhooks.
Какой метод API используют для передачи заказа?
POST /orders/create для нового заказа и /orders/edit для изменений. В обоих случаях указывают externalId, чтобы CRM не создавала дубль.
Как передаётся каталог?
Файлом ICML — это XML с категориями и торговыми предложениями. Сайт генерирует его по расписанию и отдаёт по публичному URL, который указывают в настройках магазина CRM.
Как узнать о смене статуса в CRM?
Либо опрашивать /orders/history по cron с сохранением sinceId, либо принимать webhooks из CRM. Опрос истории надёжнее при нестабильном хостинге.
Что такое sinceId?
Это метка последнего обработанного изменения в истории заказов. Сохраняя её, вы при каждом запросе забираете только новые события и не теряете изменения.
Как избежать блокировки по лимиту запросов?
Отправляйте обращения к API через очередь, а при ответе о превышении лимита делайте повторную попытку с задержкой, а не бьёте API в цикле.
Где хранить API-ключ?
В переменных окружения или защищённой конфигурации, а не в коде репозитория. Ключ даёт доступ к аккаунту, поэтому его права ограничивают нужным магазином и методами.
Поможем с настройкой и поддержкой RetailCRM
Поможем с настройкой, доработкой и поддержкой RetailCRM.