VibeFox Melhor Envio for OpenCart — Допомога

Вимоги

OpenCart: 3.0.x (перевірено на 3.0.5.0) або 4.0.2 та новіші (перевірено на 4.1.0.3).

PHP: 8.0 або новіша версія.

Обліковий запис Melhor Envio (лише для розрахунків у реальному часі): розрахунки в реальному часі потребують токен доступу. В обліковому записі Melhor Envio відкрийте сторінку токенів (melhorenvio.com.br/painel/gerenciar/tokens) і створіть токен з дозволом «shipping-calculate». Для тестування створіть токен у пісочниці Melhor Envio (sandbox.melhorenvio.com.br). Токени для робочого середовища та пісочниці різні. Кнопки «підключити» немає: ви вставляєте токен у налаштування розширення. Без токена спосіб доставки використовує резервні ціни.

Ліцензійний ключ VibeFox: купується на vibefox.net. Один ключ працює на одному домені.

Встановлення

Завантаження — це один zip-файл із пакетами для обох версій OpenCart. Розпакуйте його на своєму комп'ютері. Він містить README.txt, пакет для OpenCart 3 vfd_melhor_envio-oc3-(version).ocmod.zip і пакет для OpenCart 4 vfd_melhor_envio.ocmod.zip. Встановлюйте лише пакет для вашої версії OpenCart. Ліцензійний ключ однаковий для обох версій.

OpenCart 3

1. В адмін-панелі перейдіть до Extensions > Installer, натисніть Upload і виберіть файл vfd_melhor_envio-oc3-(version).ocmod.zip. Розширення не додає модифікацій OCMOD, тому оновлювати Extensions > Modifications не потрібно. Замість інсталятора можна скопіювати вміст папки upload цього пакета в кореневу папку вашого магазину.

2. Перейдіть до Extensions > Extensions і виберіть тип розширень Shipping. Знайдіть VibeFox Melhor Envio і натисніть Install (зелена кнопка +).

3. Натисніть Edit (кнопка з олівцем), щоб відкрити сторінку налаштувань.

4. Введіть ліцензійний ключ VibeFox у License key у блоці ліцензії у верхній частині сторінки Edit і натисніть Activate (див. Ліцензійний ключ).

5. Вставте токен доступу, контактну e-mail адресу та CEP відправлення. Якщо валюта за замовчуванням вашого магазину не BRL, вкажіть BRL exchange rate. За бажанням заповніть таблицю резервних цін (наприклад, для Бразилії) або вкажіть резервну вартість. Увімкніть Enable Melhor Envio shipping і натисніть Save.

OpenCart 4

1. В адмін-панелі перейдіть до Extensions > Installer, натисніть Upload і виберіть файл vfd_melhor_envio.ocmod.zip. Не перейменовуйте файл: OpenCart 4 бере код розширення з назви файлу, і перейменований пакет не працює.

2. Пакет з'являється в списку встановлених розширень на тій самій сторінці. Натисніть Install (зелена кнопка +) поруч із ним.

3. Перейдіть до Extensions > Extensions і виберіть тип розширень Shipping. Знайдіть VibeFox Melhor Envio, натисніть Install (зелена кнопка +), а потім Edit (кнопка з олівцем).

4. Введіть ліцензійний ключ і налаштування так само, як у кроках 4 і 5 для OpenCart 3. Сторінка налаштувань і її поля однакові в обох версіях.

Після встановлення спосіб доставки вимкнений, доки ви не увімкнете Enable Melhor Envio shipping і не збережете налаштування. Якщо ви встановлюєте розширення повторно після видалення, використовуються збережені налаштування.

Налаштування

Усі налаштування розташовані на сторінці розширення: Extensions > Extensions > Shipping > VibeFox Melhor Envio > Edit. Розділи перелічено ліворуч. Одна кнопка Save зберігає всю сторінку без перезавантаження. Кожне збереження також очищує кеш розрахунків Melhor Envio та останню помилку API. Зберігати налаштування можуть лише адміністратори з правом змінювати це розширення.

