VibeFox Mercado Envios for PrestaShop — Допомога

Вимоги

PrestaShop: від 8.0 до 9.x.

PHP: 8.0 або новіша. Модуль не встановлюється на старіших версіях PHP.

Обліковий запис Mercado Pago (лише для актуальних тарифів): актуальні тарифи беруться з калькулятора Mercado Envios вашого облікового запису Mercado Pago в Аргентині, Бразилії або Мексиці. У обліковому записі має бути увімкнений Mercado Envios. Посилки розраховуються від адреси відправлення, вказаної в цьому обліковому записі. Вам потрібен Access Token для робочого середовища (він починається з APP_USR-): у панелі розробника Mercado Pago відкрийте свій застосунок і його робочі облікові дані. Кнопки входу немає: токен вставляється в налаштування модуля. Якщо ви використовуєте лише ціни за країнами, обліковий запис Mercado Pago не потрібен.

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

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

1. В адмін-панелі перейдіть до Modules > Module Manager і натисніть Upload a module. Оберіть ZIP-файл модуля.

2. Після завершення завантаження натисніть Configure або пізніше знайдіть VibeFox Mercado Envios у списку модулів і натисніть Configure.

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

4. Для актуальних тарифів вставте Access Token, оберіть країну Mercado Envios і, якщо базова валюта вашого магазину не ARS, BRL або MXN, курс обміну. За бажанням заповніть Country prices і Fallback cost (вони використовуються без актуальних тарифів). Натисніть Save.

Під час встановлення модуль створює перевізника Mercado Envios з текстом строку доставки Mercado Envios delivery. Перевізник призначається всім зонам і всім групам клієнтів, без податкового правила. Зони, групи клієнтів, строк доставки, логотип і обмеження за розміром можна змінити в Shipping > Carriers. Не встановлюйте там ціни: ціна завжди береться з модуля.

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

Усі налаштування розташовані на сторінці модуля: Modules > Module Manager > VibeFox Mercado Envios > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Кожне збереження також очищає кеш тарифів Mercado Envios і останню помилку API.

Попередження у верхній частині сторінки показують проблеми налаштування: відсутній курс обміну, немає access token і ціни, остання помилка API Mercado Envios з датою, а також одиниця ваги чи розміру магазину, яку модуль не розпізнає (тоді вона читається як кг або см). Якщо перевізника видалено, у розділі General з'явиться повідомлення The Mercado Envios carrier was not found — reset the module to create it again.

Загальні

Додайте зони своїх клієнтів до перевізника Mercado Envios в Shipping > Carriers або скористайтеся Ignore shipping zones нижче. Ці налаштування діють для кожної зони.

Enable Mercado Envios shipping: вмикає або вимикає перевізника. Це той самий перемикач, що й статус перевізника в Shipping > Carriers.

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

Tax: податкове правило перевізника або No tax (за замовчуванням). Mercado Envios повертає кінцеві ціни. No tax показує їх так, як вони надійшли; податкове правило додає до них ваш податок на доставку.

API Mercado Envios (актуальні тарифи) (без токена використовуються лише ціни нижче)

Access token: ваш Access Token Mercado Pago для робочого середовища (APP_USR-...). Він надсилається лише на api.mercadopago.com і ніколи не записується в журнал. Після збереження поле залишається порожнім і показує Saved — leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити. Щоб припинити використання актуальних тарифів, позначте Remove the saved access token (only the prices below are used then) і збережіть.

Mercado Envios country: країна вашого облікового запису Mercado Pago: Argentina (ARS) (за замовчуванням), Brazil (BRL) або Mexico (MXN). Актуальні тарифи запитуються лише для напрямків у цій країні та вказуються в її валюті.

Exchange rate: потрібен лише тоді, коли базова валюта магазину відрізняється від валюти Mercado Envios: ціна 1 ARS, BRL або MXN у базовій валюті магазину, наприклад 0.001. Без нього актуальні тарифи не використовуються. Має бути додатне число. Як десятковий роздільник приймаються і крапка, і кома.

