VibeFox Melhor Envio for OpenCart — Help

Requirements

OpenCart: 3.0.x (tested on 3.0.5.0) or 4.0.2 and later (tested on 4.1.0.3).

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 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). Production and sandbox tokens are different. There is no "connect" button: you paste the token into the extension settings. Without a token the method uses the fallback prices.

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

Installation

The download is one zip file with the packages for both OpenCart versions. Unpack it on your computer. It contains README.txt, the OpenCart 3 package vfd_melhor_envio-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_melhor_envio.ocmod.zip. Install only the package for your OpenCart version. The license key is the same for both versions.

OpenCart 3

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_melhor_envio-oc3-(version).ocmod.zip. The extension adds no OCMOD modifications, so you do not need to refresh Extensions > Modifications. Instead of the Installer, you can copy the contents of the upload folder of this package into the root folder of your store.

2. Go to Extensions > Extensions and choose the extension type Shipping. Find VibeFox Melhor Envio and click Install (the green + button).

3. Click Edit (the pencil button) to open the settings page.

4. Paste your VibeFox license key into License key in the license block at the top of the Edit page and click Activate (see License key).

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

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_melhor_envio.ocmod.zip. Do not rename the file: OpenCart 4 takes the extension code from the file name, and a renamed package does not work.

2. The package appears in the list of installed extensions on the same page. Click Install (the green + button) next to it.

3. Go to Extensions > Extensions and choose the extension type Shipping. Find VibeFox Melhor Envio, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key and the settings as in steps 4 and 5 for OpenCart 3. The settings page and its fields are the same in both versions.

After install the method is off until you turn on Enable Melhor Envio shipping and save. If you install the extension again after an uninstall, the settings you kept are used again.

Configuration

All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox Melhor Envio > Edit. The sections are listed on the left. One Save button saves the whole page without reloading it. Every save also clears the cached Melhor Envio quotes and the last API error. Only admin users with the modify permission for this extension can save the settings.

Warnings at the top of the page (and after each save) show an incomplete setup: an origin CEP that is empty or not 8 digits, a missing contact e-mail, a missing BRL exchange rate, no token and no fallback price (then the method is never shown), the last Melhor Envio API error with its date (when a token is saved), or a store without a weight class "kg" or a length class "cm" (units are then converted by their name, and unknown units are read as kg or cm). If Name is empty, too long or contains one of the characters < > ; = # { }, 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

The settings apply to every geo zone. You can limit the method to a geo zone in Availability. The price always comes from the extension.

Enable Melhor Envio shipping: shows or hides Melhor Envio at checkout. Default: off.

Name: the shipping method name shown to customers in the cart and at checkout. Default: Melhor Envio. Required, 64 characters at most.

Sort order: the position of Melhor Envio among the shipping methods at checkout. A whole number.

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, for example tech@example.com. 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. OpenCart has no store postcode, so live quotes need this field. A CEP that is not 8 digits is saved with a notice, but 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 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 says that Melhor Envio prices are used as they are.

