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.

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

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

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

• OpenCart 4 4.0.2 – 4.1.x, PHP 7.4+
• OpenCart 3 3.0.0 – 3.0.5, PHP 5.6 – 8.2 — окрема збірка cc_crm-oc3.ocmod.zip
• OpenCart 2.3 2.3.0.0 – 2.3.0.2, PHP 5.6+ — окрема збірка cc_crm-oc2.ocmod.zip
• 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.
   Для OpenCart 2.3 візьміть збірку cc_crm-oc2.ocmod.zip. Штатний інсталятор 2.3 копіює файли лише по FTP, тож якщо FTP не налаштований — розпакуйте архів і залийте вміст теки upload/ у корінь магазину.
2. Перейдіть у Розширення → Модулі, знайдіть KeyCRM Sync і натисніть «Встановити».
3. Відкрийте налаштування модуля і вставте API-ключ з кабінету KeyCRM.
4. Увімкніть відправку і оберіть тригер: одразу при оформленні або при зміні статусу.
5. За потреби ввімкніть зворотну синхронізацію на вкладці «Reverse sync»: налаштуйте мапінг статусів (список статусів KeyCRM підвантажується прямо в адмінці) і додайте cron-задачі.
6. OpenCart 2.3 і 3.x: планувальника в цих версіях немає взагалі, тому обидві cron-адреси (черга повторних спроб і зворотна синхронізація) показані просто в налаштуваннях модуля — додайте їх у системний crontab. Поруч є поле «Cron-токен»: заповніть його, щоб адреси не міг смикати хтось сторонній.

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

1.0.1 (OpenCart 2.3)

Cron-токен зі спецсимволом (&, лапки) більше не відкидається: у 2.3 Request::clean() проганяє htmlspecialchars і по $_GET, тому такий токен прилітав у гейт сутністю й ніколи не збігався — рядок crontab отримував 403 назавжди. Тепер значення декодується один раз, як і при збереженні в адмінці.

1.1.4 — серпень 2026

Реліз фікса валюти: суми в KeyCRM надсилаються у валюті замовлення (курс замовлення), а не в базовій валюті магазину.

1.1.3 (OpenCart 3) — 11 серпня 2026

3.x-збірку підтягнуто до рівня 2.3 і 4.x. У CRM тепер їде сума в тій валюті, якою реально платив покупець, а не в базовій валюті магазину. Зʼявився cron-токен для обох адрес — без нього їх міг смикати будь-хто (поле порожнє за замовчуванням, тож наявні рядки в crontab продовжують працювати). Журнал синхронізації винесено в окремий екран з пагінацією. API-ключ і префікс UUID зі знаком & більше не зберігаються HTML-сутністю. Оновлення — просто перезалити архів: налаштування, подія і журнал лишаються на місці.

1.0.0 (OpenCart 2.3) — 9 серпня 2026

Окрема збірка під OpenCart 2.3: та сама синхронізація замовлень, журнал, черга повторних спроб і зворотна синхронізація, але на PHP 5.6-сумісному коді й шаблонах Bootstrap 3. Замість планувальника (його в 2.3 немає) — дві cron-адреси з власним токеном. Заразом виправлено суми: у CRM тепер їде та валюта, якою реально платив покупець, а не базова валюта магазину.

1.1.3 — 5 серпня 2026

Виправлено сумісність із PHP 7.4: обробник події був оголошений із типом mixed (він існує лише з PHP 8.0), тому на 7.4 синхронізація не спрацьовувала взагалі. Прибрано залежність від mbstring у журналі та зворотній синхронізації. Додано префікс UUID магазину — якщо кілька магазинів шлють замовлення в один акаунт KeyCRM, їхні замовлення з однаковим номером більше не конфліктують (CRM віддавала на це HTTP 500). Заразом у збірку повернувся файл поліфілу, без якого модуль не встановлювався.

1.1.1–1.1.2 — липень 2026

Виправлено подію замовлення на OpenCart 4.0.2.x (розділювач методу) і перевірку дубля ТТН на драйвері бази PDO.

1.1.0 — липень 2026

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

1.0.0 — липень 2026

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