VibeFox Mercado Envios for WooCommerce — Помощь

Требования

WordPress: 5.8 или новее.

WooCommerce: 7.0 или новее, установлен и активен. Без него плагин не активируется.

PHP: 8.0 или новее.

Аккаунт Mercado Pago (только для актуальных тарифов): актуальные тарифы поступают из калькулятора Mercado Envios вашего аккаунта Mercado Pago в Аргентине, Бразилии или Мексике. В аккаунте должен быть включён Mercado Envios. Посылки рассчитываются от адреса отправления, указанного в этом аккаунте. Нужен Access Token для продакшена (он начинается с APP_USR-): в панели разработчика Mercado Pago откройте своё приложение и его продакшен-учётные данные. Кнопки входа нет: токен вставляется в настройки. Если вы используете только цены по странам, аккаунт Mercado Pago не нужен.

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

Установка

1. В WordPress перейдите в Plugins > Add New > Upload Plugin, выберите ZIP-файл плагина и нажмите Install Now. Также можно загрузить папку vfd_mercado_envios в /wp-content/plugins/ по FTP.

2. Нажмите Activate.

3. Откройте настройки: WooCommerce > Settings > Shipping > VibeFox Mercado Envios, или нажмите Settings под названием плагина на странице Plugins.

4. Введите лицензионный ключ VibeFox в блоке лицензии в верхней части страницы и нажмите Activate.

5. Для актуальных тарифов вставьте Access Token, выберите страну Mercado Envios и, если валюта магазина не ARS, BRL или MXN, укажите курс обмена. По желанию заполните Country prices и Fallback cost (они используются без актуальных тарифов).

6. Добавьте VibeFox Mercado Envios в зону доставки: WooCommerce > Settings > Shipping > Shipping zones, или включите Ignore shipping zones и выберите страны.

Настройка

Все настройки находятся на одной странице: WooCommerce > Settings > Shipping > VibeFox Mercado Envios. Они действуют для всех зон доставки. Когда вы добавляете способ в зону, в окне зоны только одно поле:

Title (zone): название этого варианта при оформлении заказа. Оставьте поле пустым, чтобы использовать общее Name.

Предупреждения в верхней части страницы показывают проблемы настройки: отсутствие курса обмена, отсутствие токена доступа и цены, а также последняя ошибка API Mercado Envios с датой. При каждом сохранении настроек кэш тарифов очищается.

Общие

Enable/Disable: включает или выключает доставку Mercado Envios во всех зонах одновременно.

Name: название способа доставки, которое видят покупатели при оформлении заказа. По умолчанию: Mercado Envios.

Tax status: Mercado Envios выдаёт окончательные цены. None показывает их как есть, Taxable добавляет сверху налог на доставку из WooCommerce.

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

Access token: ваш Access Token для продакшена из Mercado Pago (APP_USR-...). Он отправляется только в Mercado Pago и никогда не записывается в журнал.

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

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

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

Эти цены используются, когда нет токена доступа, для направлений за пределами страны 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. Значения, которые не являются числами, выводятся после сохранения и очищаются. Строки без какой-либо цены удаляются при сохранении.

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. 0 означает без ограничения.

Minimum subtotal: показывает способ только если промежуточная сумма корзины не меньше этой суммы. Оставьте поле пустым, чтобы показывать всегда.

Excluded shipping classes: скрывает способ, если какой-либо товар в корзине относится к одному из этих классов доставки WooCommerce.

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

Countries: страны назначения для этого режима. Оставьте пустым для всех стран. Поле используется только при включённом Ignore shipping zones.

Бесплатная доставка

Free shipping from: промежуточная сумма корзины, начиная с которой этот способ бесплатен. В этом случае запрос к Mercado Envios не отправляется. Оставьте пустым, чтобы отключить.

Дополнительно

Debug log: записывает в журнал запросы к API и расчёт тарифов в WooCommerce > Status > Logs (источник vfd-mercado-envios). Ошибки записываются всегда, даже при выключенной опции. Токен доступа и адреса покупателей никогда не записываются в журнал.

Remove data on uninstall: при включении удаление плагина стирает все его настройки и способы в зонах. Деактивация плагина никогда не удаляет настройки.

Как это работает при оформлении заказа

