Передача заказов с OpenCart в KeyCRM – базовый сценарий интеграции, но именно в нем чаще всего теряются опции товаров, способ оплаты, отделение доставки или история статусов. Официальная инструкция keyCRM описывает базовое подключение, а на практике надежный обмен должен не просто создать карту в CRM, а сохранить достаточное количество данных для обработки заказа и безопасно пережить повторное событие.
Как выглядит поток заказа
- Покупатель подтверждает заказ в OpenCart.
- Модуль получает событие после фактической записи в базе.
- Данные нормализуются: контакты, позиции, настройки, суммы, доставка, оплата и источник.
- Модуль проверяет, связан ли этот заказ с KeyCRM.
- Через API создается или обновляется карта заказа в CRM.
- Локально сохраняется связь между ID OpenCart, источником и UUID/ID KeyCRM.
- Последующие изменения статуса обрабатываются в соответствии с настроенным направлением.
Лучше всего запускать обмен сразу после создания заказа, но не блокировать страницу успешного оформления длинным API-запросом. Если CRM временно недоступна, операция должна оставаться в журнале или очереди для повторного запуска.
Какие данные передавать из OpenCart в KeyCRM
| Группа | Минимальный набор | На что обратить внимание |
|---|---|---|
| Идентификация | ID заказа, источник, дата | ID должно быть уникальным в пределах конкретного магазина. |
| Клиент | Имя, телефон, email | Телефон нормализуйте в один формат, не создавайте дубликаты клиентов. |
| Товары | SKU, название, количество, цена | Опции передавайте по отдельности; сумма должна соответствовать фактической валюте заказа. |
| Доставка | Способ, стоимость, адрес/отделение | Кастомные поля OpenCart нуждаются в явном картенге. |
| Оплата | Метод и текущее состояние | Название метода и подтверждение платежа – разные данные. |
| Маркетинг | UTM, реферер, промокод | Штатный коннектор может не передавать кастомные маркетинговые поля. |
Практическое правило: все, что менеджер использует для подтверждения, комплектации, доставки или аналитики должно или передаваться в стандартное поле KeyCRM, или иметь задокументированное кастомное поле.
Мапинг статусов OpenCart и KeyCRM
В OpenCart статус является частью истории заказа, а в KeyCRM он может соответствовать этапу воронки. Автоматически приравнивать названия небезопасно: «Обработка» в одном магазине может означать новый заказ, а в другом уже собранную посылку.
Составьте таблицу направлений до запуска:
| Событие | OpenCart | KeyCRM | Направление |
|---|---|---|---|
| Новый заказ | Pending | Новое | OpenCart → KeyCRM |
| Подтверждено менеджером | Processing | Подтверждено | KeyCRM → OpenCart |
| Передано в доставку | Shipped | Отправлено | KeyCRM → OpenCart |
| Упразднено | Canceled | Упразднено | Выбрано одно главное направление |
Для каждой пары определите, кто является источником истины. Если разрешить одновременное обновление без правил, две системы могут бесконечно перебрасывать статусы или возвращать старое значение.
Как интеграция защищает от дублей
Повторный webhook, обновление страницы, таймаут ответа или ручной запуск не должны создавать второй заказ. Для этого операция должна быть идемпотентной: модуль ищет уже сохранившуюся связь по ID магазину и UUID/ID источнику и выполняет обновление вместо повторного создания.
Расширенный модуль Build Zone сохраняет связи заказов, находит их по UUID, не создает дубликаты и сохраняет историю изменения статусов. В админ-панели доступны инструменты проверки и очистки служебных связей – их применяют при диагностике, а не как регулярную «оптимизацию».
События, webhook, CRON и ручной запуск
Новые заказы OpenCart целесообразно отправлять сразу. Изменения со стороны KeyCRM могут приходить через исходящие webhook-ы: изменение статуса, обновление заказа или другое поддерживаемое событие. Массовые перепроверки и обслуживание удобнее выполнять через CRON.
- Событие OpenCart — быстро передает новый заказ.
- Webhook KeyCRM – сообщает магазин об изменениях со стороны CRM.
- CRON выполняет плановые операции и повторную синхронизацию.
- Ручной запуск необходим для контрольного теста и технического обслуживания.
Контрольный сценарий перед запуском
- Один заказ с простым товаром.
- Один заказ с обязательной опцией и скидкой.
- Доставка с адресом или отделением и ненулевой стоимостью.
- Онлайн-оплата и наложенный платеж как разные сценарии.
- Повторная отправка того же события без дубликата.
- Изменение статуса в разрешенном направлении.
- Временная ошибка API и обработка после восстановления.
Что смотреть, если заказ не передается
Начните с журнала модуля: время запроса, endpoint, код HTTP и текст ошибки. 401 обычно означает проблему с API-ключом; 422 - неправильное или неполное поле; 429 - превышение лимита API keyCRM; 5xx — временная ошибка сервиса или сервера. В production-журнале не должны отображаться полный Bearer token или персональные данные покупателя без надобности.
Далее проверьте, сработало ли событие OpenCart, активен ли правильный источник KeyCRM, совпадает ли картенг способа доставки и нет ли конфликта с модификатором оформления заказа. Пошаговая первичная настройка описана в инструкции «Как подключить KeyCRM к OpenCart».
Нужна ли стабильная передача заказов?
Модуль Build Zone поддерживает автоматическую передачу и импорт заказов, двусторонние статусы, источники KeyCRM, UUID, историю и защиту от дублей.