Попередження у верхній частині сторінки (і після кожного збереження) показують неповне налаштування: порожній CEP відправлення або такий, що не складається з 8 цифр, відсутня контактна e-mail адреса, відсутній курс BRL, немає токена і немає резервної ціни (тоді спосіб доставки ніколи не показується), остання помилка API Melhor Envio з датою (коли токен збережено), або магазин без класу ваги «kg» чи класу довжини «cm» (тоді одиниці переводяться за назвою, а невідомі одиниці вважаються кг або см). Якщо Name порожнє, надто довге або містить один із символів < > ; = # { }, у числовому полі введено щось, що не є числом від 0 і більше, Min weight більше за Max weight, або Default product size не має вигляду довжина x ширина x висота, сторінка показує помилку і нічого не зберігається.

Загальні

Налаштування застосовуються до всіх геозон. Спосіб можна обмежити геозоною в Availability. Ціна завжди береться з розширення.

Enable Melhor Envio shipping: показує або приховує Melhor Envio під час оформлення замовлення. За замовчуванням: off.

Name: назва способу доставки, яку покупці бачать у кошику та під час оформлення замовлення. За замовчуванням: Melhor Envio. Обов'язкове поле, не більше 64 символів.

Sort order: місце Melhor Envio серед способів доставки під час оформлення замовлення. Ціле число.

API Melhor Envio

Access token: токен обраного нижче середовища. Він надсилається до Melhor Envio як Bearer-токен. Після збереження поле залишається порожнім і показує A token is saved — leave empty to keep it. Вводьте новий токен, лише якщо хочете його змінити. Щоб видалити збережений токен, позначте Remove the saved token і збережіть. Токен ніколи не записується в журнал.

Sandbox: використовуйте пісочницю Melhor Envio (sandbox.melhorenvio.com.br) для тестів. Із нею використовуйте токен пісочниці. За замовчуванням: off.

Contact e-mail: технічна контактна e-mail адреса, яка передається в Melhor Envio в заголовку User-Agent кожного запиту, наприклад tech@example.com. Melhor Envio вимагає її від кожної інтеграції. Недійсна адреса не зберігається, і про це виводиться повідомлення.

Origin CEP: CEP (8 цифр), з якого відправляються посилки, наприклад 01310-100. В OpenCart немає поштового індексу магазину, тому для розрахунків у реальному часі потрібне це поле. CEP, що не складається з 8 цифр, зберігається з повідомленням, але розрахунки не запитуються.

Services: необов'язковий список ID послуг Melhor Envio через кому для розрахунку, наприклад 1 = Correios PAC, 2 = Correios SEDEX, 17 = Correios Mini Envios, 3 = Jadlog .Package, 4 = Jadlog .Com. Залиште порожнім, щоб розраховувати всі послуги облікового запису.

Quotes at checkout: як показуються розрахунки.

Delivery time: показувати строк доставки Melhor Envio поруч із назвою, наприклад «(3-5 business days)». За замовчуванням: on.

Declared value: оголошувати вартість товарів (страхування) в розрахунках. Коли вимкнено, розрахунки робляться без оголошеної вартості: дешевше, але посилки не застраховані. За замовчуванням: on.

BRL exchange rate: Melhor Envio розраховує вартість у бразильських реалах. Потрібно лише тоді, коли валюта за замовчуванням вашого магазину не BRL: введіть ціну 1 BRL у вашій валюті за замовчуванням, наприклад 0.17. Без нього розрахунки в реальному часі не використовуються. Значення має бути більшим за 0. Оголошена вартість переводиться в BRL за тим самим курсом. Якщо валюта за замовчуванням — BRL, поле повідомляє, що ціни Melhor Envio використовуються без змін.

Default product weight (kg): використовується для товарів без ваги, як у розрахунках, так і для обмежень ваги. Має бути більшим за 0. За замовчуванням: 0.3.

Default product size (cm): довжина x ширина x висота, використовується для товарів без розмірів. За замовчуванням: 16x11x5.

Резервні ціни (у валюті за замовчуванням вашого магазину)

Резервні ціни використовуються, коли немає токена, відсутній CEP призначення або API не повертає розрахунок (помилка, тайм-аут, відсутність покриття).

Fallback price table: ціна за країною та вагою кошика, без податку. Натисніть Add country, щоб додати рядок (новий рядок починається з Бразилії), і кнопку видалення, щоб прибрати рядок. Виберіть * Any country для кожної країни без власного рядка. У кожному рядку є Price та колонки ваги: XS до 1 кг, S від 1 до 2 кг, M від 2 до 3 кг, L від 3 до 5 кг і XL понад 5 кг. Порожня колонка або 0 використовує Price, а Price 0 означає безкоштовну доставку. Приймаються як «9.99», так і «9,99». Значення, що не є числами, повідомляються після збереження й ігноруються. Рядки без жодної ціни видаляються.

