VibeFox Melhor Envio for OpenCart — Помощь

Требования

OpenCart: 3.0.x (проверено на 3.0.5.0) или 4.0.2 и новее (проверено на 4.1.0.3).

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

Аккаунт Melhor Envio (только для расчётов в реальном времени): расчёты в реальном времени требуют токен доступа. В аккаунте Melhor Envio откройте страницу токенов (melhorenvio.com.br/painel/gerenciar/tokens) и создайте токен с разрешением «shipping-calculate». Для тестов создайте токен в песочнице Melhor Envio (sandbox.melhorenvio.com.br). Токены для рабочей среды и песочницы различаются. Кнопки «подключить» нет: токен вставляется в настройки расширения. Без токена способ доставки использует резервные тарифы.

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

Установка

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

OpenCart 3

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

2. Перейдите в Extensions > Extensions и выберите тип расширений Shipping. Найдите VibeFox Melhor Envio и нажмите Install (зелёная кнопка +).

3. Нажмите Edit (кнопка с карандашом), чтобы открыть страницу настроек.

4. Вставьте лицензионный ключ VibeFox в License key в блоке лицензии вверху страницы Edit и нажмите Activate (см. Лицензионный ключ).

5. Вставьте токен доступа, контактный e-mail и CEP отправления. Если валюта по умолчанию вашего магазина не BRL, укажите BRL exchange rate. По желанию заполните таблицу резервных тарифов (например, для Бразилии) или резервную стоимость. Включите Enable Melhor Envio shipping и нажмите Save.

OpenCart 4

1. В админ-панели перейдите в Extensions > Installer, нажмите Upload и выберите файл vfd_melhor_envio.ocmod.zip. Не переименовывайте файл: OpenCart 4 берёт код расширения из имени файла, и переименованный пакет не работает.

2. Пакет появится в списке установленных расширений на этой же странице. Нажмите рядом с ним Install (зелёная кнопка +).

3. Перейдите в Extensions > Extensions и выберите тип расширений Shipping. Найдите VibeFox Melhor Envio, нажмите Install (зелёная кнопка +), затем Edit (кнопка с карандашом).

4. Введите лицензионный ключ и настройки, как в шагах 4 и 5 для OpenCart 3. Страница настроек и её поля одинаковы в обеих версиях.

После установки способ доставки выключен, пока вы не включите Enable Melhor Envio shipping и не сохраните настройки. Если вы устанавливаете расширение заново после удаления, используются сохранённые настройки.

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Shipping > VibeFox Melhor Envio > Edit. Разделы перечислены слева. Одна кнопка Save сохраняет всю страницу без перезагрузки. Каждое сохранение также очищает кэш расчётов Melhor Envio и последнюю ошибку API. Сохранять настройки могут только администраторы с правом изменения для этого расширения.

Предупреждения в верхней части страницы (и после каждого сохранения) показывают неполную настройку: пустой CEP отправления или не из 8 цифр, отсутствующий контактный e-mail, отсутствующий курс BRL, отсутствие токена и резервной цены (тогда способ доставки никогда не показывается), последнюю ошибку API Melhor Envio с датой (если токен сохранён), либо магазин без весового класса «kg» или класса длины «cm» (тогда единицы переводятся по названию, а неизвестные единицы считаются кг или см). Если Name пусто, слишком длинное или содержит один из символов < > ; = # { }, в поле с числом введено что-то, что не является числом от 0 и выше, Min weight больше Max weight, или Default product size не имеет вида длина x ширина x высота, страница показывает ошибку и ничего не сохраняется.

Общие

Настройки применяются ко всем геозонам. Способ можно ограничить геозоной в разделе Availability. Цена всегда берётся из расширения.

Enable Melhor Envio shipping: показывает или скрывает Melhor Envio при оформлении заказа. По умолчанию: off.

Name: название способа доставки, которое покупатели видят в корзине и при оформлении заказа. По умолчанию: Melhor Envio. Обязательное поле, не более 64 символов.

Sort order: место Melhor Envio среди способов доставки при оформлении заказа. Целое число.

API Melhor Envio

Access token: токен выбранной ниже среды. Он отправляется в Melhor Envio как Bearer-токен. После сохранения поле остаётся пустым и показывает A token is saved — leave empty to keep it. Вводите новый токен, только если хотите его заменить. Чтобы удалить сохранённый токен, отметьте Remove the saved token и сохраните. Токен никогда не записывается в журнал.

Sandbox: используйте песочницу Melhor Envio (sandbox.melhorenvio.com.br) для тестов. С ней используйте токен песочницы. По умолчанию: off.

