VibeFox Envioclick 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.

Envioclick account (for live rates only): an Envioclick account in Mexico or Colombia with API access. The API key is in your Envioclick account under Mi cuenta (top right) > Información del API. If you only use fixed prices, you do not need an Envioclick account.

User-Agent (Mexico only): Envioclick Mexico requires a User-Agent value for every API request. Ask Envioclick support for it (soporte.tecnico@envioclick.com).

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_envioclick-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_envioclick.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_envioclick-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 Envioclick 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. Enter the API key, choose the API country, enter the User-Agent (Mexico), the origin postcode or DANE code and the origin address. If your store default currency is not MXN or COP, enter the currency conversion rate. Optionally add fixed prices per country and a fallback cost. Turn on Enable Envioclick and click Save.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_envioclick.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 Envioclick, 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 Envioclick and save. If you install the extension again after an uninstall, the Envioclick settings you kept are used again.

Configuration

All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox Envioclick > Edit. The sections are listed on the left. One Save button at the bottom saves the whole page without reloading it. Every save also clears the cached Envioclick quotes. Number fields accept both a point and a comma as the decimal separator. Only admin users with the modify permission for this extension can save the settings.

The General section shows warnings when live rates cannot work with the saved settings: no conversion rate for a store currency other than MXN or COP, no User-Agent for Mexico, no origin postcode or DANE code, or no origin address for Colombia. It also warns if the store weight or length unit is not recognized; then add a weight class with the unit kg in System > Localisation > Weight Classes or a length class with the unit cm in System > Localisation > Length Classes. When saving, the extension checks that Method title has 1 to 64 characters, that number fields contain numbers that are not negative, that Currency conversion rate is greater than 0, that Minimum weight (kg) is not greater than Maximum weight (kg), that the origin code has 5 digits for Mexico or 8 digits (or the 5-digit municipality code) for Colombia, that every row of Price per country has a valid country and a price, and that Sort order is a whole number. If a check fails, nothing is saved and the page lists the errors.

General

The customer sees one Envioclick rate, the cheapest or the fastest carrier. You can limit the method to a geo zone or to countries in Availability.

Enable Envioclick: shows or hides Envioclick at checkout. Default: off.

Method title: the shipping method name shown to the customer in the cart and at checkout, at most 64 characters. Default: Envioclick Shipping. Required.

Carrier in the title: add the Envioclick carrier and the estimated delivery time of a live rate to the title, for example "Envioclick Shipping (Estafeta Express, 1 day)". OpenCart saves this title with the order, so it also appears in the order e-mails and order pages. The carrier is saved to the order either way. Default: on.

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

Envioclick API (live rates)

Optional. Without an API key only the fixed prices are used. The section links to the Envioclick API documentation for Mexico and Colombia. Live rates are requested only for destinations in the API country. Shipping to other countries uses the fixed prices.

API key: your Envioclick API key from Mi cuenta > Información del API. It is sent in the "Authorization" header and is never shown to customers or written to the log. 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 API key: turn it on and save to delete the saved key; only the fixed prices are used then. A key typed in API key replaces the saved one instead. The switch turns itself off after the save.

API country: the country of your Envioclick account.

User-Agent (Mexico): the value issued by Envioclick support (soporte.tecnico@envioclick.com), for example EcUserAgent-2/123456. Required for Mexico; live rates for Mexico are not requested without it. Optional for Colombia.

Carrier choice: Cheapest (default) or Fastest (then cheapest). Envioclick returns quotes from several carriers, and the customer gets one rate.

Branch pickup rates: also consider "Ocurre" rates, where the customer collects the parcel at the carrier's branch. When off, only home delivery rates are used. Cash-on-delivery (COD) services are never used. Default: off.

Currency conversion rate: Envioclick quotes in MXN (Mexico) or COP (Colombia). If your store default currency is different, enter the value of 1 MXN or COP in your store currency, for example 0.05. The declared parcel value is converted back the same way. Leave it empty if the store currency is MXN or COP. Without it, live rates are not used in another currency.

Ship from

Used for live rates. OpenCart has no store postcode, city or street, so enter them here.

Origin postcode / DANE code: Mexico: the 5-digit postcode. Colombia: the 8-digit DANE code of the municipality, for example 11001000 for Bogotá; a 5-digit municipality code (11001) is completed with 000.

Origin address: the street and number of the pickup address. Required for Colombia, optional for Mexico.

Fixed prices

Used when there is no live rate: no API key, a destination outside the API country, or an API error or no carrier for the route.

Price per country: a list of countries and prices in your store default currency, tax excluded. Click Add country to add a row and the × button to remove one. Choose * All other countries for a price used for every country without its own row.

Fallback cost: used when there is no live rate and no row of the table matches. Leave it empty to hide the method in that case.

Fixed price applies: Per order (default) charges the price once. Per item (price × quantity) multiplies it by the number of items in the cart. Live Envioclick rates are always per shipment.

Conditions

Minimum weight (kg): hide the method below this cart weight. 0 means no limit (default).

Maximum weight (kg): hide the method above this cart weight. Default: 25. 0 means no limit.

Minimum order amount: 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.

Free shipping from: free shipping when the subtotal of the products that need shipping (after the coupon, before tax) reaches this amount. No API request is made then. Leave it empty to never give free shipping.

Tax class: the tax class of the shipping cost, or No tax (default). Envioclick quotes already include the carriers' taxes, so choose No tax to avoid charging tax on shipping twice.