Ціни без актуальних тарифів

Ці ціни використовуються, коли немає access token, для напрямків за межами країни Mercado Envios і коли API не повертає тариф. Вони вказані в базовій валюті магазину без податку.

Country prices: таблиця країн призначення та цін. Натисніть Add country, щоб додати рядок, і значок кошика, щоб видалити рядок. Оберіть * All other countries для всіх країн, які не мають власного рядка. Price — ціна для країни. Колонки XS (до 1 кг), S (1-2 кг), M (2-3 кг), L (3-5 кг) і XL (понад 5 кг) замінюють її для цієї ваги кошика. Порожня колонка або колонка з 0 використовує Price. Значення Price 0 означає безкоштовну доставку до цієї країни. Приймаються як 9.99, так і 9,99. Значення, які не є числами, повідомляються після збереження і очищуються. Рядки без жодної ціни видаляються під час збереження.

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

Calculation type: Per order стягує ціну один раз. Per item (each item priced by its own weight x quantity) шукає в Country prices (або в Fallback cost) ціну для ваги кожного товару та множить її на кількість. Якщо для якогось товару ціни немає, перевізника приховано. Актуальні тарифи Mercado Envios завжди стосуються всієї посилки.

Доступність

Min weight: мінімальна вага кошика в кг, за якої з'являється цей перевізник. 0 означає без обмеження.

Max weight: приховує перевізника, якщо кошик важить більше, у кг. Порожнє поле означає 25 кг, 0 означає без обмеження. Min weight більше за Max weight відхиляється під час збереження.

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

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

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

Безкоштовна доставка

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

Додатково

Debug log: записує запити до API та розрахунок тарифів у logs/vfd_mrcv_debug.log.php у папці модуля. Файл не можна відкрити через веб. Помилки завжди записуються, навіть коли ця опція вимкнена. Access token і адреси клієнтів ніколи не записуються в журнал.

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

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

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

На етапі доставки PrestaShop запитує в модуля ціну Mercado Envios. Враховуються лише фізичні товари: віртуальні товари не додають ваги і не входять до проміжної суми. Модуль спочатку перевіряє умови: дозволені країни (з Ignore shipping zones), вагу кошика та мінімальну проміжну суму. Якщо діє безкоштовна доставка, ціна дорівнює 0, і запит до Mercado Envios не надсилається.

Для напрямку в країні Mercado Envios з коректним поштовим індексом модуль описує кошик як одну посилку: найбільші ширина та довжина товарів, сума висот усіх товарів і загальна вага в грамах. Кожна сторона та вага піднімаються до мінімальних значень Mercado Envios для країни, тож навіть товари без розмірів чи ваги отримують тариф. Вартість кошика надсилається як ціна товару у валюті Mercado Envios. Найдешевший варіант, який повернув Mercado Envios, конвертується в базову валюту магазину і потім показується у валюті кошика покупця.

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

Натомість використовуються ціни без актуальних тарифів, коли немає токена, напрямок за межами країни Mercado Envios, поштовий індекс відсутній або некоректний, курс обміну не задано, посилка важча за ліміт Mercado Envios для країни (25 кг в Аргентині, 15 кг у Бразилії, 30 кг у Мексиці), або Mercado Envios повертає помилку чи жодного варіанта для адреси. Використовується рядок країни (або рядок *), інакше резервна вартість. Якщо ціни немає, перевізника приховано. Покупець ніколи не бачить помилку API.

Якщо ви редагуєте перевізника в Shipping > Carriers після того, як у нього з'явилися замовлення, PrestaShop зберігає його як нову версію перевізника. Модуль автоматично переходить на нову версію.

Модуль лише розраховує тарифи. Він не створює відправлень, не друкує етикетки та не відстежує посилки. Створіть відправлення у своєму обліковому записі Mercado Libre або Mercado Pago. Модуль показує одну ціну, найдешевший варіант Mercado Envios, а не вибір з усіх варіантів, і не має вибору пункту видачі (відділення).

