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

Coordinadora API key (for live quotes only): live quotes come from the Coordinadora Cotizador through the Coordinadora WooCommerce service, the same service the official Coordinadora plugin uses. Coordinadora issues the API key to customers with an active commercial agreement. Ask your Coordinadora account manager or see wc.coordinadora.com. You also need the 8-digit DANE code of the city you ship from. Without a key the method works with fixed prices only.

Products: for a live quote every product in the cart needs a weight and three dimensions (length, width, height).

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_coordinadora-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_coordinadora.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_coordinadora-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 Coordinadora 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, the origin city DANE code and, if your default currency is not COP, the COP exchange rate. Add at least a fixed price for Colombia as a fallback (see Configuration). Turn on Enable Coordinadora and click Save.

6. Make sure your products have weight and dimensions.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_coordinadora.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 Coordinadora, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key and the settings as in steps 4 to 6 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 Coordinadora and save. If you install the extension again after an uninstall, the Coordinadora settings you kept are used again.

Configuration

All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox Coordinadora > Edit. The settings apply to every geo zone; you can limit the method to a geo zone and to countries in Conditions. The sections are listed on the left. One Save button at the bottom saves the whole page without reloading it. After saving you see Settings saved. Cached Coordinadora rates were cleared. Numbers can be typed with a point or a comma (9,99 = 9.99). Only admin users with the modify permission for this extension can save the settings.

Nothing is saved and the page lists the errors if Name is empty or longer than 64 characters, a number or a table price is invalid or negative, COP per 1 unit of store currency is 0, Min weight (kg) is greater than Max weight (kg), or Sort order is not a whole number.

The page shows warnings above the settings when live quotes cannot work or the method would be hidden: Origin city (DANE code) is empty or invalid; COP per 1 unit of store currency is missing while your default currency is not COP; there is no fixed price for Colombia (or *); there is no API key and no fixed price for Colombia, so the method is never shown for Colombian addresses. A warning also appears when the store has no weight class in kg or no length class in cm and its default unit is not known to the extension; product weights are then read as kg and dimensions as cm (use kg, g, lb or oz and cm, mm, m or in in System > Localisation). The warnings are updated after every save.

General

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

Name: the shipping method name shown to the customer at checkout. Default: Coordinadora. Required, up to 64 characters.

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

Live Coordinadora rates

Live quotes are requested for destinations in Colombia. Leave the key empty to use fixed prices only.

API key: your Coordinadora WooCommerce API key from Coordinadora. After saving, the field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it. The key is never written to the log.

Remove the saved API key: shown only when a key is saved. Turn it on and click Save to delete the key; the method then uses fixed prices only.

Origin city (DANE code): the 8-digit DANE code of the city you ship from, for example 11001000 Bogotá, 05001000 Medellín, 76001000 Cali or 08001000 Barranquilla. A 5-digit municipality code is also accepted and completed to 8 digits.

COP per 1 unit of store currency: Coordinadora quotes in Colombian pesos. If your default currency is not COP, enter how many COP make 1 unit of your currency, for example 4300. The rate is also used to send the declared value in COP. Leave it empty and live rates are not used. The rate must be greater than 0. If your default currency is COP, leave it empty.

Fixed prices (used when there is no API key, for destinations outside Colombia, and as a fallback when a live quote is unavailable)

Prices by country: a list of countries with a Price column and optional prices by package size, in your default currency, tax excluded. The size comes from the cart weight: XS up to 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg, XL over 5 kg. Price is used when the size column is 0 or empty. Click Add country to add a row; a new row starts with Colombia. The country * All other countries applies to countries without their own row. A country without a row (and without *) gets no fixed price. A row with Price 0 and no size price gives free shipping.

Fixed price per: Order (default) charges the price once. Item (price × quantity) multiplies it by the number of items in the cart. This applies to fixed prices only; a live Coordinadora quote always covers the whole order.

Conditions

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

Max weight (kg): hide the method above this cart weight. Default: 25 (also used when the field is empty). 0 means no limit.

Minimum order subtotal: show the method only if 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: turn on free delivery from the subtotal below.

Free shipping from: the subtotal (after the coupon, before tax) from which shipping is free. Used only when Free shipping is on. No API request is made in that case.

