VibeFox Mercado Envios 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.

Mercado Pago account (for live rates only): live rates come from the Mercado Envios calculator of your Mercado Pago account in Argentina, Brazil or Mexico. Mercado Envios must be enabled for the account. Parcels are quoted from the shipping address configured in that account. You need the production Access Token (it starts with APP_USR-): in Mercado Pago Developers open your application and its production credentials. There is no login button: you paste the token into the extension settings. If you only use prices per country, you do not need a Mercado Pago account.

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_mercado_envios-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_mercado_envios.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_mercado_envios-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 Mercado Envios 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. For live rates, paste the Access Token, choose the Mercado Envios country and, if your store default currency is not ARS, BRL or MXN, the exchange rate. Optionally fill in Country prices and Fallback cost (used without live rates). Turn on Enable Mercado Envios shipping and click Save.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_mercado_envios.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 Mercado Envios, 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 Mercado Envios 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 Mercado Envios > Edit. The sections are listed on the left. One Save button saves the whole page without reloading it. Every save also clears the cached Mercado Envios rates and the last API error. Only admin users with the modify permission for this extension can save the settings.

Warnings in the General section (and after each save) show configuration problems: a missing exchange rate, no access token and no price (then the method is never shown), the last Mercado Envios API error with its date, and a store weight or length unit the extension does not know (it is then read as kg or cm). If Name is empty or longer than 64 characters, Exchange rate is not a positive number, another number field is not a number of 0 or more, or Min weight is greater than Max weight, the page shows an error and nothing is saved.

General

The customer sees one Mercado Envios rate. You can limit the method to a geo zone or to countries in Availability. These settings apply to every zone.

Enable Mercado Envios shipping: shows or hides Mercado Envios at checkout. Default: off.

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

Tax class: the tax class of the shipping cost, or No tax (default). Mercado Envios quotes final prices. No tax shows them as quoted, a tax class adds your shipping tax on top.

Sort order: the position of Mercado Envios among the shipping methods at checkout. A whole number.

Mercado Envios API (live rates) (without a token only the prices below are used)

Access token: your Mercado Pago production Access Token (APP_USR-...). It is sent only to api.mercadopago.com and never logged. After saving, the field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it.

Remove the saved access token: turn it on and save to delete the saved token. Only the prices below are used then. A token typed above replaces the saved one instead.

Mercado Envios country: the country of your Mercado Pago account: Argentina (ARS) (default), Brazil (BRL) or Mexico (MXN). Live rates are requested only for destinations in this country and are quoted in its currency.

Exchange rate: only needed when your store default currency differs from the Mercado Envios currency: the price of 1 ARS, BRL or MXN in your default currency, for example 0.001. Without it live rates are not used. It must be a positive number. Both a point and a comma are accepted as the decimal separator.

Prices without live rates

These prices are used when there is no access token, for destinations outside the Mercado Envios country, and when the API gives no rate (a failed request is retried after 5 minutes). They are in your store default currency, tax excluded.

Country prices: a table of destination countries and prices. Click Add country to add a row and the remove button to delete one. Choose * All other countries for every country without its own row. Price is the price for the country. The columns XS (up to 1 kg), S (1-2 kg), M (2-3 kg), L (3-5 kg) and XL (over 5 kg) replace it for that cart weight. An empty or 0 column uses Price. A Price of 0 means free shipping to that country. Both 9.99 and 9,99 are accepted. Values that are not numbers are reported after saving and cleared. Rows without any price are dropped when you save.

Fallback cost: used when neither the API nor Country prices give a price. Leave it empty to hide the method in that case.

Calculation type: Per order (default) charges the price once. Per item (each item priced by its own weight x quantity) looks up Country prices (or the Fallback cost) for the weight of each product and multiplies it by its quantity. If one product gets no price, the method is hidden. Live Mercado Envios rates are always for the whole parcel.

Availability

Min weight (kg): the minimum cart weight for this method to appear. 0 means no limit (default).

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

Minimum subtotal: show the method only when the subtotal of the products that need shipping (after the coupon, before tax) is at least this amount. Leave it empty to always show it.

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

Ignore shipping zones: offer the method for the countries below, whatever geo zone is selected.

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

Free shipping

Free shipping from: the subtotal of the products that need shipping (after the coupon, before tax) from which this method is free. No API request is made in that case. Leave it empty to disable.

Advanced