Contact e-mail: технический контактный e-mail, который передаётся в Melhor Envio в заголовке User-Agent каждого запроса, например tech@example.com. Melhor Envio требует его от каждой интеграции. Некорректный адрес не сохраняется, и об этом выводится уведомление.

Origin CEP: CEP (8 цифр), из которого отправляются посылки, например 01310-100. В OpenCart нет почтового индекса магазина, поэтому для расчётов в реальном времени нужно это поле. CEP, не состоящий из 8 цифр, сохраняется с уведомлением, но расчёты не запрашиваются.

Services: необязательный список ID услуг Melhor Envio через запятую для расчёта, например 1 = Correios PAC, 2 = Correios SEDEX, 17 = Correios Mini Envios, 3 = Jadlog .Package, 4 = Jadlog .Com. Оставьте пустым, чтобы рассчитывать все услуги аккаунта.

Quotes at checkout: как показываются расчёты.

Delivery time: показывать срок доставки Melhor Envio рядом с названием, например «(3-5 business days)». По умолчанию: on.

Declared value: объявлять стоимость товаров (страхование) в расчётах. Когда выключено, расчёты делаются без объявленной стоимости: дешевле, но посылки не застрахованы. По умолчанию: on.

BRL exchange rate: Melhor Envio рассчитывает стоимость в бразильских реалах. Нужно, только если валюта по умолчанию вашего магазина не BRL: введите цену 1 BRL в вашей валюте по умолчанию, например 0.17. Без него расчёты в реальном времени не используются. Значение должно быть больше 0. Объявленная стоимость переводится в BRL по тому же курсу. Если валюта по умолчанию — BRL, поле сообщает, что цены Melhor Envio используются как есть.

Default product weight (kg): используется для товаров без веса, как в расчётах, так и для ограничений по весу. Должен быть больше 0. По умолчанию: 0.3.

Default product size (cm): длина x ширина x высота, используется для товаров без размеров. По умолчанию: 16x11x5.

Резервные тарифы (в валюте по умолчанию вашего магазина)

Резервные тарифы используются, когда нет токена, не указан CEP назначения или API не возвращает расчёт (ошибка, таймаут, отсутствие покрытия).

Fallback price table: цена по стране и весу корзины, без налога. Нажмите Add country, чтобы добавить строку (новая строка начинается с Бразилии), и кнопку удаления, чтобы убрать строку. Выберите * Any country для всех стран без собственной строки. В каждой строке есть Price и весовые колонки: XS до 1 кг, S от 1 до 2 кг, M от 2 до 3 кг, L от 3 до 5 кг и XL свыше 5 кг. Пустая колонка или 0 использует Price, а Price 0 означает бесплатную доставку. Принимаются как «9.99», так и «9,99». Значения, которые не являются числами, сообщаются после сохранения и игнорируются. Строки без какой-либо цены удаляются.

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

Fallback calculation: Per order (по умолчанию) берёт резервную цену один раз. Per item (each item priced by its own weight x quantity) ищет резервную цену для веса каждого товара (вес по умолчанию, если у товара его нет) и умножает её на количество. Это относится только к резервным тарифам. Расчёты Melhor Envio уже включают все товары.

Доступность

Min weight (kg): скрывает способ доставки, когда корзина весит меньше. 0 означает без ограничения (по умолчанию).

Max weight (kg): скрывает способ доставки, когда корзина весит больше. По умолчанию: 30. 0 означает без ограничения. Пустое поле означает 30 кг или отсутствие ограничения, если включён Ignore shipping zones.

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

Free shipping from: промежуточная сумма корзины, начиная с которой доставка бесплатна. При варианте «по одному на услугу» бесплатной становится только самая дешёвая услуга. Более быстрые услуги сохраняют свою цену. Оставьте поле пустым, чтобы отключить.

Tax class: класс налога, который добавляется к стоимости доставки, или No tax (по умолчанию). Цены Melhor Envio — окончательные тарифы перевозчиков. Выберите No tax, если OpenCart не должен добавлять к ним налог.

Geo zone: предлагать Melhor Envio только для адресов в этой геозоне. All zones (по умолчанию) означает без ограничения. Геозоны управляются в разделе System > Localisation > Geo Zones. Геозона не проверяется, когда включён Ignore shipping zones.

Доступность без зон доставки

Обычно способ предлагается в геозоне, выбранной в Availability (во всех зонах, если ни одна не выбрана).

Ignore shipping zones: предлагать способ для стран, перечисленных ниже, независимо от выбранной геозоны. В этом режиме геозона не проверяется.

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

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

