Когда готового модуля нет, выручает API. RetailCRM предоставляет REST API v5, через который любой внешний сервис читает и пишет заказы, клиентов, товары и справочники — от аналитики до товароучёта.
Когда нужен API, а когда готовый модуль
Прежде чем писать код, стоит проверить маркетплейс RetailCRM: для популярных сервисов уже есть коробочные модули. API берут там, где готового решения нет или его логики не хватает.
- Готовый модуль — быстрый старт, но фиксированный набор возможностей.
- Коннектор (Albato, ApiX-Drive) — визуальные связки без кода для типовых событий.
- Прямой API — полный контроль, нестандартная логика, свои поля и расчёты.
Ключи доступа и права
Доступ к API даёт ключ, который создаётся в разделе Настройки → Интеграция → Ключи доступа к API. Каждому ключу назначается набор прав по принципу минимальной достаточности.
- Отдельный ключ на каждую интеграцию — так проще отозвать доступ, не ломая остальные.
- Выдавайте только нужные методы: сервису аналитики хватит чтения заказов и справочников.
- Ограничивайте магазины и группы методов, если ключ используется узко.
Базовые методы v5
API построено вокруг сущностей. Основные группы методов, которые нужны большинству интеграций:
| Задача | Метод |
|---|---|
| Список заказов | GET /api/v5/orders |
| Создать заказ | POST /api/v5/orders/create |
| Изменить заказ | POST /api/v5/orders/{id}/edit |
| Клиенты | GET /api/v5/customers |
| Справочники (статусы и пр.) | GET /api/v5/reference/* |
Ключ передаётся в параметре apiKey или заголовке X-API-KEY. Ответы приходят в JSON с полем success, по которому проверяется результат.
GET /api/v5/orders?filter[statusUpdatedAtFrom]=2026-07-14 00:00:00&limit=100
Выборка данных: фильтры и пагинация
Чтобы не тянуть всю базу каждый раз, используйте фильтры по дате изменения и постраничную выборку.
- Инкрементально — фильтр
statusUpdatedAtFromилиcustomUpdatedAtFromзабирает только изменившееся с прошлой синхронизации. - Пагинация — параметры
limit(до 100) иpage, либо курсорная выборка для больших объёмов. - Точка отсчёта — храните время последней успешной выгрузки и стартуйте от него.
Такой подход снижает нагрузку и укладывается в лимиты API, а внешний сервис получает свежие данные без полного перебора.
Лимиты, ошибки и повторы
API ограничивает частоту запросов. При превышении сервер отвечает статусом 429 Too Many Requests. Надёжная интеграция это учитывает.
| Код | Причина | Что делать |
|---|---|---|
| 400 | ошибка в данных запроса | исправить тело, не повторять вслепую |
| 403 | нет прав у ключа | расширить права ключа |
| 429 | превышен лимит | пауза и повтор с backoff |
| 5xx | сбой на стороне сервиса | повтор с задержкой |
Надёжность обмена
Промышленная интеграция отличается от «скрипта на коленке» устойчивостью к сбоям. Что заложить сразу:
- Идемпотентность — используйте
externalIdзаказа, чтобы повтор не создавал дубль. - Логирование — сохраняйте запросы и ответы для разбора инцидентов.
- Сверка — периодически сверяйте контрольные суммы или количество записей.
- Комбинация с веб-хуками — веб-хуки для оперативности, опрос API для восстановления пропусков.
Такой набор превращает интеграцию в предсказуемый механизм, который переживает временные сбои сети и обеих систем.
Итог
Подключение внешнего сервиса к RetailCRM по API — это отдельный ключ с минимальными правами, работа с методами v5 через фильтры и пагинацию, обработка лимитов и ошибок с повторами и защита от дублей через externalId. В связке с веб-хуками получается надёжный двусторонний обмен.
Мы проектируем такие интеграции с учётом лимитов и отказоустойчивости, настраиваем инкрементальную выгрузку и логирование, а сложные сценарии закрываем прямым API там, где готовых модулей не хватает. Если нужен стабильный мост между RetailCRM и вашим сервисом — поможем его построить.
Частые вопросы
Где создать API-ключ и какие права выдать?
В разделе «Настройки → Интеграция → Ключи доступа к API». Права выдавайте по минимуму: сервису аналитики достаточно чтения заказов и справочников, товароучёту — работы с заказами и товарами.
Как забирать только новые и изменённые заказы?
Фильтром по дате изменения, например statusUpdatedAtFrom, и хранением времени последней выгрузки. Это инкрементальный обмен без полного перебора базы.
Что делать при ответе 429?
Это превышение лимита запросов. Нужно сделать паузу и повторить запрос с экспоненциальным backoff, а не долбить API непрерывно.
Как не создать дубли заказов при повторах?
Использовать externalId — внешний идентификатор заказа. При повторном создании с тем же externalId RetailCRM не заведёт дубль, а свяжет с существующим.
API или веб-хуки — что выбрать?
Их сочетают: веб-хуки дают мгновенную реакцию на события, а периодический опрос API восстанавливает пропущенные из-за сбоев данные. Вместе они надёжнее любого из подходов по отдельности.
Можно ли обойтись без разработки?
Для типовых сценариев — да, через готовые модули маркетплейса или коннекторы Albato и ApiX-Drive. Прямой API нужен, когда логика нестандартна.
В каком формате отвечает API?
В JSON с полем success и данными сущностей. Результат каждого запроса нужно проверять по success и коду ответа, а не считать успешным по умолчанию.
Поможем с настройкой и поддержкой RetailCRM
Поможем с настройкой, доработкой и поддержкой RetailCRM.