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. При необходимости включите обратную синхронизацию на вкладке «Зворотна синхронізація» (в английском интерфейсе — «Reverse sync»): настройте маппинг статусов (список статусов KeyCRM подгружается прямо в админке) и добавьте cron-задачи.
6. OpenCart 2.3 и 3.x: планировщика в этих версиях нет вообще, поэтому обе cron-адреса (очередь повторных попыток и обратная синхронизация) показаны просто в настройках модуля — добавьте их в системный crontab. Рядом есть поле «Cron-токен»: заполните его, чтобы адреса не мог дёргать кто-то посторонний.