Debug log: записывает запросы к API и расчёт тарифов в файл storage/logs/vfd_menv_debug.log.php (в OpenCart 4 — system/storage/logs/vfd_menv_debug.log.php). Файл нельзя прочитать из веба. Ошибки API записываются всегда, даже если эта опция выключена. Токен никогда не записывается, а CEP покупателя сокращается до первых 5 цифр. Когда файл достигает 5 МБ, он переносится в vfd_menv_debug.old.log.php, и начинается новый журнал.

Log: показывает размер и последние записи отладочного журнала. Нажмите Clear log, чтобы очистить его.

Remove data on uninstall: когда включено, удаление расширения стирает все его настройки и журнал. Когда выключено (по умолчанию), они сохраняются для повторной установки. Кэш расчётов всегда удаляется. Услуги, сохранённые с заказами, являются историей заказов и сохраняются.

Импорт / Экспорт

Export: нажмите Download JSON, чтобы сохранить настройки в файл JSON. Токен доступа не экспортируется.

Import: вставьте ранее экспортированный JSON и нажмите Import, чтобы восстановить настройки, например в другом магазине. Значения проверяются так же, как при обычном сохранении. Сохранённый токен доступа остаётся.

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

Когда OpenCart показывает способы доставки, он запрашивает у расширения цену Melhor Envio. Если задана Geo zone и адрес находится вне её, Melhor Envio не предлагается. При Ignore shipping zones геозона не проверяется: Melhor Envio предлагается только когда страна входит в Countries (или Countries пуст). Учитываются только товары, у которых Requires Shipping установлено в Yes: другие товары не добавляют вес и не входят в промежуточную сумму. Затем расширение проверяет вес корзины и минимальную промежуточную сумму.

Для адреса доставки в Бразилии с CEP из 8 цифр расширение отправляет в Melhor Envio CEP отправления и назначения, а также каждый товар, который можно доставить, с его весом, размерами, количеством и объявленной стоимостью, плюс список услуг, если вы его задали. Поле Model товара передаётся как ID товара. Услуги с ошибкой или без цены пропускаются. Расчёты переводятся в валюту по умолчанию, округляются до её знаков после запятой, сортируются по цене и показываются в валюте покупателя с налогом выбранного Tax class. Если применяется бесплатная доставка, самая дешёвая услуга стоит 0.

При One option - the cheapest service покупатель видит один вариант, например Melhor Envio (6-7 business days). При One option per service покупатель видит по одному варианту на услугу, например Melhor Envio: Correios SEDEX (1-2 business days). Срок доставки добавляется, только если включён Delivery time.

Каждый расчёт кэшируется на 1 час, поэтому одна и та же корзина не вызывает новый запрос. Неудачный вызов запоминается на 5 минут, чтобы сбой API не замедлял каждое обновление оформления заказа. Таймаут API — 12 секунд.

Если нет токена, адрес находится вне Бразилии или ещё не имеет корректного CEP, отсутствует курс BRL, либо Melhor Envio возвращает ошибку или не находит услуг для маршрута, используются резервные тарифы: строка страны (или строка *, если у страны нет своей строки), иначе резервная стоимость. Такой вариант называется просто так, как указано в Name. Если применяется бесплатная доставка, способ показывается бесплатно, даже без цены. Если цены нет вовсе, способ доставки скрывается. Покупатель никогда не видит ошибку API. Причина записывается в журнал.

В OpenCart 4 покупатель нажимает Choose в блоке способа доставки на странице оформления заказа и выбирает вариант Melhor Envio в окне Shipping method options. Варианты и цены такие же, как в OpenCart 3.

Расширение только рассчитывает стоимость. Оно не покупает и не создаёт этикетки, не добавляет отправления в корзину Melhor Envio, не отслеживает посылки, не назначает вызов курьера и не передаёт данные счёта-фактуры (NF-e). Оно не предлагает выбор отделений перевозчиков (пунктов сдачи). Управляйте отправлениями в панели Melhor Envio. Melhor Envio отправляет только внутри Бразилии. Для остальных стран доступны только резервные тарифы.

Заказы

OpenCart сохраняет название выбранного варианта как способ доставки заказа, поэтому услуга и срок доставки видны в письмах о заказе, в аккаунте покупателя и в разделе Sales > Orders.

Когда заказ оформляется с расчётом в реальном времени, расширение также сохраняет услугу Melhor Envio точно в таком виде, как её видел покупатель на шаге доставки, без нового запроса. На странице заказа в разделе Sales > Orders админ-панели показывается блок Melhor Envio с Melhor Envio service, Service ID и Delivery estimate, чтобы вы знали, какую услугу купить в Melhor Envio. Покупатель видит Melhor Envio service и Delivery estimate на странице заказа в своём аккаунте. У заказов, оформленных с резервной ценой, услуги нет. Существующие заказы не затрагиваются.

