VibeFox Melhor Envio for PrestaShop — Help
Requirements
PrestaShop: 8.0 to 9.x.
PHP: 8.0 or later. The module refuses to install on older PHP versions.
Melhor Envio account (for live quotes only): live quotes need an access token. In your Melhor Envio account open the token page (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. There is no "connect" button: you paste the token into the module settings. Without a token the carrier uses the fallback prices.
VibeFox license key: bought on vibefox.net. One key works on one domain.
Installation
1. In the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.
2. When the upload finishes, click Configure, or find VibeFox Melhor Envio in the module list later and click Configure.
3. Paste your VibeFox license key into License key in the license block at the top of the Configure page and click Activate (see License key).
4. Paste the access token, your contact e-mail and the origin CEP. If your shop default currency is not BRL, set BRL exchange rate. Optionally fill in the fallback price table (for example for Brazil) or a fallback cost. Click Save.
On install the module creates the Melhor Envio carrier with the delivery time text Delivery by the carriers of your Melhor Envio account. The carrier is assigned to all zones and all customer groups. You can change zones, customer groups, delivery time, logo and size limits in Shipping > Carriers. Do not set prices there: the price always comes from the module.
Configuration
All settings are on the module page: Modules > Module Manager > VibeFox Melhor Envio > Configure. They apply to every zone of the carrier. Each section has its own Save button, which saves the whole page. Every save also clears the cached Melhor Envio quotes and the last API error.
Warnings at the top of the page show an incomplete setup: an origin CEP that is empty or not 8 digits, a missing contact e-mail, a missing BRL exchange rate, the last Melhor Envio API error with its date, no token and no fallback price (then the carrier is never shown), or a shop weight or dimension unit the module does not know (it is then read as kg or cm). If a number field contains something that is not a number of 0 or more, Min weight is greater than Max weight, or Default product size is not in the form length x width x height, the page shows an error and nothing is saved.
General
Enable Melhor Envio shipping: turns the carrier on or off. This is the same switch as the carrier status in Shipping > Carriers.
Name: the carrier name shown to customers at checkout. Default: Melhor Envio. Required, 64 characters at most.
Tax: the tax rule of the carrier, or No tax. Melhor Envio prices are final carrier prices. Choose No tax if PrestaShop must not add tax to them.
Melhor Envio API
Access token: the token of the environment selected below. It is sent to Melhor Envio as a Bearer token. After saving, the field stays empty and shows A token is saved — leave empty to keep it. Type a new token only to change it. To delete the saved token, tick Remove the saved token and save. The token 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 in the User-Agent header of every request. Melhor Envio requires it from every integration. An invalid address is not saved, and a notice says so.
Origin CEP: the CEP (8 digits) the parcels are shipped from, for example 01310-100. It is saved in the form 00000-000. 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 at checkout, 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 shop default currency is not BRL: enter the price of 1 BRL in your default currency, for example 0.17. Without it live quotes are not used. The value must be greater than 0. The declared value is converted to BRL with the same rate. If your default currency is BRL, the field shows Store currency is BRL.
Default product weight: in kg, used for products without a weight, both in quotes and for the weight limits. Must be greater than 0. Default: 0.3.
Default product size: length x width x height in cm, used for products without dimensions. Default: 16x11x5.
Fallback prices (in your shop default 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 trash icon to remove one. Choose * Default as the 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 carrier 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. If one item has no price, the carrier is hidden. This applies to fallback prices only. Melhor Envio quotes already include every item.
Availability
Min weight: hide the carrier when the cart weighs less, in kg. 0 means no limit.
Max weight: hide the carrier when the cart weighs more, in kg. Default: 30. 0 means no limit. An empty field means 30 kg in the zones of the carrier, and no limit only for the countries of Ignore shipping zones outside them.
Minimum subtotal: show the carrier only if the cart subtotal (products that need shipping, 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.
Ignore shipping zones: offer the carrier for the countries below even if it is not assigned to their zones. While this is on, the carrier is linked to all zones, including inactive zones and zones created later. When you switch it off, the carrier gets its own zones back.
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: writes API requests and the rate calculation to logs/vfd_menv_debug.log.php in the module folder. The file cannot be opened from the web. Errors are always logged, even with this option off. The token is never logged and the customer CEP is shortened to its first 5 digits.
Log: shows the size and the latest entries of the debug log. Click Clear log to empty it.
Remove data on uninstall: when on, uninstalling the module deletes all module settings, the carrier and the log. When off, everything is kept for a re-install. The quote cache is always removed. The services saved with orders are order history and are kept.
How it works at checkout
At the shipping step PrestaShop asks the module for the Melhor Envio price. Only products that need shipping count: virtual products add no weight and are not included in the subtotal. The module first checks the conditions: the countries of Ignore shipping zones, cart weight and minimum subtotal.
For a delivery address in Brazil with an 8-digit CEP, the module 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 default currency and sorted by price, then shown in the customer's cart currency. If free shipping applies, the cheapest service costs 0.
With One option - the cheapest service the carrier shows the price of the cheapest service, and the line Delivery estimate: under the carrier if Delivery time is on. With One option per service the customer sees Choose a delivery service: under the carrier, with one radio button per service, its price and the delivery estimate. The choice is saved at once, and the carrier price and the cart summary are updated. If the service is no longer offered for the address, the customer sees This service is not available for your address any more. Please choose another one. and the previous choice comes back.
Each quote is cached for 1 hour per parcel, CEP, token 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 carrier is shown at no cost even without a price. If there is no price at all, the carrier is hidden. The customer never sees an API error.
If you edit the carrier in Shipping > Carriers after it has orders, PrestaShop saves it as a new carrier version. The module follows the new version automatically.
The module 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 an order is placed with a live quote, the module saves the Melhor Envio service and its delivery estimate with the order. The back-office order page shows a Melhor Envio block with Melhor Envio service (with the service ID) and Delivery estimate, so you know which service to buy in Melhor Envio. The customer sees the same information on the order page in their account. In the order confirmation e-mail they are added after the carrier name. Orders placed with a fallback price have no service. Existing orders are not affected.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Melhor Envio is the first block on Modules > Module Manager > VibeFox Melhor Envio > Configure, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this shop. Below them are the line Product: presta-shipping-melhor-envio and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office language (English and Russian are included).
If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the shop address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.
One key works on one domain: the domain of the main shop, also in a multistore setup. Removing the key from the shop does not free its domain slot. Free the slot in your vibefox.net account.
Without an active key, the Melhor Envio carrier is not shown to customers at checkout and no rate is calculated. The PrestaShop storefront does not know that you are logged in to the back office, so the carrier is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in Modules > Module Manager on the Alerts tab. Existing orders are not affected.
When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module always removes the license key and license status.
Troubleshooting
Melhor Envio does not appear at checkout: check that the license is active and Enable Melhor Envio shipping is on. In Shipping > Carriers check that the carrier covers the zone of the customer's country and the customer's group, or turn on Ignore shipping zones and check Countries. Check the warnings at the top of the module page, the weight limits and Minimum subtotal. Without a token or a quote, the carrier needs a fallback price: a row in Fallback price table or a Fallback cost. Products can also be limited to certain carriers in the product page.
Only fallback prices are shown: turn on Debug log, reload the checkout and look at the Log field on the module page. Typical reasons: no token, an origin CEP that is not 8 digits, no BRL exchange rate for a default 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.
The customer sees "The service could not be saved. Please try again.": the choice did not reach the shop, for example because of a network error. The customer can choose the service again. The service selected when the customer clicks Continue is saved as well.
Tax is added to the Melhor Envio price: set Tax to No tax.
Quotes look outdated after a change: click Save on the module page. This clears the cached quotes.
The page says the Melhor Envio carrier was not found: the carrier was deleted in Shipping > Carriers. Reset the module in Modules > Module Manager to create it again.
Uninstall
Go to Modules > Module Manager, open the menu next to VibeFox Melhor Envio and choose Uninstall. The license key and the license status are always removed. The quote cache is always removed. If Remove data on uninstall is on, the carrier is deleted (orders keep their history), its own zones are restored, and the settings, the service choices of open carts and the log are removed. If it is off, the carrier is only disabled and all settings are kept. Installing the module again gives the carrier back the status it had before. The services saved with orders are always kept.
Melhor Envio is a trademark of its respective owner. This module is not affiliated with or endorsed by Melhor Envio.