Default product weight (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 (cm): length x width x height, used for products without dimensions. Default: 16x11x5.

Fallback prices (in your store 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, tax excluded. Click Add country to add a row (a new row starts with Brazil) and the remove button to delete 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, and a Price of 0 means free shipping. Both "9.99" and "9,99" are accepted. Values that are not numbers are reported after saving and ignored. Rows without any price are dropped.

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

Fallback calculation: Per order (default) 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 (default).

Max weight (kg): hide the method when the cart weighs more. Default: 30. 0 means no limit. An empty field means 30 kg, or no limit when Ignore shipping zones is on.

Minimum subtotal: show the method only if the cart subtotal (products that need shipping, after the coupon, before tax) is at least this amount. Leave it 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 it empty to disable.

Tax class: the tax class added on top of the shipping cost, or No tax (default). Melhor Envio prices are final carrier prices. Choose No tax if OpenCart must not add tax to them.

Geo zone: offer Melhor Envio only for addresses in this geo zone. All zones (default) means no limit. Geo zones are managed in System > Localisation > Geo Zones. The geo zone is not checked when Ignore shipping zones is on.

Availability without shipping zones

Normally the method is offered in the geo zone selected in Availability (all zones when none is selected).

Ignore shipping zones: offer the method for the countries below, whatever the selected geo zone is. The geo zone is not checked in this mode.

Countries: the destination countries for that mode. Leave it 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 storage/logs/vfd_menv_debug.log.php (on OpenCart 4 system/storage/logs/vfd_menv_debug.log.php). The file cannot be read from the web. API 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. When the file reaches 5 MB, it is moved to vfd_menv_debug.old.log.php and a new log is started.

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 extension deletes all extension settings and the log. When off (default), they are kept for a re-install. The quote cache is always removed. The services saved with orders are order history and are kept.

Import / Export

Export: click Download JSON to save the settings as a JSON file. The access token is not exported.

Import: paste previously exported JSON and click Import to restore the settings, for example on another store. The values are checked like a normal save. The saved access token is kept.

How it works at checkout

When OpenCart shows the shipping methods, it asks the extension for the Melhor Envio price. If a Geo zone is set and the address is outside it, Melhor Envio is not offered. With Ignore shipping zones the geo zone is not checked: Melhor Envio is offered only when the country is in Countries (or Countries is empty). Only products with Requires Shipping set to Yes count: other products add no weight and are not included in the subtotal. The extension then checks the cart weight and the minimum subtotal.

For a delivery address in Brazil with an 8-digit CEP, the extension 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 product Model is sent as the item ID. Services with an error or without a price are skipped. The quotes are converted to your default currency, rounded to its decimals, sorted by price and shown in the customer's currency with the tax of the selected Tax class. If free shipping applies, the cheapest service costs 0.

With One option - the cheapest service the customer sees one option, for example Melhor Envio (6-7 business days). With One option per service the customer sees one option per service, for example Melhor Envio: Correios SEDEX (1-2 business days). The delivery estimate is added only when Delivery time is on.

Each quote is cached for 1 hour, 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 when the country has no row), else the fallback cost. Such an option is called just by the Name. 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.

On OpenCart 4 the customer clicks Choose in the shipping method block of the checkout page and picks a Melhor Envio option in the window Shipping method options. The options and prices are the same as on OpenCart 3.

The extension 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 carrier agencies (drop-off points). Manage shipments in your Melhor Envio panel. Melhor Envio ships inside Brazil only. Other countries get the fallback prices only.

Orders

OpenCart saves the name of the chosen option as the shipping method of the order, so the service and the delivery estimate appear in the order e-mails, in the customer's account and in Sales > Orders.

When an order is placed with a live quote, the extension also saves the Melhor Envio service exactly as the customer saw it at the delivery step, without a new request. The admin order page in Sales > Orders shows a Melhor Envio block with Melhor Envio service, Service ID and Delivery estimate, so you know which service to buy in Melhor Envio. The customer sees Melhor Envio service and Delivery estimate on the order page in their account. Orders placed with a fallback price have no service. Existing orders are not affected.

On OpenCart 4 the Melhor Envio block is shown above History. OpenCart 4 keeps one order for the checkout and updates it each time the customer confirms again: the saved service is updated with it, and it is removed when the customer switches to another shipping method or the order gets a fallback price.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Melhor Envio is the first block on Extensions > Extensions > Shipping > VibeFox Melhor Envio > Edit, 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: opencart-shipping-melhor-envio and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only admin users with the Modify permission for the extension can change the key. The texts of the block follow the admin 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 store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the extension keeps working on the last known status.

One key works on one domain: the store address from the OpenCart configuration. Removing the key from the store 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 and no rate is calculated. An admin user who is logged in to the admin in the same browser still sees the method in the store, marked (unlicensed — visible to admins only), so you can set up and test the extension before you buy a key. On OpenCart 4 this preview is not available: the store does not see the admin login, so without an active key the method is hidden for everybody. After you have opened the Edit page once, a reminder appears on the admin Dashboard. Close it with × to hide it for 7 days. Existing orders are not affected.

When a license expires, the extension keeps working, but updates and support need a renewal. The status is checked again automatically when you open the admin Dashboard or the Edit page: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling the extension 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. Check Geo zone, or turn on Ignore shipping zones and check Countries. Check the warnings at the top of the extension page, 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. Check that the products have Requires Shipping set to Yes.

Only fallback prices are shown: turn on Debug log, reload the checkout and look at the Log field on the extension 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.

Tax is added to the Melhor Envio price: set Tax class to No tax.

Quotes look outdated after a change: click Save on the extension page. This clears the cached quotes.

The page says "Warning: You do not have permission to modify VibeFox Melhor Envio!": your admin user group may only view the settings. Give the group the modify permission for extension/shipping/vfd_melhor_envio (OpenCart 3) or extension/vfd_melhor_envio/shipping/vfd_melhor_envio (OpenCart 4) in System > Users > User Groups.

For developers: the Melhor Envio quote address can be replaced with the setting vfd_menv_api_url (for tests); it has no field on the settings page.

Uninstall

Go to Extensions > Extensions, choose the type Shipping and click Uninstall (the red − button) next to VibeFox Melhor Envio. The license key and license status of this extension are always removed. OpenCart always resets Enable Melhor Envio shipping, Sort order, Tax class and Geo zone. The quote cache is always removed. If Remove data on uninstall is on, the other settings and the debug log are deleted as well. If it is off, they are kept and are used again when you install the extension again. The services saved with orders are always kept, and existing orders keep their shipping method and cost.

On OpenCart 4, to remove the files of the extension as well, go to Extensions > Installer after the uninstall and click Uninstall (the orange − button) next to VibeFox Melhor Envio in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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