VibeFox Chilexpress for Adobe Commerce — Ayuda

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.

Chilexpress API keys (for live rates only): create an account on the Chilexpress developer portal (developers.wschilexpress.com) and subscribe to two products: Rating (Cotizador) and Coverage (Coberturas / Georreferencia). Each product has its own subscription key. Test keys work only with the test environment; production keys are issued to Chilexpress business customers with a customer contract. You also need the Chilexpress county code of the comuna you ship from, for example STGO. If you only use fixed prices, you do not need API keys.

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

2. Run bin/magento module:enable Vibefox_ChilexpressShipping 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 Chilexpress. 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. Fill in the Country prices table. For live rates, enter both subscription keys, your origin county code and, if the base currency of your store is not CLP, the CLP exchange rate, then choose the Rate source (see Configuration). Set Enable Chilexpress to Yes and click Save Config.

The module adds the Chilexpress shipping method to Magento. Customers see it as Chilexpress - Courier delivery (method title and method name). It is off after installation (Enable Chilexpress = No) and is offered for Chile only until you add other countries in Ship to Specific Countries. The module creates a table for the Chilexpress data of orders.

Configuration

All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox Chilexpress, 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 Chilexpress rates and comuna lists. 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, 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; a CLP exchange rate of 0; a Min weight (kg) greater than the Max weight (kg); an Origin county code that is not a Chilexpress county code.

While Enable Chilexpress is Yes, warnings after saving remind you of settings that stop live rates or hide the method: API rates are selected but the Rating API key, the Coverage API key or a valid origin county code is missing; the base currency is not CLP and the CLP exchange rate is empty; Country prices has no row for Chile (CL) or the default (*). The warnings are shown only while the method is enabled, because the Delivery Methods page is shared by all shipping methods.

General

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

Method title: the shipping method name shown to the customer in the cart and at checkout. Default: Chilexpress. 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.

Rate source: where the price comes from.

Live rates are available for destinations in Chile only. Other countries always use the fixed prices. When the API has no rate, the reason is written to the module log, never shown to the customer.

Chilexpress API (live rates)

The section starts with links to the developer portal and the Rating and Coverage subscription pages. The customer's comuna is the City field of the address, its region the State/Province of Chile.

Test environment: uses the Chilexpress test environment (qaservices.wschilexpress.com). Use it with test keys and set it to No on a live store. Default: No.

Rating API key: the subscription key of the Rating (Cotizador) product.

Coverage API key: the subscription key of the Coverage (Coberturas / Georreferencia) product. It is used to find the Chilexpress county code of the customer's comuna (the City field of the address, together with its region).

Both keys are kept as typed, only spaces around them are removed. They are never written to the log. Magento stores them 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 a saved key, clear the field and click Save Config.

Origin county code: the Chilexpress county (comuna) code you ship from, 2–5 letters, for example STGO (Santiago Centro), PROV (Providencia) or VALP (Valparaíso). It is empty after installation and is saved in upper case.

Service: the Chilexpress service used for the rate. If it is not offered for the destination, the cheapest offered service is used.

CLP exchange rate: Chilexpress quotes in Chilean pesos. Needed only if the base currency of the website is not CLP: the price of 1 CLP in the base currency, for example 0.001. Without it API rates are not used. If the base currency is CLP, leave it empty. The value must be greater than 0.

Fixed prices (used when Rate source is Fixed prices, outside Chile, and as the fallback for API rates)

Country prices: a table of destination countries with a Price column and optional prices by parcel size (XS, S, M, L, XL) in the base currency of your store, tax excluded. The size comes from the cart weight: XS up to 1 kg, S up to 2 kg, M up to 3 kg, L up to 5 kg, XL above 5 kg. A size left empty or at 0 uses Price. Click Add country to add a row and Delete to remove one. The row * Default (all other countries) applies to countries without their own row. A country without a row (and without * Default) gets no fixed price, so the method is hidden there. A saved row of zeros (or of empty prices) means free shipping for that country. The table is empty after installation. The table never blocks saving: an invalid or negative price is set to 0 and a repeated country keeps its first row; a warning Chilexpress country prices: lists the corrections.

Calculation type: Per order (default) charges the fixed price once. Per item (fixed price x number of items) multiplies it by the number of items in the cart. A Chilexpress API rate is always quoted for the whole parcel.

