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

Вимоги

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

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

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

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

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

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

OpenCart 3

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

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

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

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

5. Для тарифів у реальному часі вставте токен доступу, виберіть країну Mercado Envios і, якщо валюта магазину за замовчуванням не ARS, BRL або MXN, вкажіть обмінний курс. За бажанням заповніть Country prices і Fallback cost (використовуються без тарифів у реальному часі). Увімкніть Enable Mercado Envios shipping і натисніть Save.

OpenCart 4

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

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

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

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

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

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

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

Попередження в розділі General (і після кожного збереження) показують проблеми конфігурації: відсутній обмінний курс, немає токена доступу та ціни (тоді спосіб доставки ніколи не показується), остання помилка API Mercado Envios з датою, а також одиниця ваги або довжини магазину, яку розширення не знає (тоді вона читається як кг або см). Якщо Name порожнє або довше 64 символів, Exchange rate не є додатним числом, інше числове поле не є числом від 0 і більше, або Min weight більше за Max weight, сторінка показує помилку, і нічого не зберігається.

Загальні

Покупець бачить один тариф Mercado Envios. Ви можете обмежити спосіб доставки географічною зоною або країнами в Availability. Ці налаштування застосовуються до всіх зон.

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

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

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

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

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

Access token: ваш робочий токен доступу Mercado Pago (APP_USR-...). Він надсилається лише на api.mercadopago.com і ніколи не записується в журнал. Після збереження поле залишається порожнім і показує Saved — leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити.

Remove the saved access token: увімкніть і збережіть, щоб видалити збережений токен. Тоді використовуються лише ціни нижче. Токен, введений вище, натомість замінює збережений.

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

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

Ціни без тарифів у реальному часі

Ці ціни використовуються, якщо немає токена доступу, для напрямків поза країною Mercado Envios і якщо API не повертає тариф (невдалий запит повторюється через 5 хвилин). Вони вказані у валюті магазину за замовчуванням без податку.

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 (kg): мінімальна вага кошика, за якої з'являється цей спосіб доставки. 0 означає без обмеження (за замовчуванням).

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

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

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

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

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

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

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

Додатково

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

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

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

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

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

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

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

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

Для напрямку в країні Mercado Envios з дійсним поштовим індексом (4 цифри в Аргентині, також з CPA, наприклад C1425ABC; 8 цифр у Бразилії; 5 цифр у Мексиці) розширення описує кошик як одну посилку: найбільша ширина і довжина товарів, сума висот усіх товарів і загальна вага в грамах. Вага і розміри товарів перераховуються з їхніх класів ваги та довжини OpenCart. Кожна сторона і вага піднімаються до мінімумів Mercado Envios для країни, тож товари без розмірів або ваги також отримують тариф. Вартість кошика надсилається як ціна товару у валюті Mercado Envios. Найдешевший варіант, який повернув Mercado Envios, переводиться у валюту магазину за замовчуванням, округлюється до потрібної кількості знаків і показується у валюті покупця з податком обраного Tax class.

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

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

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

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

Замовлення

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Видалення

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

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

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