Передача замовлень з 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, історію та захист від дублів.