Як передавати замовлення з OpenCart 3 в Elbuz готовим модулем

Що вміє модуль

• Передає замовлення одразу й після кожної зміни статусу — від оформлення, платіжного модуля чи менеджера в адмінці OpenCart.
• Переводить статуси сайту в статуси Elbuz — статус документа й статус оплати за вашою таблицею.
• Догружає старі замовлення — усі, змінені з обраної дати.
• Не губить замовлення, коли Elbuz недоступний — тримає їх у черзі й повторює відправку.
• Показує журнал відправок — що пішло, в який документ і чому не пройшло.
• Продовжує історію Elbuz Tunnel — замовлення лягають у ті самі документи.

Де це і хто має доступ

Скачати

elbuz_api_sync.ocmod.zip — OpenCart 3.0.x, PHP 7.1+ з curl

Модуль на сайті

Розширення → Розширення → Модулі → «Elbuz: синхронізація замовлень»

Ключ в Elbuz

Кабінет → Налаштування системи → «Інші налаштування» → «API та токени доступу»

Право доступу

співробітнику ключа — вікно замовлень і кнопка «Додати» в ньому

Де видно замовлення

вікно «Замовлення», джерело «API: назва ключа»

Модуль передає лише замовлення. Каталог він не передає: товари з сайту в Elbuz переносить Elbuz Tunnel.

Як встановити модуль на сайт

1. Скачайте архів elbuz_api_sync.ocmod.zip.
2. В адмінці OpenCart відкрийте «Розширення → Встановлення розширень» і завантажте архів кнопкою «Завантажити». Без доступу до інсталятора скопіюйте вміст папки upload з архіву в корінь сайту.
3. Відкрийте «Розширення → Розширення», у списку типів оберіть «Модулі».
4. У рядку «Elbuz: синхронізація замовлень» натисніть «Встановити» (зелений плюс), потім «Редагувати» (олівець).

Після встановлення модуль вимкнений і нічого не відправляє, доки ви не заповните підключення й не збережете його з «Статус» — «Увімкнено». Видалення модуля кнопкою «Видалити» прибирає його чергу й журнал.

Як видати модулю ключ в Elbuz

Модулю потрібен окремий ключ API v2. Його назва стане джерелом замовлень у списку, і за ключем Elbuz упізнає вже завантажені замовлення.

1. В Elbuz відкрийте «API та токени доступу» й натисніть «+».
2. У полі «Користувач» напишіть назву магазину, наприклад site_opencart.
3. У «Від імені співробітника» оберіть співробітника, якому відкрите вікно замовлень і дозволена кнопка «Додати».
4. Зніміть «Тільки для читання».
5. Перемкніть «Зміни даних» на «Робити самому». Перемкнути може лише група «Управління».
6. У «Запобіжник: змін на годину» поставте число з запасом: кожна відправка модуля — одна зміна, навіть коли в ній 100 замовлень.
7. Збережіть і скопіюйте ключ — він починається з elbz_.

1

Користувач

2

Зміни даних: Робити самому

3

Запобіжник: змін на годину

4

Тільки для читання

1. Користувач — назва ключа site_opencart; вона ж стає джерелом замовлень («API: site_opencart»).
2. Зміни даних — режим «Робити самому»: зміни через ключ виконуються одразу, без підтвердження в «Пульсі».
3. Запобіжник — ліміт 1000 змін на годину; після перевищення ключ сам повертається в режим «Питати».
4. Тільки для читання — позначка знята, тож ключ може створювати й змінювати замовлення.

Один ключ — один сайт. Однакові номери замовлень двох сайтів під одним ключем зіллються в один документ. Загальні правила ключів — у статті API v2.

Як підключити модуль до Elbuz

Де: модуль «Elbuz: синхронізація замовлень» → вкладка «Підключення».

1. «Статус» — «Увімкнено».
2. «Адреса API Elbuz» — адреса вашого акаунта з /api/v2 у кінці: https://ваш-домен.elbuz.com/api/v2. Адреса без https:// чи http:// не збережеться: «Адреса API має починатися з https:// або http://».
3. «Ключ API» — ключ, скопійований в Elbuz.
4. «ID шаблону Elbuz» залиште порожнім. Він потрібен лише для переходу з Elbuz Tunnel.
5. Натисніть «Перевірити з'єднання». Відповідь «З'єднання є. Отримано статусів документа: N, статусів оплати: M.» означає, що адреса й ключ правильні, а статуси Elbuz з'явилися на вкладці «Статуси».
6. Збережіть модуль синьою кнопкою з дискетою вгорі праворуч.

1

Статус

2

Адреса API Elbuz

3

Ключ API

4

ID шаблону Elbuz

5

Перевірити з'єднання

6

Зберегти