Availability

Normally the method is offered for addresses in the selected geo zone, or everywhere.

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

Ignore shipping zones: do not check the geo zone; the country list below decides. Default: off.

Countries: the destination countries for that mode. Leave it empty to allow all countries. Used only when Ignore shipping zones is on.

Advanced

Debug log: writes rate calculations and API errors to storage/logs/vfd_evc_debug.log.php (on OpenCart 4 system/storage/logs/vfd_evc_debug.log.php). The file cannot be read from the web. The API key and customer addresses are not logged. Nothing is written while the log is off, not even API errors. Turn it off when you are done. When the file reaches 5 MB, it is moved to vfd_evc_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 Envioclick settings, cached quotes and the log. When off (default), they are kept for a re-install. The Envioclick data of placed orders is always kept.

Import / Export

Export: click Download JSON to save the settings as a JSON file. The API key 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 API key is kept.

How it works at checkout

When OpenCart shows the shipping methods, it asks the extension for the Envioclick price. If a Geo zone is set (and Ignore shipping zones is off) and the address is outside it, Envioclick is not offered. Only products with Requires Shipping set to Yes count: other products add no weight and are not included in the order amount. The extension then checks the conditions: the countries of Ignore shipping zones, the cart weight and the minimum order amount. The order amount 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 Envioclick.

If an API key is set and the destination is in the API country, the extension asks Envioclick for quotes. In Mexico the request is made once the customer has entered a 5-digit postcode. In Colombia it is made once the municipality is recognized from an 8-digit DANE code in the postcode field, or from the department (the region of the OpenCart address) and the city; a city name that is unique in Colombia is recognized without the department. Accents and case do not matter. The extension picks the cheapest or the fastest quote that is not cash on delivery and converts it to your store default currency. The price is rounded to the decimals of that currency and shown to the customer in their currency with the tax of the selected Tax class.

The parcel is always one box: the total weight converted to kg from the product weight classes, and a box size from the product dimensions converted to cm. Products without dimensions count as 10 × 10 × 10 cm. A cart without any weight is sent as 0.5 kg. The declared value is the order amount.

Each quote is cached for 1 hour for the same route and parcel. A failed request is cached for 10 minutes, so an unavailable API does not slow down every checkout update. If Envioclick returns an error or no carrier for the route, the customer sees no error: the fixed price or the fallback cost is used, or the method is hidden. The reason is written to the debug log when it is on.

The extension calculates rates only. It does not create guides or labels, request pickups, track or cancel shipments. It offers one rate, not a choice between carriers, and uses no cash-on-delivery services and no multi-parcel quotes. Live quotes are domestic only.

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

Orders

When an order is placed with Envioclick, the rate calculated at checkout is saved with the order and no longer changes. In Sales > Orders the order page shows the panel Envioclick shipping with Envioclick carrier, Estimated delivery and Envioclick rate ID (for a live rate), Price source (Envioclick live rate, Fixed price per country, Fallback cost or Free shipping threshold) and Calculated price (excl. tax). The panel is shown even after the method is switched off.

On OpenCart 4 the checkout keeps one order and updates it each time the customer confirms again. The saved rate is then replaced by the latest rate of the checkout. If the customer switches to another shipping method, the panel is no longer shown for that order. Changes of the order in the admin do not change the saved rate.

If Carrier in the title is on, the carrier is part of the shipping method name of the order. If it is off, a line Shipping carrier: with the carrier of a live rate is added to the new order e-mail and to the order page in the customer's account while the extension is enabled. Create the guide in your Envioclick account. Orders placed with a fixed price have no Envioclick carrier.

License key

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

Envioclick does not appear at checkout: check that the license is active and Enable Envioclick is on. Check Geo zone, or Ignore shipping zones and Countries, the weight limits and Minimum order amount. Without a live rate the method needs a fixed price for the country, a * All other countries row or a Fallback cost. Check that the products have Requires Shipping set to Yes.

Live rates do not appear: read the warnings in the General section, then turn on Debug log, reload the checkout and look at the Log field on the extension page. Common reasons: no conversion rate (store currency is not MXN or COP), no User-Agent (Mexico), no origin postcode or DANE code, the customer's postcode (Mexico) or city (Colombia) is not entered yet, the destination is outside the API country, or no carrier for the route.

Why a conversion rate? Envioclick returns prices in Mexican or Colombian pesos only. The extension never shows a peso amount as another currency.

Colombia: the city is not recognized: check that the customer selects the department as the region of the address and types the municipality name correctly. An 8-digit DANE code typed as the postcode also works.

Tax is charged twice on shipping: Envioclick quotes already include the carriers' taxes. Set Tax class to No tax.

Rates 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 Envioclick!": your admin user group may only view the settings. Give the group the modify permission for extension/shipping/vfd_envioclick (OpenCart 3) or extension/vfd_envioclick/shipping/vfd_envioclick (OpenCart 4) in System > Users > User Groups.

For developers: the Envioclick quotation API address can be replaced with the setting vfd_evc_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 Envioclick. The license key and license status of this extension are always removed. OpenCart always resets Enable Envioclick, Sort order, Tax class and Geo zone. The cached quotes are always removed. If Remove data on uninstall is on, the Envioclick settings and the debug log are deleted as well. If it is off, the other settings are kept and are used again when you install the extension again. The Envioclick data of placed orders is kept in both cases, and 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 Envioclick in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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