VibeFox Melhor Envio for WooCommerce — Help

Requirements

WordPress: 5.8 or later.

WooCommerce: 7.0 or later, installed and active. The plugin refuses to activate without it.

PHP: 8.0 or later.

Melhor Envio account (for live quotes only): live quotes need an access token. In your Melhor Envio account open the access permissions page for tokens (Integrações > Permissões de acesso, melhorenvio.com.br/painel/gerenciar/tokens) and generate a token with the "shipping-calculate" permission. For testing, generate a token in the Melhor Envio sandbox (sandbox.melhorenvio.com.br/painel/gerenciar/tokens). Production and sandbox tokens are different. Tokens expire. There is no "connect" button: you paste the token into the settings. Without a token the method uses the fallback prices.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the vfd_melhor_envio folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Shipping > VibeFox Melhor Envio, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

5. Paste the access token, your contact e-mail and the origin CEP. If your store currency is not BRL, set BRL exchange rate. Optionally fill in the fallback price table (for example for Brazil) or a fallback cost.

6. Add a zone for Brazil in WooCommerce > Settings > Shipping > Shipping zones and add VibeFox Melhor Envio to it, or turn on Ignore shipping zones and choose countries.

Configuration

All settings are on one page: WooCommerce > Settings > Shipping > VibeFox Melhor Envio. They apply to every shipping zone. When you add the method to a zone, the zone window has only one field:

Title (zone): the name of this option at checkout. Leave it empty to use the global Name.

Warnings at the top of the page show an incomplete setup: an origin CEP that is not 8 digits, a missing contact e-mail, a missing BRL exchange rate, the last Melhor Envio API error with its date, or no token and no fallback price. Every time you save the settings, the cached quotes are cleared.

General

Enable/Disable: turns Melhor Envio shipping on or off in all zones at once.

Name: the shipping method name shown to customers at checkout. Default: Melhor Envio.

Tax status: Taxable adds WooCommerce tax to the shipping cost, None does not.

Melhor Envio API

Access token: the token of the environment selected below. It is never written to the log.

Sandbox: use the Melhor Envio sandbox (sandbox.melhorenvio.com.br) for testing. Use a sandbox token with it. Default: off.

Contact e-mail: a technical contact e-mail, sent to Melhor Envio with every request. Melhor Envio requires it from every integration.

Origin CEP: the CEP (8 digits) the parcels are shipped from, for example 01310-100. Without a valid origin CEP no quotes are requested.

Services: optional comma-separated Melhor Envio service IDs to quote, for example 1 = Correios PAC, 2 = Correios SEDEX, 17 = Correios Mini Envios, 3 = Jadlog .Package, 4 = Jadlog .Com. Leave empty to quote every service of your account.

Quotes at checkout: how the quotes are shown.

Delivery time: show the delivery estimate of Melhor Envio next to the name, for example "(3-5 business days)". Default: on.

Declared value: declare the product value (insurance) in quotes. When off, quotes are made without declared value: cheaper, but parcels are not insured. Default: on.

BRL exchange rate: Melhor Envio quotes in Brazilian reais. Only needed if your store currency is not BRL: enter the price of 1 BRL in your store currency, for example 0.17. Without it live quotes are not used. The declared value is converted to BRL with the same rate.

Default product weight (kg): used for products without a weight, both in quotes and for the weight limits. Default: 0.3.

Default product size (cm): length x width x height used for products without dimensions. Default: 16x11x5.

Fallback prices (in your store currency)

Fallback prices are used when there is no token, the destination CEP is missing or the API gives no quote (error, timeout, no coverage).

Fallback price table: price by country and cart weight. Click + Add country to add a row and the cross to remove one. Choose * Any country for every country without its own row. Each row has a Price and weight columns: XS up to 1 kg, S 1-2 kg, M 2-3 kg, L 3-5 kg and XL over 5 kg. An empty or 0 column uses Price. Both "9.99" and "9,99" are accepted. Values that are not numbers are reported after saving and ignored.

Fallback cost: used when the table has no price either. Leave it empty to hide the method in that case.

Fallback calculation: Per order charges the fallback price once. Per item (each item priced by its own weight x quantity) looks up the fallback price for the weight of each item (the default weight when it has none) and multiplies it by its quantity. This applies to fallback prices only. Melhor Envio quotes already include every item.

Availability