1. Статус — «Увімкнено»: без цього модуль нічого не відправляє.
2. Адреса API Elbuz — адреса акаунта з /api/v2 у кінці.
3. Ключ API — ключ із вікна «API та токени доступу», показується крапками.
4. ID шаблону Elbuz — порожнє; заповнюють лише при переході з Elbuz Tunnel.
5. Перевірити з'єднання — зверху зелене повідомлення з кількістю отриманих статусів Elbuz.
6. Зберегти — без збереження модуль не почне відправляти замовлення.

«Перевірити з'єднання» бере адресу й ключ прямо з форми, без збереження. Відправляти замовлення модуль почне лише після збереження. Помилка перевірки виглядає як «Немає з'єднання з Elbuz: …» з причиною — розбір у таблиці нижче.

Як зіставити статуси сайту зі статусами Elbuz

Де: вкладка «Статуси». Для кожного статусу OpenCart оберіть «Статус документа в Elbuz» і «Статус оплати в Elbuz». Список статусів Elbuz з'являється після «Перевірити з'єднання».

В OpenCart окремого статусу оплати немає: оплату показує той самий статус замовлення. Тому для статусів, у які сайт переводить оплачені замовлення, оберіть «Оплачено» в колонці оплати.

«— не змінювати —» означає, що цей статус сайту не міняє відповідний статус в Elbuz. Нове замовлення без зіставлення отримає статус за замовчуванням, «Новий». Якщо заповнено «ID шаблону Elbuz», для порожніх рядків діє зіставлення статусів шаблону.

1

Обробка → Оплачено

2

Очікування → Новий

3

Скасовано: оплату не змінювати

1. Обробка — сюди сайт переводить оплачене замовлення, тому в обох колонках «Оплачено».
2. Очікування — нове замовлення: статус «Новий», оплата «Чекання».
3. Скасовано — статус документа «Скасовано», статус оплати лишається, як був («— не змінювати —»).

Модуль відправляє замовлення щоразу, коли змінюється його статус. Чи перепише новий статус сайту той, що поставив менеджер в Elbuz, вирішують загальні правила: хто кого перезаписує. Позиції записуються лише при створенні документа.

Як відправити замовлення, які вже є на сайті

Нові замовлення модуль відправляє сам. Ті, що були на сайті до встановлення, відправте вручну.

Де: вкладка «Відправка».

1. У «Замовлення змінені з» оберіть дату. За замовчуванням — 30 днів тому.
2. Натисніть «Відправити». Модуль бере всі замовлення, змінені з цієї дати, крім незавершених кошиків без статусу, і шле пакетами по 100.
3. Не закривайте сторінку, доки біля кнопки не з'явиться «лишилось у черзі: 0». Рядок показує «Відправлено: N, помилок: M, лишилось у черзі: K».

Повторна відправка тих самих замовлень дублів не створює: вони оновлюються в уже створених документах. Тією самою кнопкою доганяють замовлення після збою — оберіть дату, з якої вони не дійшли.

Посилання для cron

Під кнопкою стоїть «Посилання для cron». Додайте його в планувальник хостингу на запуск раз на 5–15 хвилин, наприклад:

*/10 * * * * curl -s "https://ваш-сайт/index.php?route=extension/module/elbuz_api_sync/cron&key=…" >/dev/null

Cron відправляє те, що не пройшло одразу, — до 1000 замовлень за запуск. Без нього черга йде разом із наступним замовленням сайту: якщо замовлень уночі немає, затримане вчора дійде лише зранку. Посилання без правильного key відповідає 403 і нічого не відправляє.

1

Замовлення змінені з

2

Відправити

3

Посилання для cron

1. Замовлення змінені з — за замовчуванням 30 днів тому.
2. Відправити — шле всі замовлення, змінені з цієї дати, пакетами по 100.
3. Посилання для cron — для планувальника хостингу, раз на 5–15 хвилин; ключ у посиланні свій у кожного сайту.

Як перевірити, що замовлення доходять

1. Оформіть на сайті тестове замовлення.
2. У модулі відкрийте вкладку «Журнал». Замовлення має стояти в стані «відправлено» з результатом «створено». У колонці «Документ Elbuz» — ID документа в Elbuz, а не його номер у списку замовлень.
3. В Elbuz відкрийте вікно «Замовлення». Замовлення стоїть зверху з джерелом «API: назва ключа»; його номер на сайті записаний у документ окремим полем.
4. Змініть статус замовлення в адмінці OpenCart. У журналі з'явиться «оновлено», в Elbuz — статус за вашою таблицею зіставлення.

1

Номер замовлення на сайті

2

Результат

3

Документ Elbuz

1. Замовлення — номер на сайті, посилання відкриває замовлення в OpenCart.
2. Результат — «створено» для нового документа, «оновлено», коли замовлення вже було в Elbuz.
3. Документ Elbuz — внутрішній ID документа в Elbuz, не номер замовлення в списку.

Журнал показує 30 останніх замовлень. Жовті рядки ще в черзі, червоні — не відправлені; причина — у колонці «Повідомлення». Номер у колонці «Замовлення» відкриває замовлення в OpenCart.

1

35971: оплачено на сайті

2

35973: нове, не оплачене