Замовлення

Коли замовлення оформлено з актуальним тарифом Mercado Envios, модуль зберігає назву служби, орієнтовний строк доставки в днях і актуальний тариф. В адмін-панелі на сторінці замовлення показано блок Mercado Envios з полями Mercado Envios service, Estimated delivery та Live rate (excl. tax). Покупець бачить Mercado Envios service і Estimated delivery на сторінці деталей замовлення у своєму обліковому записі. Наявні замовлення не змінюються через пізніші зміни тарифів.

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

Модуль працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox Mercado Envios — це перший блок на сторінці Modules > Module Manager > VibeFox Mercado Envios > Configure, над налаштуваннями. Вставте ключ у поле License key і натисніть Activate. Після цього блок показує ключ у прихованому вигляді, статус (наприклад, дату, до якої дійсна ліцензія, і ваш домен), а також кнопки Check now для повторної перевірки статусу, Change key для введення іншого ключа та Remove key для видалення ключа з цього магазину. Нижче розташовані рядок Product: presta-shipping-mercado-envios і посилання 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.

Без активного ключа перевізник Mercado Envios не показується покупцям під час оформлення замовлення, і тариф не розраховується. Вітрина PrestaShop не знає, що ви ввійшли в адмін-панель, тож перевізника приховано й для вас: модуль можна налаштувати до купівлі ключа, але перевірити його під час оформлення замовлення не можна. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Наявні замовлення не змінюються.

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

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

Mercado Envios не з'являється під час оформлення замовлення: перевірте, що ліцензія активна і ввімкнено Enable Mercado Envios shipping. У Shipping > Carriers перевірте, що перевізник охоплює зону країни покупця та групу покупця (або ввімкніть Ignore shipping zones і перевірте Countries). Перевірте попередження у верхній частині сторінки модуля, обмеження ваги та Minimum subtotal. Перевізнику потрібна ціна: робочий access token для адрес у країні Mercado Envios, або Country prices, або Fallback cost. Крім того, товари можуть бути обмежені певними перевізниками на сторінці товару.

Актуальні тарифи не з'являються: увімкніть Debug log, перезавантажте оформлення замовлення і перегляньте поле Log на сторінці модуля. Типові причини: немає токена, напрямок за межами країни Mercado Envios, відсутній або некоректний поштовий індекс, не задано Exchange rate, посилка перевищує ліміт ваги або для адреси немає варіанта Mercado Envios.

HTTP 401 або 403 у попередженнях: access token недійсний або прострочений. Скопіюйте Access Token для робочого середовища ще раз із панелі розробника Mercado Pago.

Mercado Envios відповів в іншій валюті: країна облікового запису не відповідає Mercado Envios country. Оберіть країну свого облікового запису Mercado Pago.

У якій валюті ціни? Country prices, Fallback cost і пороги вказані в базовій валюті магазину. Актуальні тарифи надходять у валюті вашого облікового запису Mercado Pago і конвертуються через Exchange rate, коли магазин використовує іншу базову валюту.

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

На сторінці написано, що перевізника Mercado Envios не знайдено: перевізника видалено в Shipping > Carriers. Скиньте модуль у Modules > Module Manager, щоб створити його знову.

Видалення

Перейдіть до Modules > Module Manager, відкрийте меню поруч із VibeFox Mercado Envios і оберіть Uninstall. Ліцензійний ключ і статус ліцензії завжди видаляються. Кеш тарифів завжди видаляється. Якщо Remove data on uninstall увімкнено, перевізника буде видалено (замовлення зберігають свою історію), а також видаляться налаштування, журнал і збережені дані служби замовлень. Якщо вимкнено, перевізника лише вимикають, а всі налаштування та дані служби замовлень зберігаються. Після повторного встановлення модуля перевізник отримує статус, який мав до видалення.

Mercado Envios і Mercado Pago є торговельними марками їх відповідних власників. Цей модуль не пов'язаний з Mercado Envios чи Mercado Pago і не схвалений ними.