Min weight (kg): hide the method when the cart weighs less. 0 means no limit.

Max weight (kg): hide the method when the cart weighs more. Default: 30. 0 means no limit.

Minimum subtotal: show the method only if the cart subtotal (after discounts, before tax) is at least this amount. Leave empty to always show it.

Free shipping from: the cart subtotal from which shipping is free. With one option per service, only the cheapest service becomes free. Faster services keep their price. Leave empty to disable.

Excluded shipping classes: hide the method when the cart contains items from any of these WooCommerce shipping classes.

Ignore shipping zones: offer the method for the countries below even without adding it to a shipping zone.

Countries: the destination countries for that mode. Leave empty for all countries. This field is used only when Ignore shipping zones is on.

Advanced

Debug log: logs API requests and rate calculation to WooCommerce > Status > Logs (source vfd-melhor-envio). Errors are always logged, even with this option off. The token and customer addresses are never logged.

Remove data on uninstall: when on, deleting the plugin removes all plugin settings and zone methods. Deactivating the plugin never deletes settings.

How it works at checkout

When the customer enters a delivery address, WooCommerce asks the plugin for a rate. The plugin first checks the conditions: cart weight, minimum subtotal and excluded shipping classes.

For a delivery address in Brazil with an 8-digit CEP, the plugin sends Melhor Envio the origin and destination CEP and every shippable item with its weight, size, quantity and declared value, plus the service list if you set one. The quotes are converted to your store currency and sorted by price. The customer sees the cheapest service or one option per service, with the delivery estimate if it is turned on. If free shipping applies, the cheapest service costs 0.

Each quote is cached for 1 hour per parcel, CEP and environment, so the same cart does not trigger a new request. A failed call is remembered for 5 minutes, so an API outage does not slow down every checkout refresh. The API timeout is 12 seconds.

If there is no token, the address is outside Brazil or has no valid CEP yet, the BRL exchange rate is missing, or Melhor Envio returns an error or no service for the route, the fallback prices are used: the row of the country (or the * row), else the fallback cost. If free shipping applies, the method is shown at no cost even without a price. If there is no price at all, the method is hidden. The customer never sees an API error.

The method works on the classic checkout and on the Cart and Checkout blocks. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin calculates prices only. It does not buy or generate labels, add shipments to the Melhor Envio cart, track parcels, schedule pickups or send invoice (NF-e) data. It does not offer the selection of Jadlog, Azul or LATAM agencies (drop-off points) or the "own hand" and "receipt" extra services. Manage shipments in your Melhor Envio panel. Melhor Envio ships inside Brazil only. Other countries get the fallback prices only.

Orders

When the order is placed with a live quote, the service and the delivery estimate are saved on the order shipping line. They are shown on the order screen and in the order e-mails as Melhor Envio service and Delivery estimate, so you know which service to buy in Melhor Envio. Existing orders keep their shipping lines.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Shipping > VibeFox Melhor Envio. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, Melhor Envio is not shown to customers at checkout. Logged-in store managers still see it, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

Troubleshooting

Melhor Envio does not appear at checkout: check that the license is active, Enable/Disable is on, and the method is added to the zone of the customer's country (or Ignore shipping zones is on and the country is allowed). Check the warnings at the top of the settings page, the weight limits, Minimum subtotal and Excluded shipping classes. Without a token or a quote, the method needs a fallback price: a row in Fallback price table or a Fallback cost.

Only fallback prices are shown: turn on Debug log, reload the checkout and open WooCommerce > Status > Logs, source vfd-melhor-envio. Typical reasons: no token, an origin CEP that is not 8 digits, no BRL exchange rate for a store currency other than BRL, no destination CEP yet, or no service covers the route.

HTTP 401 or 403 in the log or the warnings: Melhor Envio rejected the access token. It is wrong, expired or revoked, or it belongs to the other environment. Generate a new token and check that Sandbox matches it.

Which price do customers see: with one option, the cheapest service returned by Melhor Envio. With one option per service, every service that serves the route. Per item applies to fallback prices only.

Quotes look outdated after a change: save the settings page. This clears the cached quotes.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps all settings. Only the quote cache is cleared. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin and the cached quotes are always removed. Settings and zone methods are removed only if Remove data on uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their shipping lines.

Melhor Envio is a trademark of its respective owner. This plugin is not affiliated with or endorsed by Melhor Envio.