Як синхронізувати залишки 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 показує старе значення після оновлення бази.