VibeFox Melhor Envio for Adobe Commerce — Guida
Requirements
Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.
PHP: 8.1 to 8.4, with the cURL, JSON and mbstring extensions.
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. You also need the CEP your parcels are shipped from. Without a token the method uses the fallback prices.
VibeFox license key: bought on vibefox.net. One key works on one domain.
Installation
The module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.
1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-melhor-envio-shipping. Without Composer: unpack the ZIP file into app/code/Vibefox/MelhorEnvioShipping/, so that registration.php is directly in that folder.
2. Run bin/magento module:enable Vibefox_MelhorEnvioShipping and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.
3. In the Admin go to Stores > Configuration > Sales > Delivery Methods and open VibeFox Melhor Envio. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).
4. Paste the access token, your contact e-mail and the origin CEP. If the base currency of your store is not BRL, set BRL exchange rate. Optionally fill in the fallback price table (for example for Brazil) or a fallback cost. Set Enable Melhor Envio to Yes and click Save Config.
The module adds the Melhor Envio shipping method to Magento. With the cheapest service or a fallback price, customers see it as Melhor Envio - Shipping (method title and method name). It is off after installation (Enable Melhor Envio = No).
Configuration
All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox Melhor Envio, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Method title and Method name also for a store view. Remove data on uninstall is read from the Default Config only. Save Config saves the whole page and clears the cached Melhor Envio quotes. Amounts accept "9.99" and "9,99".
If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Method title, longer than 64 characters or with one of the characters < > ; = # { }; an empty Method name or one longer than 64 characters; a Sort order that is not a whole number; a number field that does not contain a number of 0 or more; a BRL exchange rate or Default product weight of 0; a Minimum weight (kg) greater than the Maximum weight (kg); a Default product size that is not in the form length x width x height.
Some values are saved with a warning instead: an invalid Contact e-mail is not saved (Melhor Envio: the contact e-mail is not valid and was not saved.), an Origin CEP that does not have 8 digits is saved but reported (Melhor Envio: the origin CEP must have 8 digits.), and cells of the fallback price table that are not numbers of 0 or more are ignored and listed.
While Enable Melhor Envio is Yes, warnings after saving remind you of settings that stop live quotes or hide the method: an origin CEP that is empty or not 8 digits, a missing contact e-mail, a missing BRL exchange rate when the base currency is not BRL, or no access token and no fallback price (then the method is never shown). The warnings are shown only while the method is enabled, because the Delivery Methods page is shared by all shipping methods.
General
Enable Melhor Envio: shows or hides the method at checkout. Default: No.
Method title: the carrier name shown in the cart and at checkout. Default: Melhor Envio. Required, at most 64 characters, without < > ; = # { }.
Method name: shown after the method title, as "Method title - Method name", for fallback prices and for the cheapest service. Default: Shipping. Required, at most 64 characters. With one option per service, the name of the service is shown instead.
Sort order: the position among the shipping methods at checkout. A whole number, negative numbers are allowed.
Melhor Envio API
API status: while the method is enabled and a token is saved, shows the last Melhor Envio API error (Last Melhor Envio API error: with the message) for up to one day. A successful quote or Save Config removes it.
Access token: the token of the environment selected below, with the "shipping-calculate" permission. It is sent to Melhor Envio as a Bearer token and never written to the log. Magento stores it encrypted and shows only a mask after saving. Leave the mask as it is to keep the saved token, type a new value to change it. To delete the saved token, clear the field and click Save Config. Only the fallback prices are used then.
Sandbox: use the Melhor Envio sandbox (sandbox.melhorenvio.com.br) for testing. Use a sandbox token with it. Default: No.
Contact e-mail: a technical contact e-mail, sent to Melhor Envio in the User-Agent header of every request. An invalid address is not saved.
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 live 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 business-day estimate of Melhor Envio after the option name, for example "(3-5 business days)". Default: Yes.
Declared value: declare the product unit values (after discounts, in BRL) as insurance value in quotes. When No, quotes are made without declared value: cheaper, but parcels are not insured. Default: Yes.
BRL exchange rate: Melhor Envio quotes in Brazilian reais. Only needed if the base currency of your store is not BRL: enter how many units of the base currency 1 BRL is worth, 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 base currency is BRL, the rate is always 1.
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, for example 16x11x5. Magento has no standard product dimensions, so this size is sent for every product. Default: 16x11x5.
Fallback prices (in the base currency of your store, tax excluded)
Fallback prices are used when there is no token, the destination is outside Brazil or has no valid CEP yet, the BRL exchange rate 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 Delete to remove one. Choose * All other countries as the country for every country without its own row. Each row has a Price and weight columns: XS up to 1 kg, S up to 2 kg, M up to 3 kg, L up to 5 kg and XL over 5 kg. An empty or 0 column uses Price; a Price of 0 means free shipping. The first row of the country wins. If that row has no price for the weight, Fallback cost is used, not the * All other countries row.
Fallback calculation: Per order charges the fallback price once. Per item 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 method is hidden. This applies to fallback prices only. Melhor Envio quotes already include every item.
Fallback cost: used when there is no live quote and the table has no price. Leave it empty to hide the method in that case.
Availability
Minimum weight (kg): hide the method when the cart weighs less. 0 means no minimum.
Maximum weight (kg): hide the method when the cart weighs more. Default: 30. 0 means no limit, an empty field means 30 kg.
Minimum subtotal: show the method only if the cart subtotal (physical products after discounts, before tax, in the base currency) is at least this amount. Leave empty to always show it.
Free shipping from: the cart subtotal from which shipping is free. With live quotes, only the cheapest service becomes free; other services keep their price. With fallback prices the method costs 0, even when there is no price. Leave empty to disable. A Magento cart price rule with free shipping makes every offered service free.
Ship to Applicable Countries: All Allowed Countries offers Melhor Envio for every country your store allows, Specific Countries only for the countries below.
Ship to Specific Countries: the destination countries for Specific Countries. Melhor Envio quotes Brazil only; other countries use the fallback prices.
Product weights are converted to kg from the weight unit of your store (Stores > Configuration > General > General > Locale Options > Weight Unit, lbs or kgs). Magento products have no standard dimensions, so volumetric weight is not calculated from product attributes. The module has no tax setting of its own: if your store taxes shipping, set Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping.
Advanced
Debug log: writes API requests and the rate calculation to var/log/vfd_menv_debug.log.php in the Magento folder. The file cannot be opened from the web. API errors are always logged, even when this is off. Tokens and full destination CEPs are never logged.
Log: shows the size and the latest entries of the log. Click Clear log to empty it.
Remove data on uninstall: when Yes, uninstalling the module with its data deletes the Melhor Envio settings and the log (see Uninstall). The license data and the cached quotes are always removed. The Melhor Envio data of orders is never deleted.
How it works at checkout
At the shipping step Magento asks the module for the Melhor Envio price. Only products that need shipping count: virtual and downloadable products add no weight and are not included in the subtotal. Bundle products shipped separately are counted item by item. The module first checks the countries, the 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 from BRL to your base currency and sorted by price; Magento then shows them in the customer's currency and adds tax on shipping if your store charges it. If free shipping applies, the cheapest service costs 0.
With One option - the cheapest service the customer sees one option, for example Melhor Envio - Shipping (3-5 business days). With One option per service the customer sees one option per service in the standard list of shipping methods, each with its price and, if Delivery time is Yes, the delivery estimate. The checkout has no extra widget: the choice is a normal Magento shipping method.
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 live quote, the fallback prices are used: the row of the country (or the * All other countries 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 reason is written to the log.
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 Melhor Envio, the module saves the quote the order was placed with, without a new request to Melhor Envio. The shipping method of the order shows the option the customer chose, for example Melhor Envio - Correios SEDEX.
On the admin order page (Sales > Orders > View, Information tab) the Melhor Envio shipping block shows Service, Service ID, Delivery estimate, Price source (api for a live quote, fixed for the price table, fallback for the fallback cost, free for free shipping), Quoted price (BRL), Price in base currency and Base currency, so you know which service to buy in Melhor Envio. Orders placed with a fallback price have no service.
The customer sees Melhor Envio service and Delivery estimate on the order page in their account, or on the Orders and Returns page for guests, when the order was placed with a live quote. The blocks also work for older orders and when the module is switched off. 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 row of the VibeFox Melhor Envio group in Stores > Configuration > Sales > Delivery Methods, 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 store. Below them are the line Product: magento-shipping-melhor-envio and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Delivery Methods configuration section can change the key. The texts of the block follow the Admin interface locale (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 store 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 default store view, also when the installation has several websites or stores. Removing the key from the store does not free its domain slot. Free the slot in your vibefox.net account.
Without an active key, the Melhor Envio method is not shown to customers at checkout and no rate is calculated. The Magento storefront does not know that you are logged in to the Admin, so the method 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 the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. 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: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data 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 is Yes for the website of the store. Check Ship to Applicable Countries and Ship to Specific Countries, the warnings after Save Config, the weight limits and Minimum subtotal. 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 look at the Log field in the Advanced section. Typical reasons: no token, an origin CEP that is not 8 digits, no BRL exchange rate for a base currency other than BRL, no destination CEP yet, or no service covers the route.
HTTP 401 or 403 in the log or in API status: 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.
Tax is added to the Melhor Envio price: Melhor Envio prices are final carrier prices. If Magento must not add tax to them, do not set a taxable class in Tax Class for Shipping.
Quotes look outdated after a change: click Save Config on the Delivery Methods page. This clears the cached quotes.
The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.
Uninstall
Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:
Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_MelhorEnvioShipping. It removes the data and the code.
Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_MelhorEnvioShipping to remove the data, then bin/magento module:disable Vibefox_MelhorEnvioShipping, delete the folder app/code/Vibefox/MelhorEnvioShipping and run bin/magento setup:upgrade.
The license key, the license status and the cached quotes are always removed. If Remove data on uninstall is Yes, the Melhor Envio settings and the log are removed too. If it is No, the settings are kept for a re-install. The Melhor Envio data of orders (service, delivery estimate and prices) is always kept.
Melhor Envio is a trademark of its respective owner. This module is not affiliated with or endorsed by Melhor Envio.