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

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.

Chilean regions (for live rates only): live rates need the region (zone) of the delivery address. OpenCart 3.0.5.0 has 15 of the 16 Chilean regions; the extension can add the missing ones (see Chilean regions below). The country Chile must exist in the store.

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_chilexpress-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_chilexpress.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_chilexpress-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 Chilexpress 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. Fill in the Country prices table. For live rates, enter both subscription keys, your origin county code and, if the store currency is not CLP, the CLP exchange rate, click Add Chilean regions if the page shows missing regions, then choose the rate source (see Configuration). Turn on Enable/Disable and click Save.

OpenCart 4

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

Configuration

All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox Chilexpress > Edit. 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 Chilexpress rates and comuna lists were cleared. Only admin users with the modify permission for this extension can save the settings, clear the log or add regions.

The page lists problems at the top: API rates are selected but the Rating API key is empty; the Coverage API key is empty; the origin county code is empty or invalid; the store currency is not CLP and no CLP exchange rate is set; Country prices has no row for Chile or the default; Chile has no zones in the store; the store weight or length unit is not known to the extension (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). Numbers can be typed with a point or a comma. Nothing is saved and the page lists the errors if Name is empty, contains one of the characters < > ; = # { } or is longer than 64 characters, a number is invalid or negative, CLP exchange rate is 0, Min weight (kg) is greater than Max weight (kg), Origin county code is not a county code, or Sort order is not a whole number.

General

One delivery method "Chilexpress" for every geo zone, or for the geo zone selected under Availability.

Enable/Disable: shows or hides Chilexpress at checkout. Default: off.

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

Tax class: the tax class of the shipping cost, or No tax (default). Chilexpress API rates are used exactly as quoted. Choose No tax if the quote already includes IVA and your store would add tax on top.

Sort order: the position of Chilexpress among the delivery methods at checkout. A whole number.

Rates

Rate source: where the price comes from.

Live rates are available for destinations in Chile only. Other countries always use the fixed prices.

Country prices: a list of destination countries with a Price column and optional prices by parcel size in your store default currency, 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 at 0 uses Price. Click Add country to add a row. The row * Default (other countries) applies to countries without their own row. A country without a row (and without the default row) gets no fixed price, so the method is hidden there. A saved row whose price and size prices are all 0 gives free shipping. An empty table is shown with one row for Chile at 0, so enter real prices before you save the page. A repeated country or an invalid price is corrected (the duplicate is ignored, the price set to 0), and a warning 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.

Chilexpress API (live rates)

The section starts with links to the developer portal and the Rating and Coverage subscription pages.

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

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).

After saving, a key field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it. The key is saved as typed, only spaces around it are removed.

Remove the saved Rating API key and Remove the saved Coverage API key: turn one on and click Save to delete that key.

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 install. A value that is not a county code is rejected with an error.

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 your store default currency is not CLP: the price of 1 CLP in that currency, for example 0.001. Without it API rates are not used. If the store currency is CLP, leave it empty. The value must be greater than 0.

Chilean regions: the comunas of Chile are looked up per region, so live rates need the region (zone) of the address. The field shows how many zones Chile has and which regions are missing, with the button Add Chilean regions. It adds only the missing regions as zones of Chile; existing zones are not changed and a region is not added twice. When all 16 regions are in place, the field says All 16 Chilean regions are zones of Chile. If Chile is not a country of the store, the field says so: add it in System > Localisation > Countries.

Availability

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

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 cart subtotal (products that need shipping, after coupons, tax excluded) is at least this amount. Leave it empty to always show it.

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

Ignore shipping zones: offer the method for the countries below without checking the geo zone.

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

Free shipping

Free shipping: turns on the free shipping threshold.

Free shipping from: the cart subtotal (products that need shipping, after coupons, tax excluded) from which shipping is free. Used only when Free shipping is on. No API request is made in that case.

Advanced

