OneBox Sync — CRM для OpenCart 2.3, 3.x і 4.x

OneBox Sync для OpenCart — модуль, який зв’язує магазин на OpenCart 2.3, 3.x або 4.x із OneBox OS: кожне нове замовлення автоматично стає процесом-замовленням у CRM разом із клієнтом, телефоном, адресою доставки та товарами. Замість ручного перенесення даних менеджер одразу бачить заявку в OneBox і працює з нею за вашим бізнес-процесом.

Модуль повністю безкоштовний, код відкритий. Репозиторій на GitHub: github.com/catcodestudio/opencart-onebox-sync. Без ключів, підписок і лімітів на замовлення.

Як це працює — крок за кроком

1. Покупець оформлює замовлення — модуль реагує на подію додавання історії замовлення, не втручаючись у checkout.
2. Модуль авторизується у вашому OneBox: отримує токен через POST /api/v2/token/get/ і надсилає замовлення через POST /api/v2/order/set/.
3. Товари прив’язуються до каталогу OneBox: назва, артикул (SKU/модель), кількість і ціна — каталожні продукти знаходяться або створюються автоматично, без дублів у каталозі. Доставка передається окремим рядком, тому сума процесу сходиться із сумою замовлення.
4. OneBox повертає ID процесу — він фіксується в журналі синхронізації; додатково передається externalid, тож повторне спрацювання не створить другий процес.
5. Невдалі відправки повторює cron-ретрай — замовлення, які не пішли з першої спроби, доїжджають у CRM автоматично.

Що під капотом

• Події OpenCart — модуль підписується на додавання історії замовлення (addHistory в OpenCart 4, addOrderHistory в 3.x і 2.3); файли ядра і теми не модифікуються.
• Ідемпотентність: upsert за externalid на боці OneBox плюс унікальний журнал синхронізації в БД магазину — ні дубльованих процесів, ні дубльованих товарів у каталозі.
• Мапінг товарів, оплати й доставки у поля процесу OneBox; необов’язкова маршрутизація workflowid/statusid/sourceid (порожньо = перший бізнес-процес автоматично).
• Cron-черга повторів для замовлень, які не вдалося відправити з першого разу: підбираються і невдалі відправки, і ті, що зависли в стані «в процесі» понад годину (наприклад, якщо PHP обірвався посеред запиту).
• Cron-токен — публічний URL повторів можна закрити спільним секретом: ...&token=<значення>. Штатний планувальник OpenCart 4 працює й без токена, порожнє поле лишає ендпоінт відкритим.
• API-пароль зберігається в БД у зашифрованому вигляді, а журнал синхронізації містить запит і відповідь API для діагностики.

Як встановити

1. У OneBox встановіть компонент «API v2» (1b.app → Додатки → API-сервіси) і задайте співробітнику логін та пароль (Користувачі і співробітники → Логін, пароль, права доступу).
2. Завантажте cc_onebox.ocmod.zip через Розширення → Інсталятор в адмінці OpenCart. Для OpenCart 3.0.2–3.0.5 беріть окрему збірку — cc_onebox-oc3.ocmod.zip (після встановлення оновіть модифікації: Розширення → Модифікації → кнопка «Оновити»).
3. Для OpenCart 2.3.0.0–2.3.0.2 беріть збірку cc_onebox-oc2.ocmod.zip. ⚠️ Штатний інсталятор 2.3 копіює файли лише по FTP: якщо FTP не налаштовано, розпакуйте архів і залийте вміст теки upload/ у корінь магазину, далі Розширення → Модулі → OneBox Sync → «Встановити».
4. У Розширення → Модулі знайдіть OneBox Sync, натисніть «Встановити» й відкрийте налаштування.
5. Вкажіть домен вашого OneBox, API-логін і API-пароль, натисніть «Перевірити з’єднання».
6. За потреби заповніть ID бізнес-процесу, етапу і джерела (можна лишити порожніми — модуль візьме перший бізнес-процес) та збережіть.
7. Оформіть тестове замовлення і перевірте процес у OneBox та рядок у журналі.
8. В OpenCart 3.x і 2.3 планувальника немає — рядок повторів додається в crontab хостингу вручну (типово раз на 15 хвилин):
   curl -s "https://SHOP/index.php?route=extension/module/cc_onebox_cron/retry&token=ТОКЕН" (у 3.x роут — extension/module/cc_onebox/cronRetry; готовий URL показано в налаштуваннях модуля)