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

Требования

PrestaShop: 8.0–9.x.

PHP: 8.0 или новее. Модуль не устанавливается на более старых версиях PHP.

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

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

Установка

1. В админ-панели перейдите в Modules > Module Manager и нажмите Upload a module. Выберите ZIP-файл модуля.

2. По окончании загрузки нажмите Configure или позже найдите VibeFox Melhor Envio в списке модулей и нажмите Configure.

3. Вставьте лицензионный ключ VibeFox в License key в блоке лицензии в верхней части страницы Configure и нажмите Activate (см. раздел «Лицензионный ключ»).

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

При установке модуль создаёт перевозчика Melhor Envio с текстом срока доставки Delivery by the carriers of your Melhor Envio account. Перевозчик привязывается ко всем зонам и всем группам покупателей. Зоны, группы покупателей, срок доставки, логотип и ограничения по размерам можно изменить в Shipping > Carriers. Цены там не задавайте: цена всегда берётся из модуля.

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Melhor Envio > Configure. Они действуют для всех зон перевозчика. У каждого раздела своя кнопка Save, которая сохраняет всю страницу. Каждое сохранение также очищает кэш расчётов Melhor Envio и последнюю ошибку API.

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

General

Enable Melhor Envio shipping: включает или выключает перевозчика. Это тот же переключатель, что и статус перевозчика в Shipping > Carriers.

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

Tax: правило налога перевозчика или No tax. Цены Melhor Envio являются окончательными ценами перевозчика. Выберите No tax, если PrestaShop не должен добавлять к ним налог.

Melhor Envio API

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) для тестов. Используйте с ней токен песочницы. По умолчанию: выключено.

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

Origin CEP: CEP (8 цифр), откуда отправляются посылки, например 01310-100. Сохраняется в формате 00000-000. Без корректного CEP отправления расчёты не запрашиваются.

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». По умолчанию: включено.

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

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

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

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

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

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

Fallback price table: цена по стране и весу корзины. Нажмите Add country, чтобы добавить строку, и значок корзины, чтобы удалить строку. Выберите * Default в качестве страны для каждой страны, у которой нет своей строки. В каждой строке есть Price и колонки веса: XS до 1 кг, S 1-2 кг, M 2-3 кг, L 3-5 кг и XL свыше 5 кг. Пустая колонка или колонка с 0 использует Price. Принимаются как «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: скрывает перевозчика, если корзина весит меньше, в кг. 0 означает без ограничения.

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

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

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

Ignore shipping zones: предлагает перевозчика в указанных ниже странах, даже если он не привязан к их зонам. Пока опция включена, перевозчик привязан ко всем зонам, включая неактивные и созданные позже. Когда вы её выключаете, у перевозчика снова появляются его собственные зоны.

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

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

Debug log: записывает запросы к API и расчёт тарифов в logs/vfd_menv_debug.log.php в папке модуля. Файл нельзя открыть через веб. Ошибки записываются всегда, даже когда опция выключена. Токен никогда не попадает в журнал, а CEP покупателя сокращается до первых 5 цифр.

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

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

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

На шаге доставки PrestaShop запрашивает у модуля цену Melhor Envio. Учитываются только товары, которые требуют доставки: виртуальные товары не добавляют вес и не входят в промежуточную сумму. Модуль сначала проверяет условия: страны из Ignore shipping zones, вес корзины и минимальную сумму заказа.

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

При One option - the cheapest service перевозчик показывает цену самой дешёвой услуги и строку Delivery estimate: под перевозчиком, если включено Delivery time. При One option per service покупатель видит под перевозчиком Choose a delivery service: с переключателем для каждой услуги, её ценой и оценкой срока доставки. Выбор сохраняется сразу, цена перевозчика и сводка корзины обновляются. Если услуга больше не предлагается для адреса, покупатель видит This service is not available for your address any more. Please choose another one., и возвращается предыдущий выбор.

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

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

Если вы редактируете перевозчика в Shipping > Carriers после того, как с ним появились заказы, PrestaShop сохраняет его как новую версию перевозчика. Модуль автоматически переходит на новую версию.

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

Заказы

Когда заказ оформлен с актуальным расчётом, модуль сохраняет с заказом услугу Melhor Envio и её оценку срока доставки. На странице заказа в панели администратора отображается блок Melhor Envio с Melhor Envio service (с ID услуги) и Delivery estimate, чтобы вы знали, какую услугу покупать в Melhor Envio. Покупатель видит ту же информацию на странице своего заказа в аккаунте. В письме с подтверждением заказа они добавляются после названия перевозчика. Заказы с резервной ценой не имеют услуги. Существующие заказы не затрагиваются.

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

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Melhor Envio — первый блок на странице Modules > Module Manager > VibeFox Melhor Envio > Configure, над настройками. Вставьте ключ в License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой лицензия действует, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: presta-shipping-melhor-envio и ссылка 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.

Без действующего ключа перевозчик Melhor Envio не показывается покупателям при оформлении заказа, и расчёты не производятся. Витрина PrestaShop не знает, что вы вошли в бэк-офис, поэтому перевозчик скрыт и для вас: модуль можно настроить до покупки ключа, но нельзя проверить при оформлении заказа. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются.

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

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

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

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

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

Покупатель видит «The service could not be saved. Please try again.»: выбор не дошёл до магазина, например из-за сетевой ошибки. Покупатель может выбрать услугу снова. Услуга, выбранная в момент, когда покупатель нажимает Continue, тоже сохраняется.

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

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

Страница сообщает, что перевозчик Melhor Envio не найден: перевозчик был удалён в Shipping > Carriers. Сбросьте модуль в Modules > Module Manager, чтобы создать его заново.

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox Melhor Envio и выберите Uninstall. Лицензионный ключ и статус лицензии всегда удаляются. Кэш расчётов всегда удаляется. Если Remove data on uninstall включено, перевозчик удаляется (заказы сохраняют свою историю), восстанавливаются его собственные зоны, а настройки, выбор услуг в открытых корзинах и журнал удаляются. Если выключено, перевозчик только отключается, и все настройки сохраняются. При повторной установке модуля перевозчик получает статус, который был у него раньше. Услуги, сохранённые с заказами, всегда сохраняются.

Melhor Envio является товарным знаком его правообладателя. Этот модуль не аффилирован с Melhor Envio и не одобрен им.