Интеграция с самописным сайтом через API

Самописный сайт не имеет готового модуля, поэтому интеграция строится напрямую через REST API RetailCRM. Это гибко: вы сами решаете, что и когда передавать. Разберём ключевые методы, выгрузку каталога и защиту обмена от потерь.

API v5 и ключ доступа

RetailCRM предоставляет REST API версии v5. Базовый адрес — https://{account}.retailcrm.ru/api/v5/, авторизация — по параметру apiKey. Ключ создаётся в Настройки → Интеграция → Ключи доступа к API с типом «Магазин» и ограниченным набором методов.

• Формат обмена — JSON, ответы содержат флаг success;
• Есть готовый PHP SDK (retailcrm/api-client-php), но подойдёт и обычный HTTP-клиент;
• У API есть лимит запросов в секунду — массовые операции делают пачками.

Создание заказа

Новый заказ отправляется методом POST orders/create. В теле — номер, состав, суммы, оплата, доставка и покупатель. В ответ CRM возвращает внутренний id, который сайт сохраняет для будущих обновлений.

Минимальный набор полей заказа:

1. externalId — ваш номер заказа для связи систем;
2. items — позиции с offer.externalId и ценой;
3. customer — покупатель (телефон, e-mail, имя);
4. delivery и payments — доставка и оплата.

Позиции связываются со справочником по offer.externalId, совпадающему с ICML. Без этого товар в заказе будет «сырым», без картинки и остатка.

Клиенты и дедупликация

Клиент передаётся вместе с заказом или отдельно методом customers/create. RetailCRM ищет контакт по телефону и e-mail и привязывает заказ к существующей карточке, если находит совпадение.

Чтобы дедупликация работала, приводите телефон к единому формату +7XXXXXXXXXX и не создавайте клиента отдельным запросом, если он и так уйдёт вместе с заказом.

Выгрузка каталога в ICML

Товары нужны, чтобы позиции заказа связались со справочником. Самописный сайт отдаёт каталог в формате ICML по постоянной ссылке, а RetailCRM забирает файл по расписанию.

• Скрипт обходит активные товары и формирует валидный XML;
• Вариации связываются общим productId, каждая — своим id;
• Остаток передаётся атрибутом quantity, артикул — vendorCode.

Ссылку на файл (например https://shop.ru/retailcrm/icml) добавляют в Администрирование → Настройки каталога. Для больших каталогов файл строят заранее по cron, чтобы избежать таймаутов.

Вебхуки и обратный обмен

Чтобы получать изменения из CRM (смену статуса, оплату, правки оператора), сайт подписывается на вебхуки RetailCRM или периодически опрашивает метод orders/history.

Метод orders/history отдаёт изменения с момента последнего запроса по sinceId, что удобно для гарантированной синхронизации без потерь — даже если вебхук был пропущен.

Надёжность обмена и отладка

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

• Очередь отправки: заказ, не ушедший из-за ошибки или лимита API, повторяется, а не теряется;
• Идемпотентность: ищите заказ по externalId и делайте orders/edit вместо дублирующего создания;
• Логирование: сохраняйте запросы и ответы CRM — по ним видно, где обмен разошёлся;
• Справочники: способы оплаты и доставки берите из references/*, а не хардкодьте коды.

Итог

Интеграция самописного сайта с RetailCRM строится на REST API v5: ключ типа «Магазин», создание заказов через orders/create, дедупликация клиентов по телефону, выгрузка каталога в ICML и обратный обмен через вебхуки или orders/history. Гибкость такого подхода требует дисциплины — очередей, идемпотентности и логирования.

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