Availability and free shipping

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

Max weight (kg): the method is hidden above this cart weight. Default: 25. 0 means no limit, an empty field means 25 kg.

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

Free shipping: turns on the free shipping threshold 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 request goes to Chilexpress in that case.

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

Ship to Specific Countries: the destination countries for Specific Countries. Default: Chile. Countries other than Chile 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). Magento products have no standard dimensions, so the live rate is quoted by weight.

The module has no tax field. Tax on shipping follows Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping. Chilexpress API rates are used exactly as quoted; if the quote already includes IVA, do not tax shipping there, so IVA is not charged twice.

Advanced

Debug log: writes API requests and rate calculations to var/log/vfd_chx_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. API keys 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 Chilexpress 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. The services saved with orders are order history and are never deleted.

How it works at checkout

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

For an address in Chile and an API rate source, the module takes the region of the address and the comuna from the City field and looks up the Chilexpress county code in the comuna list of that region (Coverage API). Accents, spaces and spelling variants are ignored, so Ñuñoa and Nunoa match, and Santiago matches Santiago Centro. A county code typed in the City field is accepted too. Then the module sends the Rating API the origin and destination county codes, the cart weight (at least 0.1 kg), a minimal parcel size of 1 × 1 × 1 cm (Magento products have no dimensions) and the cart subtotal in CLP as the declared value. Chilexpress returns its services; the module uses the chosen service or the cheapest one, with your contract price when Chilexpress returns one, and converts the peso amount to your base currency. The price is rounded to 2 decimals; Magento then shows it in the customer's currency and adds tax on shipping if your store charges it. The customer sees one price, not a choice of Chilexpress services.

Rates are cached for 1 hour and comuna lists for 7 days. A failed request is remembered for 5 minutes, so a slow or unavailable API does not slow down every checkout refresh. The API timeout is 10 seconds. If Chilexpress returns an error, no service with a price, or the comuna or region is unknown, the customer sees no error. The method is hidden in the API-only mode, or the fixed price is used. The reason is written to the log.

The module calculates rates only. It does not create shipments or transport orders (OT), print labels, book pickups or track parcels; book the shipment in your Chilexpress account. Customers cannot choose a Chilexpress office, and there is no comuna selector: the customer types the comuna in the standard City field. International shipments use the fixed prices.

Orders

When an order is placed with Chilexpress, the module saves how its price was calculated. On the admin order page (Sales > Orders > View, Information tab) the Chilexpress block shows Chilexpress service (for a live rate, the service Chilexpress quoted and its code, for example EXPRESS (code 3)), Price source (Chilexpress API, Fixed price or Free shipping) and Calculated price (excl. tax) in the base currency. The block also works for older orders and when the module is switched off. Customers do not see it.

License key

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

Chilexpress does not appear at checkout: check that the license is active and Enable Chilexpress is Yes for the website of the store. Check Ship to Applicable Countries and Ship to Specific Countries (Chile only by default), the weight limits and Minimum subtotal. With fixed prices, check that the country or * Default has a row in Country prices.

Shipping in Chile is free although it should not be: the Country prices row for Chile (or * Default) has 0 or nothing in Price and in the size columns. Enter the prices and click Save Config.

The live rate is not shown, the fixed price is used instead: first check the warnings shown after Save Config. Otherwise turn on Debug log, reload the checkout and look at the Log field in the Advanced section. Typical causes: the address has no region, a comuna that Chilexpress does not recognise (check the City field and the region), a key for the wrong product or environment, or a destination without Chilexpress coverage.

HTTP 401 or 403 in the log: the subscription key is wrong, inactive, or for another product or environment. Test keys work only with Test environment = Yes.

API rates are not used in a store with another base currency: enter the CLP exchange rate.

Are API rates with or without IVA? They are used exactly as Chilexpress quotes them. If the quote already includes IVA and your store taxes shipping, do not tax shipping in Tax Class for Shipping.

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

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

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

The license key, the license status, the cached rates and comuna lists are always removed. If Remove data on uninstall is Yes, the Chilexpress settings and the log are removed too. If it is No, the settings are kept for a re-install. The Chilexpress data of orders (service and price source) stays with the orders.

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