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

KeyCRM Sync для OpenCart 4 — модуль двосторонньої синхронізації магазину з 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.

Скільки коштує

Безкоштовно, код відкритий. Завантажуйте з GitHub або кнопкою на цій сторінці — без тарифів, лімітів замовлень і прихованих платежів.

Технічні вимоги

• OpenCart 4.0.2 – 4.1.x
• API-ключ KeyCRM — кабінет KeyCRM → Налаштування → Загальні → API-ключ
• Cron на хостингу — для черги повторних спроб і зворотної синхронізації (пряма відправка замовлень працює і без крона)

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

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

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

1. Завантажте cc_crm.ocmod.zip через Розширення → Інсталятор в адмінці OpenCart.
2. Перейдіть у Розширення → Модулі, знайдіть KeyCRM Sync і натисніть «Встановити».
3. Відкрийте налаштування модуля і вставте API-ключ з кабінету KeyCRM.
4. Увімкніть відправку і оберіть тригер: одразу при оформленні або при зміні статусу.
5. За потреби ввімкніть зворотну синхронізацію на вкладці «Reverse sync»: налаштуйте мапінг статусів (список статусів KeyCRM підвантажується прямо в адмінці) і додайте cron-задачі.

Історія версій

1.1.0 — липень 2026

Зворотна синхронізація KeyCRM → OpenCart: статуси замовлень за налаштовуваним мапінгом, номери ТТН в історію замовлення, опційне оновлення залишків за SKU (з урахуванням резервів KeyCRM). Виправлено передачу вартості доставки (shipping_price), тригер подій моделі OC4 і admin-AJAX-посилання.

1.0.0 — липень 2026

Перший реліз: відправка замовлень у KeyCRM при оформленні або зміні статусу, ідемпотентність без дублів, черга повторних спроб через cron, мапер полів і оплат, шифрування API-ключа, журнал синхронізації, автостворення джерела в CRM.