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

Требования

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

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

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

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

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

Установка

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

2. Нажмите Activate.

3. Откройте настройки: WooCommerce > Settings > Shipping > VibeFox Melhor Envio или нажмите Settings под названием плагина на странице «Плагины».

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

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

6. Добавьте зону для Бразилии в WooCommerce > Settings > Shipping > Shipping zones и добавьте в неё VibeFox Melhor Envio, либо включите Ignore shipping zones и выберите страны.

Настройка

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

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

Предупреждения вверху страницы показывают неполную настройку: CEP отправления не из 8 цифр, не указан контактный e-mail, не задан курс BRL, последняя ошибка API Melhor Envio с датой или отсутствие токена и резервной цены. При каждом сохранении настроек кэш расчётов очищается.

Общие

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

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

Tax status: Taxable добавляет налог WooCommerce к стоимости доставки, None — не добавляет.

API Melhor Envio

Access token: токен выбранной ниже среды. Он никогда не записывается в журнал.

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

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

Origin CEP: CEP (8 цифр), с которого отправляются посылки, например 01310-100. Без корректного 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. Без курса актуальные расчёты не используются. Объявленная стоимость переводится в BRL по тому же курсу.

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

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

Fallback prices (в валюте вашего магазина)

Резервные цены используются, когда нет токена, не указан 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. Принимаются как «9.99», так и «9,99». Значения, которые не являются числами, выводятся после сохранения и игнорируются.

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

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

Availability

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

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

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

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

Excluded shipping classes: скрывает способ доставки, если в корзине есть товары из любого из этих классов доставки WooCommerce.

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

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

Advanced

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

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

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

Когда покупатель вводит адрес доставки, WooCommerce запрашивает у плагина тариф. Плагин сначала проверяет условия: вес корзины, минимальную сумму и исключённые классы доставки.

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

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

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

Способ работает в классическом оформлении заказа и в блоках «Корзина» и «Оформление заказа». Он совместим с HPOS (хранилищем заказов высокой производительности WooCommerce).

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

Заказы

Когда заказ оформлен с актуальным расчётом, услуга и оценка срока доставки сохраняются в строке доставки заказа. Они отображаются на экране заказа и в письмах о заказе как Melhor Envio service и Delivery estimate, чтобы вы знали, какую услугу оформить в Melhor Envio. Существующие заказы сохраняют свои строки доставки.

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

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

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

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

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

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

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

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

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

Какую цену видят покупатели: при одном варианте — самую дешёвую услугу из ответа Melhor Envio. При варианте на каждую услугу — каждую услугу, обслуживающую маршрут. Per item применяется только к резервным ценам.

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

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

Удаление

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

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