Fallback cost: використовується, коли в таблиці теж немає ціни. Залиште порожнім, щоб приховати спосіб доставки в такому разі.

Fallback calculation: Per order (за замовчуванням) бере резервну ціну один раз. Per item (each item priced by its own weight x quantity) шукає резервну ціну для ваги кожного товару (вагу за замовчуванням, якщо її немає) і множить її на кількість. Це стосується лише резервних цін. Розрахунки Melhor Envio вже включають усі товари.

Доступність

Min weight (kg): приховує спосіб доставки, коли кошик важить менше. 0 означає без обмеження (за замовчуванням).

Max weight (kg): приховує спосіб доставки, коли кошик важить більше. За замовчуванням: 30. 0 означає без обмеження. Порожнє поле означає 30 кг, або без обмеження, якщо увімкнено Ignore shipping zones.

Minimum subtotal: показує спосіб доставки, лише якщо проміжна сума кошика (товари, що потребують доставки, після купона, до податку) становить принаймні цю суму. Залиште порожнім, щоб показувати його завжди.

Free shipping from: проміжна сума кошика, починаючи з якої доставка безкоштовна. За варіанту «один на послугу» безкоштовною стає лише найдешевша послуга. Швидші послуги зберігають свою ціну. Залиште порожнім, щоб вимкнути.

Tax class: клас податку, що додається до вартості доставки, або No tax (за замовчуванням). Ціни Melhor Envio — остаточні тарифи перевізників. Виберіть No tax, якщо OpenCart не повинен додавати до них податок.

Geo zone: пропонувати Melhor Envio лише для адрес у цій геозоні. All zones (за замовчуванням) означає без обмеження. Геозони керуються в System > Localisation > Geo Zones. Геозона не перевіряється, коли увімкнено Ignore shipping zones.

Доступність без зон доставки

Зазвичай спосіб пропонується в геозоні, вибраній у Availability (у всіх зонах, якщо жодну не вибрано).

Ignore shipping zones: пропонувати спосіб для країн, перелічених нижче, незалежно від вибраної геозони. У цьому режимі геозона не перевіряється.

Countries: країни призначення для цього режиму. Залиште порожнім для всіх країн. Це поле використовується лише коли увімкнено Ignore shipping zones.

Додатково

Debug log: записує запити до API та розрахунок тарифів у storage/logs/vfd_menv_debug.log.php (в OpenCart 4 — system/storage/logs/vfd_menv_debug.log.php). Файл не можна прочитати з веб-браузера. Помилки API записуються завжди, навіть коли ця опція вимкнена. Токен ніколи не записується, а CEP покупця скорочується до перших 5 цифр. Коли файл досягає 5 МБ, його переносять до vfd_menv_debug.old.log.php і починають новий журнал.

Log: показує розмір і останні записи журналу налагодження. Натисніть Clear log, щоб очистити його.

Remove data on uninstall: коли увімкнено, видалення розширення також видаляє всі його налаштування та журнал. Коли вимкнено (за замовчуванням), вони зберігаються для повторного встановлення. Кеш розрахунків завжди видаляється. Послуги, збережені із замовленнями, є історією замовлень і зберігаються.

Імпорт / Експорт

Export: натисніть Download JSON, щоб зберегти налаштування у файл JSON. Токен доступу не експортується.

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

Як це працює під час оформлення замовлення

Коли OpenCart показує способи доставки, він запитує у розширення ціну Melhor Envio. Якщо встановлено Geo zone і адреса знаходиться за її межами, Melhor Envio не пропонується. З Ignore shipping zones геозона не перевіряється: Melhor Envio пропонується лише тоді, коли країна входить до Countries (або Countries порожній). Враховуються лише товари, у яких Requires Shipping встановлено в Yes: інші товари не додають ваги й не входять до проміжної суми. Далі розширення перевіряє вагу кошика та мінімальну проміжну суму.

Для адреси доставки в Бразилії з CEP з 8 цифр розширення надсилає до Melhor Envio CEP відправлення та призначення, а також кожен товар, що підлягає доставці, з його вагою, розмірами, кількістю та оголошеною вартістю, плюс список послуг, якщо ви його задали. Поле Model товару передається як ID товару. Послуги з помилкою або без ціни пропускаються. Розрахунки переводяться у валюту за замовчуванням, округлюються до її десяткових знаків, сортуються за ціною і показуються у валюті покупця з податком обраного Tax class. Якщо діє безкоштовна доставка, найдешевша послуга коштує 0.