Tax class: the tax class of the shipping cost, or No tax (default). With a tax class OpenCart adds shipping tax on top of the rate. Choose No tax if your prices or the Coordinadora quote already include tax.

Geo zone: offer Coordinadora only for addresses in this geo zone. All zones (default) means no limit. Geo zones are managed in System > Localisation > Geo Zones.

Countries: offer Coordinadora only for these destination countries. Leave it empty to allow all countries. This limit applies together with Geo zone.

Advanced

Debug log: writes rate calculations to storage/logs/vfd_crd_debug.log.php (on OpenCart 4 system/storage/logs/vfd_crd_debug.log.php). The file cannot be read from the web. API errors and incomplete settings are always logged, even when this option is off. The API key and customer addresses are never logged. When the file reaches 5 MB, it is moved to vfd_crd_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 Coordinadora settings, cached rates and logs. When off (default), everything is kept for a re-install.

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 Coordinadora price. If a Geo zone is set and the address is outside it, Coordinadora is not offered. Only products with Requires Shipping set to Yes count: other products add no weight and are not included in the quote. 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. The extension first checks the conditions: allowed countries, cart weight and minimum order subtotal. If free shipping applies, the price is 0 and no request goes to Coordinadora.

For an address in Colombia with an API key, the extension finds the DANE code of the destination city in this order: a DANE code in the city field (Colombian departments and cities checkout modules write it, for example MEDELLIN (ANT) (05001000)), an 8-digit postcode, or the built-in list of department capitals and about 40 largest cities. If the address has a region (department), a city from the list is checked against it. Accents and case are ignored.

Then the extension sends Coordinadora the destination DANE code and each product with the origin city, its weight (kg), dimensions (cm), quantity and declared value (COP). The declared value is the product line total before tax, after the coupon discount. Product weight and length classes are converted automatically. Coordinadora returns the price in COP, and the extension converts it to your default currency, rounds it to the decimals of that currency and shows it in the customer's currency with the tax of the selected Tax class. Each quote is cached for 1 hour. A failed request is remembered for 10 minutes, so a Coordinadora outage never slows every checkout refresh. The API timeout is 10 seconds.

When a live quote is unavailable (API error, unknown city, a product without weight or dimensions, missing settings), the fixed price is used. If there is none, the method is hidden for that cart. Error details go to the debug log, never to the customer.

The extension calculates rates only. It does not create shipments or guides (guías), print labels, book pickups (recogidas), track parcels, collect cash on delivery (recaudo) or offer Droop pickup points; use the Coordinadora portal for these. It adds nothing to orders: the order shows the method name and the shipping cost like any other OpenCart shipping method. International destinations use the fixed prices.

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

License key

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

Coordinadora does not appear at checkout: check that the license is active and Enable Coordinadora is on. Check the warnings at the top of the extension page, Geo zone, Countries, the weight limits and Minimum order subtotal. Without a live quote, a fixed price for the country or * must exist. Check that the products have Requires Shipping set to Yes.

The live rate is not shown, only the fixed price: turn on Debug log, reload the checkout and look at the Log field on the extension page. Typical reasons: the destination city is not recognised, a product has no weight or dimensions, the origin DANE code or the COP exchange rate is missing, or Coordinadora returned an error.

The destination city is not recognised: install a Colombian departments and cities checkout module that writes the DANE code into the city field. Developers can map more cities or change the API address with the OpenCart events vfd_coordinadora/dane_cities, vfd_coordinadora/destination_dane and vfd_coordinadora/api_url; the API address can also be replaced with the setting vfd_crd_api_url (for tests), which has no field on the settings page.

Does the rate include tax? The rate is what Coordinadora quotes. With a Tax class OpenCart adds shipping tax on top; choose No tax if the quote already includes it for you.

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

Uninstall

Go to Extensions > Extensions, choose the type Shipping and click Uninstall (the red − button) next to VibeFox Coordinadora. The license key and license status of this extension are always removed. OpenCart always resets Enable Coordinadora, Sort order, Tax class and Geo zone. The cached quotes are always removed. If Remove data on uninstall is on, the Coordinadora settings and the log are deleted as well. If it is off, the other settings are kept and are used again when you install the extension again. 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 Coordinadora in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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