На OpenCart 4 блок Melhor Envio показывается над блоком History. OpenCart 4 ведёт один заказ на оформление и обновляет его каждый раз, когда покупатель подтверждает заказ снова: сохранённая услуга обновляется вместе с ним, а удаляется, когда покупатель переходит к другому способу доставки или когда заказу назначается резервная цена.

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

Расширение работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Melhor Envio — первый блок на Extensions > Extensions > Shipping > VibeFox Melhor Envio > Edit, над настройками. Введите ключ в License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой лицензия действует, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: opencart-shipping-melhor-envio и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт vibefox.net. Менять ключ могут только администраторы с правом Modify для этого расширения. Тексты блока следуют языку админ-панели (включены английский и русский).

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

Один ключ работает на одном домене: адрес магазина из конфигурации OpenCart. Удаление ключа из магазина не освобождает его место для домена. Освободите место в своём аккаунте vibefox.net.

Без действующего ключа способ доставки Melhor Envio не показывается покупателям при оформлении заказа, и расчёт не выполняется. Администратор, вошедший в админ-панель в том же браузере, по-прежнему видит способ доставки в магазине с пометкой (unlicensed — visible to admins only), поэтому вы можете настроить и проверить расширение до покупки ключа. В OpenCart 4 этот предпросмотр недоступен: магазин не видит вход администратора, поэтому без действующего ключа способ доставки скрыт для всех. После того как вы один раз откроете страницу Edit, в панели администратора Dashboard появляется напоминание. Закройте его кнопкой ×, чтобы скрыть его на 7 дней. Существующие заказы не затрагиваются.

Когда срок лицензии истекает, расширение продолжает работать, но для обновлений и поддержки нужно продление. Статус проверяется снова автоматически, когда вы открываете админ-панель Dashboard или страницу Edit: раз в день в первые 14 дней после ввода ключа, затем раз в неделю. Задание cron не нужно. Удаление расширения всегда удаляет лицензионный ключ и статус лицензии.

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

Melhor Envio не появляется при оформлении заказа: проверьте, что лицензия действует и включён Enable Melhor Envio shipping. Проверьте Geo zone или включите Ignore shipping zones и проверьте Countries. Посмотрите предупреждения в верхней части страницы расширения, ограничения по весу и Minimum subtotal. Без токена или расчёта способу доставки нужна резервная цена: строка в Fallback price table или Fallback cost. Проверьте, что у товаров Requires Shipping установлено в Yes.

Показываются только резервные тарифы: включите Debug log, перезагрузите оформление заказа и посмотрите поле Log на странице расширения. Обычные причины: нет токена, CEP отправления не из 8 цифр, нет BRL exchange rate при валюте по умолчанию, отличной от BRL, CEP назначения ещё не указан, или ни одна услуга не обслуживает маршрут.

HTTP 401 или 403 в журнале или предупреждениях: Melhor Envio отклонил токен доступа. Он неверный, истёк или отозван, либо относится к другой среде. Создайте новый токен и проверьте, что Sandbox соответствует ему.

К цене Melhor Envio добавляется налог: установите Tax class в No tax.

Расчёты выглядят устаревшими после изменения: нажмите Save на странице расширения. Это очистит кэш расчётов.

Страница пишет "Warning: You do not have permission to modify VibeFox Melhor Envio!": ваша группа администраторов может только просматривать настройки. Дайте группе право изменения для extension/shipping/vfd_melhor_envio (OpenCart 3) или extension/vfd_melhor_envio/shipping/vfd_melhor_envio (OpenCart 4) в разделе System > Users > User Groups.

Для разработчиков: адрес API расчётов Melhor Envio можно заменить настройкой vfd_menv_api_url (для тестов); на странице настроек для неё нет поля.

Удаление

Перейдите в Extensions > Extensions, выберите тип Shipping и нажмите Uninstall (красная кнопка −) рядом с VibeFox Melhor Envio. Лицензионный ключ и статус лицензии этого расширения всегда удаляются. OpenCart всегда сбрасывает Enable Melhor Envio shipping, Sort order, Tax class и Geo zone. Кэш расчётов всегда удаляется. Если Remove data on uninstall включено, удаляются также остальные настройки и отладочный журнал. Если выключено, они сохраняются и используются снова при повторной установке расширения. Услуги, сохранённые с заказами, всегда остаются, а существующие заказы сохраняют свой способ доставки и стоимость.

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

Melhor Envio — торговая марка её владельца. Это расширение не связано с Melhor Envio и не одобрено Melhor Envio.