За One option - the cheapest service покупець бачить один варіант, наприклад Melhor Envio (6-7 business days). За One option per service покупець бачить варіант для кожної послуги, наприклад Melhor Envio: Correios SEDEX (1-2 business days). Строк доставки додається, лише якщо увімкнено Delivery time.

Кожен розрахунок кешується на 1 годину, тож той самий кошик не викликає новий запит. Невдалий виклик запам'ятовується на 5 хвилин, щоб збій API не сповільнював кожне оновлення оформлення замовлення. Тайм-аут API — 12 секунд.

Якщо немає токена, адреса знаходиться поза Бразилією або ще не має дійсного CEP, бракує курсу BRL, або Melhor Envio повертає помилку чи жодної послуги для маршруту, використовуються резервні ціни: рядок країни (або рядок *, якщо у країни немає власного рядка), інакше резервна вартість. Такий варіант називається просто так, як вказано в Name. Якщо діє безкоштовна доставка, спосіб показується безкоштовно, навіть без ціни. Якщо ціни немає взагалі, спосіб доставки приховується. Покупець ніколи не бачить помилку API. Причина записується в журнал.

На OpenCart 4 покупець натискає Choose у блоці способу доставки на сторінці оформлення замовлення і вибирає варіант Melhor Envio у вікні Shipping method options. Варіанти та ціни такі самі, як в OpenCart 3.

Розширення лише розраховує ціни. Воно не купує й не створює етикетки, не додає відправлення до кошика Melhor Envio, не відстежує посилки, не планує забір і не передає дані накладної (NF-e). Воно не пропонує вибір агенцій перевізників (пунктів здачі). Керуйте відправленнями в панелі Melhor Envio. Melhor Envio відправляє лише в межах Бразилії. Інші країни отримують лише резервні ціни.

Замовлення

OpenCart зберігає назву обраного варіанта як спосіб доставки замовлення, тож послуга та строк доставки з'являються в електронних листах про замовлення, в обліковому записі покупця та в розділі Sales > Orders.

Коли замовлення оформлюється з розрахунком у реальному часі, розширення також зберігає послугу Melhor Envio точно такою, якою її бачив покупець на кроці доставки, без нового запиту. Сторінка замовлення в адмін-панелі в розділі Sales > Orders показує блок Melhor Envio з Melhor Envio service, Service ID і Delivery estimate, щоб ви знали, яку послугу купити в Melhor Envio. Покупець бачить Melhor Envio service і Delivery estimate на сторінці замовлення у своєму обліковому записі. У замовлень, оформлених із резервною ціною, послуги немає. Наявні замовлення не змінюються.

На OpenCart 4 блок Melhor Envio показується над History. OpenCart 4 зберігає одне замовлення для оформлення і оновлює його щоразу, коли покупець підтверджує знову: збережена послуга оновлюється разом із ним, а видаляється, коли покупець переходить до іншого способу доставки або замовлення отримує резервну ціну.

Ліцензійний ключ

Розширення працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox Melhor Envio є першим блоком на Extensions > Extensions > Shipping > VibeFox Melhor Envio > Edit, над налаштуваннями. Введіть ключ у License key і натисніть Activate. Після цього блок показує ключ у замаскованому вигляді, статус (наприклад, дату, до якої ліцензія активна, і ваш домен) і кнопки Check now для повторної перевірки статусу, Change key для введення іншого ключа та Remove key для видалення ключа з цього магазину. Нижче є рядок Product: opencart-shipping-melhor-envio і посилання Manage licenses and domains in your account, яке відкриває ваш обліковий запис vibefox.net. Змінювати ключ можуть лише адміністратори з правом Modify для розширення. Тексти блоку відповідають мові адмін-панелі (включено англійську та російську).

Якщо ключ не приймається, блок пояснює причину, наприклад Key not found, This key belongs to another product, Domain limit reached або License expired on з датою. Після зміни адреси магазину або після звільнення слота домену в обліковому записі натисніть Check now. Якщо сервер ліцензій недоступний, розширення продовжує працювати за останнім відомим статусом.

