Как синхронизировать остатки KeyCRM с OpenCart

Синхронизация остатков между KeyCRM и OpenCart требуется, когда одна и та же товарная позиция продается через сайт, маркетплейсы или менеджеров. Ее цель – не просто скопировать число, а правильно сопоставить товар и вариант, учесть резерв, выбрать склад и не перезаписать более новое значение старым данным.

Почему передача заказов не равна синхронизации остатков

Штатная интеграция keyCRM из OpenCart передает заказ, но обратное обновление остатков на сайте требует API-реализации. Это прямо указано в актуальной официальной инструкции keyCRM об остатках.

Расширенный модуль KeyCRM для OpenCart автоматизирует этот обмен: обновляет складские остатки и цены, поддерживает варианты и настройки, импорт/экспорт продуктов, CRON и webhook-события. Но даже с готовым модулем нужно сначала определить правила учета.

Выберите источник правды

До запуска решите, где менеджер имеет право изменять остаток:

• KeyCRM → OpenCart. CRM ведет склад, резервы и продажи по всем каналам; сайт только показывает доступное количество.
• OpenCart → KeyCRM. Магазин является основным каталогом и передает фактический остаток в CRM.
• Двухсторонний обмен. Требуются версии записей, четкие события и правила разрешения конфликта. Простого «последняя запись побеждает» часто недостаточно.

SKU товаров и опций - ключ сопоставления

KeyCRM и OpenCart имеют собственные внутренние ID, поэтому напрямую сравнивать их нельзя. Стабильным бизнес-ключом выступает артикул SKU. Он должен быть:

• пустым для каждого товара;
• уникальным в пределах всего каталога;
• отдельным для каждого варианта – размера, цвета или комплектации;
• одинаковым в KeyCRM и OpenCart;
• неизменным после установления связи или измененным синхронно в обеих системах.

В стандартной конфигурации OpenCart поле SKU может быть только у родительского товара. Для синхронизации опций часто требуется дополнительное поле артикула на уровне значения опции. Без него CRM не отличит, например, футболку M от футболки L.

Количество, резерв и несколько складов

В KeyCRM доступны физическое количество и резерв. Для витрины обычно нужно доступное количество, а не весь физический остаток. Формула зависит от бизнес-процесса, но чаще всего это:

Если составов несколько, зафиксируйте, какие из них обслуживают сайт: один конкретный, сумма избранных или отдельные остатки по локациям. Не суммируйте состав брака, транзит или офлайн-резерв без явного решения бизнеса.

API, CRON и webhook: что за что отвечает

Надежная схема сочетает webhook для скорости и CRON для контрольной сверки. Если одно событие не пришло, плановый процесс исправит несовпадение.

API-лимиты, пауза и очередь

За актуальной справкой keyCRM, один API-ключ имеет предел до 20 запросов в минуту; рекомендованная пауза – около трех секунд. Превышение возвращает 429. Поэтому каталог с тысячами позиций нельзя синхронизировать параллельным циклом без ограничения скорости.

Правильный процесс:

1. получает страницу данных или небольшой пакет;
2. кладет задачу в контролируемую очередь;
3. обрабатывает их с заданной паузой;
4. при 429 ждет и повторяет операцию;
5. записывает последнюю успешную позицию, чтобы не начинать импорт с нуля.

Безопасный запуск синхронизации

1. Сделайте резервную копию и выключите массовые ручные правки во время первой сверки.
2. Экспортируйте таблицу SKU из обеих систем и найдите пустые и дублированные артикулы.
3. Выберите 5–10 товаров: без опций, с опциями, с нулевым остатком и резервом.
4. Запустите обмен для тестового набора.
5. Сверьте количество в KeyCRM, OpenCart и на витрине.
6. Имитируйте продажу на сайте и изменение в CRM.
7. Проверьте повторное событие, 429, временная недоступность API и журнал.
8. Только после этого запускайте весь каталог пакетами.

Типичные причины неправильного остатка

• одинаковый SKU у нескольких товаров или опций;
• артикул содержит незаметный пробел или разный регистр;
• физическое количество используется без вычитания резерва;
• выбран не тот состав или подведены лишние составы;
• одновременно работают две CRON-задачи;
• старое пакетное обновление перезаписывает более новое событие;
• API отвечает 429, но интеграция не повторяет запрос;
• кэш OpenCart показывает старое значение после обновления базы.