1. 35971 — замовлення, оплачене на сайті: в Elbuz його оплата «Оплачено».
2. 35973 — нове замовлення: оплата «Чекання».

Що буде, якщо Elbuz не відповів

Оформлення замовлення на сайті модуль не гальмує й не ламає. На відповідь Elbuz він чекає до 5 секунд, а помилку записує в журнал і лишає замовлення в черзі.

Замовлення зі станом «не відправлено» піде знову, коли зміниться його статус на сайті або коли ви натиснете «Відправити» з датою, що його охоплює. Усі повтори беруть поточні дані замовлення.

Як перейти з Elbuz Tunnel без дублів

Замовлення, які вже забрав тунель, записані з джерелом його шаблону. Щоб модуль оновлював саме їх, а не заводив нові документи, вкажіть номер цього шаблону.

1. В Elbuz відкрийте Довідники → Операції → Завантаження даних. Номер шаблону тунелю — в останній колонці списку шаблонів, «ID».
2. У модулі на вкладці «Підключення» впишіть його в «ID шаблону Elbuz» і збережіть.
3. Змініть статус одного старого замовлення на сайті. У журналі модуля має бути «оновлено», а не «створено».
4. У шаблоні тунелю зніміть галочку «Замовлення», щоб замовлення не приходили двома шляхами. Каталог тунель забирає й далі.

З «ID шаблону Elbuz» діє зіставлення статусів шаблону: його кнопки «Статуси замовлення» й «Статуси оплати». Рядок, заповнений на вкладці «Статуси» модуля, важливіший за шаблон. Шаблон має бути видимим співробітнику ключа, інакше відправка поверне 422 з "template_id": "not found".

Сценарії

Новий магазин: замовлення мають з'являтися в Elbuz одразу

Задача: менеджер працює в Elbuz і не має чекати розкладу, щоб побачити замовлення сайту.

Що зробити: окремий ключ у режимі «Робити самому»; у модулі — «Статус» «Увімкнено», адреса, ключ, «Перевірити з'єднання», зіставлення статусів, збереження; «Відправити» з датою початку роботи сайту; посилання для cron у планувальник раз на 10 хвилин.

Що вийде: кожне нове замовлення за кілька секунд стає документом «Замовлення покупця» з джерелом «API: назва ключа», зміна статусу на сайті оновлює той самий документ.

Оплата карткою на сайті має позначатися в Elbuz

Задача: менеджер не повинен звіряти оплати з платіжною системою вручну.

Що зробити: на вкладці «Статуси» для статусу, який ставить платіжний модуль після оплати, оберіть «Оплачено» в обох колонках.

Що вийде: щойно платіжний модуль змінить статус, замовлення в Elbuz отримає статус оплати «Оплачено». Залишок і резерв не зміняться, доки документ не проведено.

Каталог іде тунелем, замовлення — модулем

Задача: тунель роками забирав і каталог, і замовлення; замовлення мають приходити одразу, а не з наступним прогоном.

Що зробити: перехід з тунелю: «ID шаблону Elbuz» шаблону тунелю, перевірка на старому замовленні, потім зняти в шаблоні галочку «Замовлення».

Що вийде: старі замовлення оновлюються в тих самих документах, нові додаються туди ж. Тунель далі оновлює каталог за своїм розкладом.

Що робити, коли замовлення не приходять

Часті запитання

Модуль передає в Elbuz товари й ціни?

Ні, лише замовлення. Каталог із сайту забирає Elbuz Tunnel, а з Elbuz на сайт — вивантаження через тунель.

У якій валюті приходять суми?

У валюті замовлення, тобто так, як платив покупець. Ціна позиції — з податком, доставка — окремою сумою.

Покупець додав товар у замовлення на сайті — чи зміниться документ?

Ні. Позиції записуються лише при створенні документа; змінений склад переносять у документ вручну. Повторні відправки, поки документ не проведено, оновлюють статус, оплату й спосіб доставки; адреса, суми й покупець лишаються з першої відправки.

Чи працює модуль на OpenCart 2 або 4?

Ні, модуль для OpenCart 3.0.x. Із сайту на OpenCart 2 замовлення забирає тунель.

Чи спише замовлення з модуля залишок?

Ні. Документ створюється непроведеним, а залишок і резерв Elbuz рахує лише за проведеними документами.

Що буде, якщо видалити замовлення на сайті?

Документ в Elbuz лишиться: модуль документи не видаляє. Переведіть замовлення на сайті в статус, зіставлений зі «Скасовано», до видалення, або видаліть документ в Elbuz.

Суміжні теми

• Якщо треба зрозуміти, чий статус лишиться після відправки, — хто кого перезаписує.
• Якщо сайт не на OpenCart 3 і модуль пишете самі — замовлення через API v2.
• Якщо з сайту треба забрати ще й каталог — перенесення каталогу через Elbuz Tunnel.
• Якщо треба, щоб інша система дізнавалася про зміну замовлення, — вебхуки API v2.