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 и не поддерживается ими.