VibeFox Coordinadora 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 and JSON extensions.

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 dimensions (length, width, height). Magento has no standard product dimensions: the module reads them from the product attributes ts_dimensions_length, ts_dimensions_width, ts_dimensions_height or length, width, height, if your store has them. Without them the fixed prices are used.

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-coordinadora-shipping. Without Composer: unpack the ZIP file into app/code/Vibefox/CoordinadoraShipping/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_CoordinadoraShipping 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 Coordinadora. 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. Enter the API key, the origin city DANE code and, if the base currency of your store is not COP, the COP exchange rate. Add at least a fixed price for Colombia (or *) as a fallback (see Configuration). Set Enable Coordinadora to Yes and click Save Config.

The module adds the Coordinadora shipping method to Magento. Customers see it as Coordinadora - Courier delivery (method title and method name). It is off after installation (Enable Coordinadora = No). Make sure Colombia is among the allowed countries of your store.

Configuration

All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox Coordinadora, 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 Coordinadora quotes. Numbers 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, longer than 64 characters or with one of the characters < > ; = # { }; an empty Method name or one longer than 64 characters; a Sort order that is not a whole number; a number field that does not contain a non-negative number; COP per 1 unit of base currency set to 0; a Min weight (kg) greater than the Max weight (kg); an invalid or negative price in Prices by country.

While Enable Coordinadora is Yes, warnings after saving show settings that stop live quotes or hide the method. With an API key: Origin city (DANE code) is empty or invalid; the base currency is not COP and COP per 1 unit of base currency is empty; there is no fixed price for Colombia (or *), so the method is hidden when a live quote is unavailable. Without an API key: there is no fixed price for Colombia (or *), so the method is never shown for Colombian addresses. The warnings are shown only while the method is enabled, because the Delivery Methods page is shared by all shipping methods.

General

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

Method title: the shipping method name shown to the customer in the cart and at checkout (the carrier title in Magento). Default: Coordinadora. Required, at most 64 characters, without < > ; = # { }.

Method name: shown after the method title, as "Method title - Method name". Default: Courier delivery. Required, at most 64 characters.

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

Live Coordinadora rates

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

API key: your Coordinadora API key, sent to Coordinadora in the request header. Magento stores it encrypted and shows only a mask after saving. Leave the mask as it is to keep the saved key, type a new value to change it. To delete the saved key, clear the field and click Save Config; the method then uses fixed prices only. The key is never written to the log.

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. An invalid code is saved as typed, and the warning after saving points to it; live quotes are not requested until it is fixed.

COP per 1 unit of base currency: Coordinadora quotes in Colombian pesos. If the base currency of your website is not COP, enter how many COP make 1 unit of the base 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 base 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 table of countries with a Price column and the size columns XS, S, M, L and XL, in the base 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 and Delete to remove one. The country * Default (all other countries) applies to countries without their own row. A country without a row (and without *) gets no fixed price. A saved row of zeros (or of empty prices) means free shipping for that country. If a country is added twice, the first row is used.

Fixed price per: Order 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.

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

Minimum order subtotal: show the method only if the subtotal of the products that need shipping (after discounts, tax excluded, in the base currency) is at least this amount. Leave empty to always show it.

Free shipping: Yes turns on free delivery from the subtotal below. Default: No.

Free shipping from: the subtotal of the products that need shipping (after discounts, tax excluded, in the base currency) from which shipping is free. Used only when Free shipping is Yes. No API request is made in that case.

Ship to Applicable Countries: All Allowed Countries (default) offers Coordinadora for every country your store allows, Specific Countries only for the countries below.

Ship to Specific Countries: the destination countries for Specific Countries. Countries other than Colombia always get the fixed prices.

Product weights are converted to kg from the weight unit of your store (Stores > Configuration > General > General > Locale Options > Weight Unit, lbs or kgs). Product dimensions from the attributes are read in cm when the weight unit is kgs and in inches when it is lbs. The module has no tax field: shipping tax is set by Magento in Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping.

Advanced

Debug log: writes rate calculations to var/log/vfd_crd_debug.log.php in the Magento folder. The file cannot be opened from the web. API errors and incomplete settings are always logged, even when this is off. The API key and customer addresses 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 Coordinadora settings and the log (see Uninstall). When No, they are kept for a re-install. The license key and the cached rates are always removed.

How it works at checkout

At the shipping step Magento asks the module for the Coordinadora price. Only products that need shipping count: virtual and downloadable products add no weight and are not included in the subtotal. Magento first checks Ship to Applicable Countries, then the module checks the cart weight and Minimum order subtotal. If free shipping applies, the price is 0 and no request goes to Coordinadora. A Magento cart price rule with free shipping also makes the price 0.

For an address in Colombia with an API key, the module finds the DANE code of the destination city in this order: a DANE code in the City field (Colombian cities checkout extensions write it, for example MEDELLIN (ANT) (05001000) or 05001), an 8-digit postcode, or the built-in list of department capitals and about 40 largest cities. A city from the list is checked against the department (State/Province) of the address. Accents and case are ignored. Bogotá D.C. has no department of its own in Magento and is entered with Cundinamarca.

Then the module sends Coordinadora the origin and destination DANE codes and each product with its weight (kg), dimensions (cm), quantity and declared value (COP). The declared value is the product line total after cart discounts, tax excluded. Coordinadora returns the price in COP, and the module converts it to your base currency; Magento then shows it in the customer's currency and adds tax on shipping if your store charges it. 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 module 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. International destinations use the fixed prices.

License key

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

Coordinadora does not appear at checkout: check that the license is active and Enable Coordinadora is Yes for the website of the store. Check Ship to Applicable Countries and Ship to Specific Countries, the weight limits and Minimum order subtotal. Without a live quote, a fixed price for the country or * must exist.

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

The destination city is not recognised: the customer can type the DANE code of the city into the City field, or you can install a Colombian cities checkout extension that writes it there. Developers can map more cities with the Magento events vfd_crd_dane_cities and vfd_crd_destination_dane, or change the API address with vfd_crd_api_url.

Does the rate include tax? The rate is what Coordinadora quotes. If your store taxes shipping (Tax Class for Shipping), Magento adds tax on top; do not tax shipping if the quote already includes it for you.

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

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

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

The license key, the license status and the cached quotes are always removed. If Remove data on uninstall is Yes, the Coordinadora settings and the log are removed too. If it is No, the settings are kept for a re-install. The module has no database tables of its own; existing orders are not affected.

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