KeyCRM Sync — CRM для OpenCart 2.3, 3.x & 4.x

KeyCRM Sync для OpenCart 2.3, 3.x і 4.x — модуль двосторонньої синхронізації магазину з KeyCRM. У прямому напрямку кожне замовлення OpenCart автоматично створюється в CRM — з покупцем, товарами, доставкою і способом оплати. У зворотному (опційно) модуль підтягує з KeyCRM назад в OpenCart статуси замовлень, номери ТТН і навіть залишки товарів. Менеджери ведуть продажі в одному вікні CRM, а магазин залишається актуальним без ручної роботи.

Модуль повністю безкоштовний. Код відкритий на GitHub: github.com/catcodestudio/opencart-keycrm-sync. Для роботи достатньо API-ключа з кабінету KeyCRM — без підписок і додаткових сервісів.

Як це працює — крок за кроком

1. Покупець оформлює замовлення в магазині OpenCart.
2. Модуль формує дані для CRM: контакти, товари, доставка й оплата. Телефон нормалізується у формат +380, позиції з нульовою ціною пропускаються.
3. Замовлення відправляється у KeyCRM — одразу при оформленні або при переході в налаштований статус. Джерело замовлень створюється в CRM автоматично при першій відправці.
4. Захист від дублів: унікальний ключ UNIQUE(order_id, target) у журналі гарантує, що замовлення не задвоїться, навіть якщо подія спрацює повторно.
5. Невдалі відправки потрапляють у чергу повторних спроб — окрема cron-задача добиває їх з обмеженням кількості спроб.
6. Зворотна синхронізація (якщо ввімкнена): друга cron-задача періодично забирає з KeyCRM оновлені статуси (за вашим мапінгом «статус KeyCRM → статус OpenCart»), додає в історію замовлення коментар з ТТН і, окремим чекбоксом, оновлює залишки товарів за SKU.

Що під капотом

• Ідемпотентність на рівні БД — UNIQUE(order_id, target) у таблиці журналу: дублікат неможливий навіть при повторному спрацюванні події OpenCart.
• API-ключ зашифрований у БД — sodium з HMAC-фолбеком, у відкритому вигляді не зберігається.
• Журнал синхронізації з постатусним записом по кожному замовленню і фрагментами запиту/відповіді API — зручно розбирати, чому конкретне замовлення не пішло.
• Зворотна синхронізація без петель: читає KeyCRM тільки на отримання, а під час запису історії замовлення глушить подію прямої синхронізації — назад у CRM нічого не відправляється. Кожен прогін пересканує 10-хвилинне перекриття, щоб не загубити граничні оновлення; час — в UTC.
• Адаптерна архітектура — мапер замовлень і диспетчер відокремлені від конкретної CRM, KeyCRM реалізована як адаптер.

Як встановити

1. Завантажте cc_crm.ocmod.zip через Розширення → Інсталятор в адмінці OpenCart. Для OpenCart 3.x — збірку cc_crm-oc3.ocmod.zip.
   Для OpenCart 2.3 візьміть збірку cc_crm-oc2.ocmod.zip. Штатний інсталятор 2.3 копіює файли лише по FTP, тож якщо FTP не налаштований — розпакуйте архів і залийте вміст теки upload/ у корінь магазину.
2. Перейдіть у Розширення → Модулі, знайдіть KeyCRM Sync і натисніть «Встановити».
3. Відкрийте налаштування модуля і вставте API-ключ з кабінету KeyCRM.
4. Увімкніть відправку і оберіть тригер: одразу при оформленні або при зміні статусу.
5. За потреби ввімкніть зворотну синхронізацію на вкладці «Зворотна синхронізація»: налаштуйте мапінг статусів (список статусів KeyCRM підвантажується прямо в адмінці) і додайте cron-задачі.
6. OpenCart 2.3 і 3.x: планувальника в цих версіях немає взагалі, тому обидві cron-адреси (черга повторних спроб і зворотна синхронізація) показані просто в налаштуваннях модуля — додайте їх у системний crontab. Поруч є поле «Cron-токен»: заповніть його, щоб адреси не міг смикати хтось сторонній.