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 и не одобрен ими.