VibeFox Mercado Envios for Adobe Commerce — सहायता

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.

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: in the Mercado Pago developer panel open your application and its production credentials. There is no login button: you paste the token into the module 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 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-mercado-envios-shipping. Without Composer: unpack the ZIP file into app/code/Vibefox/MercadoEnviosShipping/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_MercadoEnviosShipping 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 Mercado Envios. 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. For live rates, paste the Access token, choose the Mercado Envios country and, if the base currency of your store is not ARS, BRL or MXN, enter the exchange rate. Optionally fill in Country prices and Fallback cost (used without live rates). Set Enable Mercado Envios to Yes and click Save Config.

The module adds the Mercado Envios shipping method to Magento. With fixed prices customers see it as Mercado Envios - Shipping (method title and method name). With a live rate the method name is replaced by the Mercado Envios service and the delivery time, for example Mercado Envios - Estándar a domicilio (3 business days). It is off after installation (Enable Mercado Envios = No).

Configuration

All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox Mercado Envios, 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 Mercado Envios rates and the last API error. 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 or Method name, longer than 64 characters, a Method title with one of the characters < > ; = # { }; a Sort order that is not a whole number; an exchange rate, fallback cost, weight or subtotal field that does not contain a number of 0 or more; an Exchange rate of 0; a Minimum weight (kg) greater than the Maximum weight (kg) (an empty maximum counts as 25 kg).

While Enable Mercado Envios is Yes, warnings after saving show settings that stop live rates or hide the method: Mercado Envios: enter the exchange rate for the selected account country and base currency. and Mercado Envios: no access token and no fixed prices; the method is hidden at checkout. The warnings are shown only while the method is enabled, because the Delivery Methods page is shared by all shipping methods.

General

Enable Mercado Envios: shows or hides Mercado Envios at checkout. Default: No.

Method title: the carrier name shown in the cart and at checkout. Default: Mercado Envios. Required, at most 64 characters, without < > ; = # { }.

Method name: shown after the method title, as "Method title - Method name", for fixed and free prices. Default: Shipping. Required, at most 64 characters. Live rates show the Mercado Envios service and delivery time instead.

Sort order: the position among the shipping methods at checkout. A whole number, negative numbers are allowed.

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

Access token: the production Access Token of your Mercado Pago account. It is sent only to api.mercadopago.com and never logged. 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 prices below are used then.

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: how many units of the base currency of your store one ARS, BRL or MXN is worth, for example 0.001. Only needed when the base currency differs from the currency of the account country. Without it live rates are not used. It must be greater than 0.

API status: shows the last Mercado Envios API error with its date, while the method is enabled and a token is saved. It is empty when there is no error. A successful live rate clears it.

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. They are in the base currency of your store, tax excluded.

Country prices: a table of destination countries and prices. Click Add country to add a row and Delete to remove 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 (up to 2 kg), M (up to 3 kg), L (up to 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. If a country has several rows, the first one is used. Values that are not numbers are cleared on save, and the warning Mercado Envios: invalid country prices were cleared: lists them; the rest of the page is saved. Rows without any price are dropped when you save.

Calculation type: Per order (default) charges the price once. Per item 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.

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

Availability

Minimum weight (kg): the minimum cart weight for the method to appear. Empty or 0 means no minimum.

Maximum weight (kg): hide the method when the cart weighs more. Default: 25. An empty field means 25 kg, an explicit 0 means no weight limit. The API also has its own parcel limit per country (see How it works at checkout).

Minimum subtotal: show the method only when the cart subtotal (products that need shipping, 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 (calculated the same way) from which the method is free. No request goes to Mercado Envios in that case. Leave empty to turn it off.

Ship to Applicable Countries: All Allowed Countries offers Mercado Envios for every country your store allows, Specific Countries only for the countries below.

Ship to Specific Countries: the destination countries for Specific Countries. Live rates are requested only for the Mercado Envios country; other countries use the prices without live rates.

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 the parcel is sent with the minimum Mercado Envios size of the country and volumetric weight is not calculated. The module has no tax setting: if your store charges tax on shipping, set it in Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping.

Advanced

Debug log: writes API requests and rate calculations to var/log/vfd_mrcv_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. The access token and full customer postcodes 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 Mercado Envios settings and the log (see Uninstall). The license key and the cached rates are always removed. The service data of orders is never deleted.

How it works at checkout

At the shipping step Magento asks the module for the Mercado Envios 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. If Free shipping from applies, the price is 0 and no request goes to Mercado Envios. A Magento cart price rule with free shipping also makes the price 0 when the method has a price.

For a destination in the Mercado Envios country with a valid postcode (Argentina: the 4 digits of the CP or CPA, for example C1425ABC is sent as 1425; Brazil: 8 digits; Mexico: 5 digits), the module describes the cart as one parcel: the total weight in grams, at least 100 g, and the minimum size of the country (Argentina and Mexico 10 x 10 x 10 cm, Brazil 16 x 11 x 2 cm). 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 base currency; Magento then shows it in the customer's currency and adds tax on shipping if your store charges it. The delivery time from Mercado Envios is rounded up to whole days.

Each quote is cached for 1 hour, 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 or limits the requests, 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 * All other countries row) is used, else the fallback cost. If there is no price, the method is hidden. The customer never sees an API error. The reason is written to the log.

The module 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 module keeps the service name, the estimated delivery time in business days and the price, without a new request to Mercado Envios. The shipping method of the order shows the service and the delivery time, for example Mercado Envios - Estándar a domicilio (3 business days), so they also appear in the order e-mails. Orders placed with a fixed price, the fallback cost or free shipping have no service data.

On the admin order page (Sales > Orders > View, Information tab) the Mercado Envios shipping block shows Service, Estimated delivery (business days), Price in base currency and Base currency.

The customer sees Mercado Envios service and Estimated delivery on the order page in their account, or on the Orders and Returns page for guests. The blocks also work for older orders and when the module is switched off. Existing orders are not affected by later rate changes.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Mercado Envios is the first row of the VibeFox Mercado Envios 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-mercado-envios 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 Mercado Envios 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

Mercado Envios does not appear at checkout: check that the license is active and Enable Mercado Envios 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. The method needs a price: a working access token for addresses in the Mercado Envios country, or Country prices or Fallback cost.

Live rates do not appear: turn on Debug log, reload the checkout and look at the Log field in the Advanced section. 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 API status: the access token is invalid or expired. Copy the production Access Token again from the Mercado Pago developer panel.

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 subtotal thresholds are in the base currency of your store. Live rates come in the currency of your Mercado Pago account and are converted with Exchange rate when the base currency is different.

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

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_MercadoEnviosShipping. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_MercadoEnviosShipping to remove the data, then bin/magento module:disable Vibefox_MercadoEnviosShipping, delete the folder app/code/Vibefox/MercadoEnviosShipping and run bin/magento setup:upgrade.

The license key, the license status and the cached rates are always removed. If Remove data on uninstall is Yes, the Mercado Envios settings and the log are removed too. If it is No, the settings are kept for a re-install. The Mercado Envios service data of orders is always kept.

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