Debug log: writes API requests and the rate calculation to storage/logs/vfd_mrcv_debug.log.php (on OpenCart 4 system/storage/logs/vfd_mrcv_debug.log.php). The file cannot be read from the web. Errors are always logged, even with this option off. The access token and customer addresses are never logged. When the file reaches 5 MB, it is moved to vfd_mrcv_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 the settings and the log. When off (default), they are kept for a re-install. Cached rates are always removed. The Mercado Envios data of placed orders is always kept as order history.

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 Mercado Envios price. If a Geo zone is set and the address is outside it, Mercado Envios is not offered (unless Ignore shipping zones is on; then Countries decides). 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. The subtotal is the price of the products that need shipping, after the coupon discount and before tax. Gift certificates, reward points and store credit are not taken into account. If free shipping applies, the price is 0 and no request goes to Mercado Envios.

For a destination in the Mercado Envios country with a valid postcode (4 digits in Argentina, also from a CPA such as C1425ABC; 8 digits in Brazil; 5 digits in Mexico), the extension describes the cart as one parcel: the largest width and length of the products, the heights of all products added up, and the total weight in grams. Product weights and dimensions are converted from their OpenCart weight and length classes. Each side and the weight are raised to the Mercado Envios minimums of the country, so products without dimensions or weight still get a rate. The cart value is sent as the item price in the Mercado Envios currency. The cheapest option returned by Mercado Envios is converted to your default currency, rounded to its decimals and shown in the customer's currency with the tax of the selected Tax class.

Each quote is cached for up to 1 hour (not longer than the OpenCart cache lifetime), so the same cart does not trigger a new request. A failed quote is not repeated for 5 minutes. If Mercado Pago cannot be reached, rejects the token, limits the requests or answers in another currency, all live quotes pause for 5 minutes, so the checkout does not wait for the API on every refresh. The API timeout is 10 seconds.

The prices without live rates are used instead when there is no token, the destination is outside the Mercado Envios country, the postcode is missing or not valid, the exchange rate is missing, the parcel is heavier than the Mercado Envios limit of the country (25 kg in Argentina, 15 kg in Brazil, 30 kg in Mexico), or Mercado Envios returns an error or no option for the address. The row of the country (or the * row) is used, else the fallback cost. If there is no price, the method is hidden. The customer never sees an API error.

On OpenCart 4 the customer clicks Choose in the shipping method block of the checkout page and picks Mercado Envios in the window Shipping method options. The method works the same way as on OpenCart 3.

The extension calculates rates only. It does not create shipments, print labels or track parcels. Create the shipment in your Mercado Libre or Mercado Pago account. It shows one price, the cheapest Mercado Envios option, not a choice between all options, and it has no pickup point (agency) selector.

Orders

When an order is placed with a live Mercado Envios rate, the extension keeps the service name, the estimated delivery time in days and the live rate. In Sales > Orders the order page shows a Mercado Envios block with Mercado Envios service, Estimated delivery and Live rate (excl. tax). The block is shown even when the method is later disabled. A registered customer sees Mercado Envios service and Estimated delivery under the shipping method on the order page of their account, and the same lines are added to the new order e-mail. Orders placed with a table price or the fallback cost have no service. Existing orders are not affected by later rate changes.

On OpenCart 4 the Mercado Envios 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 table price or the fallback cost.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Mercado Envios is the first block on Extensions > Extensions > Shipping > VibeFox Mercado Envios > 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-mercado-envios 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, Mercado Envios 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

Mercado Envios does not appear at checkout: check that the license is active and Enable Mercado Envios shipping is on. Check Geo zone, or turn on Ignore shipping zones and check Countries. Check the warnings on the extension page, the weight limits and Minimum subtotal. The method needs a price: a working access token for addresses in the Mercado Envios country, or Country prices or Fallback cost. Check that the products have Requires Shipping set to Yes.

Live rates do not appear: turn on Debug log, reload the checkout and look at the Log field on the extension page. Typical reasons: no token, a destination outside the Mercado Envios country, a missing or invalid postcode, a missing Exchange rate, a parcel over the weight limit, or no Mercado Envios option for the address.

HTTP 401 or 403 in the warnings: the access token is invalid or expired. Copy the production Access Token again from Mercado Pago Developers.

Mercado Envios answered in another currency: the account country does not match Mercado Envios country. Choose the country of your Mercado Pago account.

In which currency are the prices: Country prices, Fallback cost and the thresholds are in your store default currency. Live rates come in the currency of your Mercado Pago account and are converted with Exchange rate when the store uses another default currency.

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

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

For developers: the Mercado Envios API address can be replaced with the setting vfd_mrcv_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 Mercado Envios. The license key and license status of this extension are always removed. OpenCart always resets Enable Mercado Envios shipping, Sort order, Tax class and Geo zone. The cached rates and the last API error are 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 Mercado Envios data of placed orders is 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 Mercado Envios in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

Mercado Envios and Mercado Pago are trademarks of their respective owner. This extension is not affiliated with or endorsed by Mercado Envios or Mercado Pago.