Один ключ працює на одному домені: адреса магазину з конфігурації OpenCart. Видалення ключа з магазину не звільняє його слот домену. Звільніть слот у своєму обліковому записі vibefox.net.

Без активного ключа спосіб доставки Melhor Envio не показується покупцям під час оформлення замовлення, і розрахунок вартості не виконується. Адміністратор, який увійшов в адмін-панель у тому самому браузері, усе ще бачить спосіб доставки в магазині, позначений як (unlicensed — visible to admins only), тож ви можете налаштувати та протестувати розширення до купівлі ключа. На OpenCart 4 такого попереднього перегляду немає: магазин не бачить вхід адміністратора, тому без активного ключа спосіб доставки приховано для всіх. Після того як ви один раз відкрили сторінку Edit, на адмін-панелі Dashboard з'являється нагадування. Закрийте його кнопкою ×, щоб приховати на 7 днів. Наявні замовлення не змінюються.

Коли ліцензія спливає, розширення продовжує працювати, але для оновлень і підтримки потрібне продовження. Статус автоматично перевіряється знову, коли ви відкриваєте адмін-панель Dashboard або сторінку Edit: раз на добу протягом перших 14 днів після введення ключа, далі раз на тиждень. Cron-завдання не потрібне. Видалення розширення завжди видаляє ліцензійний ключ і статус ліцензії.

Усунення несправностей

Melhor Envio не з'являється під час оформлення замовлення: перевірте, що ліцензія активна і Enable Melhor Envio shipping увімкнено. Перевірте Geo zone або увімкніть Ignore shipping zones і перевірте Countries. Перегляньте попередження у верхній частині сторінки розширення, обмеження ваги та Minimum subtotal. Без токена чи розрахунку способу доставки потрібна резервна ціна: рядок у Fallback price table або Fallback cost. Перевірте, що в товарів Requires Shipping встановлено в Yes.

Показуються лише резервні ціни: увімкніть Debug log, перезавантажте оформлення замовлення та подивіться поле Log на сторінці розширення. Типові причини: немає токена, CEP відправлення не з 8 цифр, немає BRL exchange rate за валюти за замовчуванням, відмінної від BRL, ще не вказано CEP призначення, або жодна послуга не обслуговує маршрут.

HTTP 401 або 403 у журналі чи попередженнях: Melhor Envio відхилив токен доступу. Він неправильний, прострочений або відкликаний, або належить до іншого середовища. Створіть новий токен і перевірте, що Sandbox відповідає йому.

До ціни Melhor Envio додається податок: встановіть Tax class на No tax.

Після зміни розрахунки здаються застарілими: натисніть Save на сторінці розширення. Це очистить кеш розрахунків.

Сторінка пише "Warning: You do not have permission to modify VibeFox Melhor Envio!": ваша група адміністраторів може лише переглядати налаштування. Надайте групі право змінювати extension/shipping/vfd_melhor_envio (OpenCart 3) або extension/vfd_melhor_envio/shipping/vfd_melhor_envio (OpenCart 4) у розділі System > Users > User Groups.

Для розробників: адресу API розрахунків Melhor Envio можна замінити налаштуванням vfd_menv_api_url (для тестів); для нього немає поля на сторінці налаштувань.

Видалення

Перейдіть до Extensions > Extensions, виберіть тип Shipping і натисніть Uninstall (червона кнопка −) поруч із VibeFox Melhor Envio. Ліцензійний ключ і статус ліцензії цього розширення завжди видаляються. OpenCart завжди скидає Enable Melhor Envio shipping, Sort order, Tax class і Geo zone. Кеш розрахунків завжди видаляється. Якщо Remove data on uninstall увімкнено, також видаляються інші налаштування та журнал налагодження. Якщо вимкнено, вони зберігаються і використовуються знову, коли ви повторно встановлюєте розширення. Послуги, збережені із замовленнями, завжди залишаються, а наявні замовлення зберігають свій спосіб доставки та вартість.

На OpenCart 4, щоб також видалити файли розширення, після видалення перейдіть до Extensions > Installer, натисніть Uninstall (помаранчева кнопка −) поруч із VibeFox Melhor Envio у списку встановлених розширень, а потім Delete (червона кнопка з кошиком), щоб видалити завантажений пакет.

Melhor Envio є торговою маркою її власника. Це розширення не пов'язане з Melhor Envio і не схвалене Melhor Envio.