Когда покупатель вводит адрес доставки, WooCommerce запрашивает у плагина тариф. Плагин сначала проверяет условия: вес корзины, минимальную сумму и исключённые классы доставки. Если действует бесплатная доставка, способ стоит 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.

Способ работает при классическом оформлении заказа и в блоках Корзина и Оформление заказа. Он совместим с WooCommerce High-Performance Order Storage (HPOS).

Плагин только рассчитывает тарифы. Он не создаёт отправления, не печатает этикетки и не отслеживает посылки. Создайте отправление в своём аккаунте Mercado Libre или Mercado Pago. Он показывает один тариф на способ — самый дешёвый вариант Mercado Envios, а не выбор из всех вариантов, и не имеет выбора пункта выдачи (агентства).

Заказы

Если заказ оформлен с актуальным тарифом, название службы и предполагаемый срок доставки в днях сохраняются в позиции доставки заказа как Mercado Envios service и Estimated delivery. Существующие заказы сохраняют свои позиции доставки.

Лицензионный ключ

Плагин работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии находится вверху страницы WooCommerce > Settings > Shipping > VibeFox Mercado Envios. Вставьте ключ в поле License key и нажмите Activate. В блоке показывается статус, например дата, до которой лицензия действительна, и ваш домен. Кнопка Check now повторно проверяет статус, Change key позволяет ввести другой ключ, а Remove key удаляет его с этого сайта. Ссылка Manage licenses and domains in your account открывает ваш аккаунт на vibefox.net.

Один ключ работает на одном домене. Удаление ключа с сайта не освобождает слот домена. Освободите его в своём аккаунте на vibefox.net.

Без активного ключа Mercado Envios не показывается покупателям при оформлении заказа. Авторизованные менеджеры магазина по-прежнему видят его с пометкой (unlicensed — visible to admins only), чтобы вы могли настроить и протестировать плагин до покупки ключа. Напоминание появляется на странице Plugins и на страницах WooCommerce. Существующие заказы не затрагиваются.

Когда срок лицензии истекает, плагин продолжает работать, но для обновлений и поддержки нужно продление. Статус автоматически проверяется в фоновом режиме.

Устранение неполадок

Mercado Envios не появляется при оформлении заказа: проверьте, что лицензия активна, что Enable/Disable включён и способ добавлен в зону страны покупателя (или включён Ignore shipping zones и страна разрешена). Проверьте предупреждения вверху страницы настроек, ограничения веса, Minimum subtotal и Excluded shipping classes. Способу нужна цена: рабочий токен доступа для адресов в стране Mercado Envios либо Country prices или Fallback cost.

Актуальные тарифы не появляются: включите Debug log, перезагрузите оформление заказа и откройте WooCommerce > Status > Logs, источник vfd-mercado-envios. Типичные причины: нет токена, направление за пределами страны Mercado Envios, отсутствующий или недействительный почтовый индекс, не задан Exchange rate, посылка превышает лимит веса или для адреса нет варианта Mercado Envios.

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

Mercado Envios ответил в другой валюте: страна аккаунта не совпадает с Mercado Envios country. Выберите страну вашего аккаунта Mercado Pago.

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

Тарифы выглядят устаревшими после изменения: сохраните страницу настроек. Это очистит кэш тарифов.

Блок лицензии показывает ошибку: следуйте сообщению в блоке. Например, если ключ уже используется на другом домене, освободите слот в своём аккаунте на vibefox.net и нажмите Check now. Если адрес сайта изменился, нажмите Check now, чтобы активировать ключ для нового домена. Если сервер лицензий недоступен, плагин продолжает работать по последнему известному статусу.

Удаление

Деактивация плагина сохраняет все настройки. Очищается только кэш тарифов. Чтобы удалить плагин, деактивируйте его и удалите на странице Plugins. Лицензионный ключ и статус лицензии этого плагина, кэш тарифов и последняя ошибка API удаляются всегда. Настройки и способы в зонах удаляются, только если была включена опция Remove data on uninstall. Иначе они сохраняются для повторной установки. Существующие заказы сохраняют свои позиции доставки.

Mercado Envios и Mercado Pago являются товарными знаками их соответствующих владельцев. Этот плагин не связан с Mercado Envios или Mercado Pago и не одобрен ими.