Debug log: writes API requests and rate calculations to storage/logs/vfd_chx_debug.log.php. The file cannot be read from the web. API errors are always logged, even when this option is off. API keys and customer addresses are never logged. When the file reaches 5 MB, it is moved to vfd_chx_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 all its settings, cached rates and the log. When off (default), everything is kept for a re-install. Orders and the Chilexpress services saved with them are always kept.

Import / Export

Export: click Download JSON to save the settings as a JSON file. API keys are 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. Saved API keys are kept.

How it works at checkout

When OpenCart shows the delivery methods, it asks the extension for the Chilexpress price. If a Geo zone is set, Ignore shipping zones is off and the address is outside the zone, Chilexpress is not offered. Only products with Requires Shipping set to Yes count: other products add no weight and are not included in the subtotal. Weights are converted to kilograms and dimensions to centimetres from the weight and length classes of the products. The subtotal is the price of the products that need shipping, after the coupon discount, tax excluded, in your store default currency. Gift certificates, reward points and store credit are not taken into account. The extension first checks the conditions: allowed countries (with Ignore shipping zones), cart weight and minimum subtotal. If free shipping applies, the price is 0 and no request goes to Chilexpress.

For an address in Chile and an API rate source, the extension takes the region (zone) 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 extension sends the Rating API the origin and destination county codes, the cart weight (at least 0.1 kg), the parcel dimensions (length and width of the largest product, heights stacked) and the cart subtotal in CLP as the declared value. Chilexpress returns its services; the extension uses the chosen service or the cheapest one and converts the peso amount to your store default currency. The price is rounded to the decimals of that currency and then shown in the customer's currency with the tax of the selected Tax class.

Rates are cached for 1 hour. Comuna lists are cached for up to 7 days, but not longer than the OpenCart cache keeps its entries (1 hour by default). 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 debug log.

The extension 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.

On OpenCart 4 the customer clicks Choose in the shipping method block of the checkout page and picks Chilexpress in the window Shipping method options, for example Chilexpress - $5.49. The method works the same way as on OpenCart 3.

Orders

When an order is placed with Chilexpress, the extension saves how its price was calculated. In Sales > Orders the order page shows a Chilexpress panel with Chilexpress service (for a live rate, the service Chilexpress quoted, for example Express; otherwise a dash) and Price: Live rate (Chilexpress Rating API), Fixed price or Free shipping. The panel is also shown while the method is switched off. On OpenCart 4 the Chilexpress panel is shown above History, and when an order is confirmed again at checkout or changed to another shipping method, the panel follows the change.

License key

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

Chilexpress does not appear at checkout: check that the license is active and Enable/Disable is on. Check Geo zone (or Ignore shipping zones and Countries), the weight limits and Minimum subtotal. With fixed prices, check that the country or * Default (other countries) has a row. Check that the products have Requires Shipping set to Yes.

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

The live rate is not shown, the fixed price is used instead: first check the warnings at the top of the extension page. Otherwise turn on Debug log, reload the checkout and look at the Log field on the extension page. Typical causes: the address has no region or Chile is missing regions (use Add Chilean regions), 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 on.

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

Are API rates with or without IVA? They are used exactly as Chilexpress quotes them. If your store adds tax to shipping and the quote already includes IVA, set Tax class to No tax.

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

The page says "Warning: You do not have permission to modify VibeFox Chilexpress!": your admin user group may only view the settings. Give the group the modify permission for extension/shipping/vfd_chilexpress (OpenCart 3) or extension/vfd_chilexpress/shipping/vfd_chilexpress (OpenCart 4) in System > Users > User Groups.

For developers: the Chilexpress API base address can be replaced with the setting vfd_chx_api_base_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 Chilexpress. The license key and license status of this extension are always removed. OpenCart always resets Enable/Disable, Sort order, Tax class and Geo zone. The cached rates and comuna lists are always removed. If Remove data on uninstall is on, the other settings and the debug log are deleted as well. If it is off, they are kept and are used again when you install the extension again. The Chilexpress services saved with orders are never deleted, and existing orders keep their shipping method and cost. Chilean regions added with Add Chilean regions stay in the store.

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 Chilexpress in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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