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.