VibeFox Melhor Envio for PrestaShop — Допомога
Вимоги
PrestaShop: 8.0–9.x.
PHP: 8.0 або новіша версія. Модуль не встановлюється на старіших версіях PHP.
Обліковий запис Melhor Envio (лише для актуальних розрахунків): для актуальних розрахунків потрібен токен доступу. В обліковому записі Melhor Envio відкрийте сторінку токенів (melhorenvio.com.br/painel/gerenciar/tokens) і створіть токен з дозволом «shipping-calculate». Для тестів створіть токен у пісочниці Melhor Envio (sandbox.melhorenvio.com.br/painel/gerenciar/tokens). Токени бойового режиму та пісочниці відрізняються. Кнопки «підключити» немає: токен вставляється в налаштування модуля. Без токена перевізник використовує резервні ціни.
Ліцензійний ключ VibeFox: купується на vibefox.net. Один ключ працює на одному домені.
Встановлення
1. В панелі адміністратора перейдіть до Modules > Module Manager і натисніть Upload a module. Оберіть ZIP-файл модуля.
2. Після завершення завантаження натисніть Configure або пізніше знайдіть VibeFox Melhor Envio у списку модулів і натисніть Configure.
3. Вставте ліцензійний ключ VibeFox у License key у блоці ліцензії у верхній частині сторінки Configure і натисніть Activate (див. розділ «Ліцензійний ключ»).
4. Вставте токен доступу, контактну e-mail адресу та CEP відправлення. Якщо валюта магазину за замовчуванням не BRL, вкажіть BRL exchange rate. За бажанням заповніть таблицю резервних цін (наприклад, для Бразилії) або резервну вартість. Натисніть Save.
Під час встановлення модуль створює перевізника Melhor Envio з текстом терміну доставки Delivery by the carriers of your Melhor Envio account. Перевізник прив'язується до всіх зон і всіх груп покупців. Зони, групи покупців, термін доставки, логотип і обмеження розмірів можна змінити в Shipping > Carriers. Ціни там не задавайте: ціна завжди береться з модуля.
Налаштування
Усі налаштування розташовані на сторінці модуля: Modules > Module Manager > VibeFox Melhor Envio > Configure. Вони діють для всіх зон перевізника. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Кожне збереження також очищує кешовані розрахунки Melhor Envio та останню помилку API.
Попередження у верхній частині сторінки показують неповне налаштування: порожній CEP відправлення або CEP не з 8 цифр, відсутня контактна e-mail адреса, відсутній курс BRL, остання помилка API Melhor Envio з датою, відсутній токен, відсутня резервна ціна (тоді перевізник ніколи не показується) або одиниця ваги чи розмірів магазину, яку модуль не знає (тоді вона читається як кг або см). Якщо в числовому полі є щось, що не є числом від 0 і більше, якщо Min weight більше за Max weight або Default product size не має формату довжина x ширина x висота, сторінка показує помилку і нічого не зберігається.
General
Enable Melhor Envio shipping: вмикає або вимикає перевізника. Це той самий перемикач, що й статус перевізника в Shipping > Carriers.
Name: назва перевізника, яку покупці бачать під час оформлення замовлення. За замовчуванням: Melhor Envio. Обов'язкове поле, не більше 64 символів.
Tax: правило податку перевізника або No tax. Ціни Melhor Envio є остаточними цінами перевізника. Оберіть No tax, якщо PrestaShop не повинен додавати до них податок.
Melhor Envio API
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) для тестування. Використовуйте з нею токен пісочниці. За замовчуванням: вимкнено.
Contact e-mail: технічна контактна e-mail адреса, яка передається в Melhor Envio в заголовку User-Agent кожного запиту. Melhor Envio вимагає її від кожної інтеграції. Некоректна адреса не зберігається, і про це з'являється повідомлення.
Origin CEP: CEP (8 цифр), з якого відправляються посилки, наприклад 01310-100. Зберігається у форматі 00000-000. Без коректного CEP відправлення розрахунки не запитуються.
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». За замовчуванням: увімкнено.
Declared value: оголошує вартість товарів (страхування) в розрахунках. Коли вимкнено, розрахунки виконуються без оголошеної вартості: вони дешевші, але посилки не застраховані. За замовчуванням: увімкнено.
BRL exchange rate: Melhor Envio розраховує вартість у бразильських реалах. Це потрібно лише якщо валюта магазину за замовчуванням не BRL: введіть ціну 1 BRL у валюті магазину за замовчуванням, наприклад 0.17. Без нього актуальні розрахунки не використовуються. Значення має бути більшим за 0. Оголошена вартість перераховується в BRL за тим самим курсом. Якщо валюта магазину за замовчуванням BRL, поле показує Store currency is BRL.
Default product weight: у кг, для товарів без ваги, як для розрахунків, так і для обмежень за вагою. Має бути більшим за 0. За замовчуванням: 0.3.
Default product size: довжина x ширина x висота в см, для товарів без розмірів. За замовчуванням: 16x11x5.
Резервні ціни (у валюті магазину за замовчуванням)
Резервні ціни використовуються, якщо немає токена, не вказано CEP призначення або API не повертає розрахунок (помилка, тайм-аут, немає покриття).
Fallback price table: ціна за країною та вагою кошика. Натисніть Add country, щоб додати рядок, і значок кошика для видалення рядка. Оберіть * Default як країну для кожної країни, яка не має власного рядка. Кожен рядок має Price та колонки ваги: XS до 1 кг, S 1-2 кг, M 2-3 кг, L 3-5 кг і XL понад 5 кг. Порожня колонка або колонка з 0 використовує Price. Приймаються як «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: приховує перевізника, якщо кошик важить менше, у кг. 0 означає без обмеження.
Max weight: приховує перевізника, якщо кошик важить більше, у кг. За замовчуванням: 30. 0 означає без обмеження. Порожнє поле означає 30 кг у зонах перевізника і відсутність обмеження лише для країн з Ignore shipping zones, які знаходяться поза ними.
Minimum subtotal: показує перевізника лише якщо проміжна сума кошика (товари, що потребують доставки, після знижок, до податків) становить щонайменше цю суму. Залиште порожнім, щоб показувати завжди.
Free shipping from: проміжна сума кошика, від якої доставка безкоштовна. За варіанта «по одному на послугу» безкоштовною стає лише найдешевша послуга. Швидші послуги зберігають свою ціну. Залиште порожнім, щоб вимкнути.
Ignore shipping zones: пропонує перевізника в країнах, зазначених нижче, навіть якщо він не прив'язаний до їхніх зон. Поки це ввімкнено, перевізник прив'язаний до всіх зон, зокрема неактивних і створених пізніше. Коли ви вимикаєте це, перевізник знову отримує власні зони.
Countries: країни призначення для цього режиму. Залиште порожнім для всіх країн. Це поле використовується лише коли ввімкнено Ignore shipping zones.
Додатково
Debug log: записує запити до API та розрахунок вартості в logs/vfd_menv_debug.log.php у папці модуля. Файл не можна відкрити з веб. Помилки завжди записуються, навіть коли цей параметр вимкнено. Токен ніколи не записується в журнал, а CEP покупця скорочується до перших 5 цифр.
Log: показує розмір і останні записи журналу налагодження. Натисніть Clear log, щоб очистити його.
Remove data on uninstall: якщо увімкнено, видалення модуля стирає всі його налаштування, перевізника та журнал. Якщо вимкнено, усе зберігається для повторного встановлення. Кеш розрахунків завжди видаляється. Послуги, збережені із замовленнями, є історією замовлень і зберігаються.
Як це працює під час оформлення замовлення
На етапі доставки PrestaShop запитує в модуля ціну Melhor Envio. Враховуються лише товари, що потребують доставки: віртуальні товари не додають ваги і не входять до проміжної суми. Модуль спершу перевіряє умови: країни з Ignore shipping zones, вагу кошика і мінімальну проміжну суму.
Для адреси доставки в Бразилії з CEP з 8 цифр модуль надсилає в Melhor Envio CEP відправлення та призначення, а також кожен товар, який можна відправити, з його вагою, розмірами, кількістю та оголошеною вартістю, плюс список послуг, якщо ви його задали. Розрахунки переводяться у валюту магазину за замовчуванням, сортуються за ціною, а потім показуються у валюті кошика покупця. Якщо діє безкоштовна доставка, найдешевша послуга коштує 0.
За One option - the cheapest service перевізник показує ціну найдешевшої послуги та рядок Delivery estimate: під перевізником, якщо увімкнено Delivery time. За One option per service покупець бачить Choose a delivery service: під перевізником, з перемикачем для кожної послуги, її ціною та оцінкою терміну доставки. Вибір зберігається одразу, а ціна перевізника та підсумок кошика оновлюються. Якщо послуга більше не пропонується для адреси, покупець бачить This service is not available for your address any more. Please choose another one., і повертається попередній вибір.
Кожен розрахунок кешується на 1 годину для кожної комбінації посилки, CEP, токена та середовища, тож той самий кошик не викликає новий запит. Невдалий виклик запам'ятовується на 5 хвилин, щоб збій API не сповільнював кожне оновлення оформлення замовлення. Тайм-аут API — 12 секунд.
Якщо немає токена, адреса знаходиться поза Бразилією або ще не має коректного CEP, курс BRL відсутній, або Melhor Envio повертає помилку чи жодної послуги для маршруту, використовуються резервні ціни: рядок країни (або рядок *), інакше резервна вартість. Якщо діє безкоштовна доставка, перевізник показується безкоштовно, навіть без ціни. Якщо ціни немає взагалі, перевізник приховується. Покупець ніколи не бачить помилку API.
Якщо ви редагуєте перевізника в Shipping > Carriers після того, як у нього з'явилися замовлення, PrestaShop зберігає його як нову версію перевізника. Модуль автоматично переходить на нову версію.
Модуль лише розраховує ціни. Він не купує і не створює етикетки, не додає відправлення до кошика Melhor Envio, не відстежує посилки, не призначає забір і не надсилає дані рахунку-фактури (NF-e). Він не пропонує вибір відділень Jadlog, Azul або LATAM (пунктів приймання) та додаткових послуг «вручення особисто» і «повідомлення про вручення». Керуйте відправленнями в панелі Melhor Envio. Melhor Envio відправляє лише всередині Бразилії. Інші країни отримують лише резервні ціни.
Замовлення
Коли замовлення оформлено з актуальним розрахунком, модуль зберігає разом із замовленням послугу Melhor Envio та її оцінку терміну доставки. На сторінці замовлення в панелі адміністратора відображається блок Melhor Envio з Melhor Envio service (з ID послуги) і Delivery estimate, щоб ви знали, яку послугу купувати в Melhor Envio. Покупець бачить ту саму інформацію на сторінці свого замовлення в обліковому записі. У листі з підтвердженням замовлення вони додаються після назви перевізника. Замовлення з резервною ціною не мають послуги. Існуючі замовлення не зачіпаються.
Ліцензійний ключ
Модуль працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox Melhor Envio — перший блок на сторінці Modules > Module Manager > VibeFox Melhor Envio > Configure, над налаштуваннями. Вставте ключ у License key і натисніть Activate. Після цього блок показує ключ у замаскованому вигляді, статус (наприклад, дату, до якої ліцензія дійсна, і ваш домен) та кнопки Check now для повторної перевірки статусу, Change key для введення іншого ключа і Remove key для видалення ключа з цього магазину. Нижче розташовані рядок Product: presta-shipping-melhor-envio і посилання Manage licenses and domains in your account, яке відкриває ваш обліковий запис vibefox.net. Змінювати ключ можуть лише співробітники з правом Configure для модуля. Тексти блоку відповідають мові бек-офісу (включено англійську та російську).
Якщо ключ не прийнято, блок повідомляє причину, наприклад Key not found, This key belongs to another product, Domain limit reached або License expired on і дату. Після зміни адреси магазину або після звільнення слота домену в обліковому записі натисніть Check now. Якщо сервер ліцензій недоступний, модуль продовжує працювати за останнім відомим статусом.
Один ключ працює на одному домені: домені основного магазину, також у конфігурації з кількома магазинами. Видалення ключа з магазину не звільняє слот домену. Звільніть слот у своєму обліковому записі vibefox.net.
Без активного ключа перевізник Melhor Envio не показується покупцям під час оформлення замовлення, і розрахунки не виконуються. Вітрина PrestaShop не знає, що ви увійшли в бек-офіс, тому перевізник приховується й для вас: модуль можна налаштувати до купівлі ключа, але не можна перевірити під час оформлення замовлення. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Існуючі замовлення не зачіпаються.
Коли ліцензія спливає, модуль продовжує працювати, але для оновлень і підтримки потрібне продовження. Статус автоматично перевіряється під час роботи в бек-офісі: раз на добу протягом перших 14 днів після введення ключа, потім раз на тиждень. Cron-завдання не потрібне. Видалення або скидання модуля завжди видаляє ліцензійний ключ і статус ліцензії.
Усунення несправностей
Melhor Envio не з'являється під час оформлення замовлення: перевірте, що ліцензія активна і увімкнено Enable Melhor Envio shipping. В Shipping > Carriers перевірте, що перевізник охоплює зону країни покупця та групу покупця, або увімкніть Ignore shipping zones і перевірте Countries. Перевірте попередження у верхній частині сторінки модуля, обмеження за вагою та Minimum subtotal. Без токена або розрахунку перевізнику потрібна резервна ціна: рядок у Fallback price table або Fallback cost. Товари також можуть бути обмежені певними перевізниками на сторінці товару.
Показуються лише резервні ціни: увімкніть Debug log, перезавантажте оформлення замовлення і перегляньте поле Log на сторінці модуля. Типові причини: немає токена, CEP відправлення не з 8 цифр, немає BRL exchange rate за валюти за замовчуванням, відмінної від BRL, ще немає CEP призначення або жодна послуга не покриває маршрут.
HTTP 401 або 403 у журналі чи попередженнях: Melhor Envio відхилив токен доступу. Він неправильний, прострочений або відкликаний, чи належить до іншого середовища. Створіть новий токен і перевірте, що Sandbox відповідає йому.
Покупець бачить «The service could not be saved. Please try again.»: вибір не дійшов до магазину, наприклад через мережеву помилку. Покупець може обрати послугу знову. Послуга, обрана в момент, коли покупець натискає Continue, також зберігається.
До ціни Melhor Envio додається податок: встановіть Tax у значення No tax.
Після зміни розрахунки виглядають застарілими: натисніть Save на сторінці модуля. Це очистить кешовані розрахунки.
Сторінка повідомляє, що перевізника Melhor Envio не знайдено: перевізника видалено в Shipping > Carriers. Скиньте модуль у Modules > Module Manager, щоб створити його знову.
Видалення
Перейдіть до Modules > Module Manager, відкрийте меню поруч із VibeFox Melhor Envio і виберіть Uninstall. Ліцензійний ключ і статус ліцензії завжди видаляються. Кеш розрахунків завжди видаляється. Якщо Remove data on uninstall увімкнено, перевізник видаляється (замовлення зберігають свою історію), його власні зони відновлюються, а налаштування, вибір послуг у відкритих кошиках і журнал видаляються. Якщо вимкнено, перевізник лише деактивується і всі налаштування зберігаються. Під час повторного встановлення модуля перевізник отримує статус, який мав раніше. Послуги, збережені із замовленнями, завжди зберігаються.
Melhor Envio є торговою маркою її власника. Цей модуль не пов'язаний з Melhor Envio і не схвалений ним.