VibeFox Blue Express 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.
Blue Express account (for live rates only): live rates need a Blue Express e-commerce account and its API key (x-api-key). Request it from Blue Express: developers.bluex.cl or gpo.integraciones@bx.cl. The service you use (EX, PY or MD) must be enabled in your Blue Express contract. If you only use fixed prices, you do not need an API key.
Chilean regions: for a live rate the delivery address must have a Chilean region. If your store is missing Chilean regions, the extension can add them for you (see Configuration).
Pickup points: the Blue Express map is loaded from widget-pudo.blue.cl in the customer's browser.
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_blue_express-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_blue_express.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_blue_express-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 Blue Express 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 service, the origin district code (for example SCL), the CLP exchange rate if your store currency is not CLP, and fixed prices (for example CL=4500). Turn on Enable/Disable for home delivery and Pickup point option if you want to offer pickup at Blue Express points. Click Save. See Configuration.
OpenCart 4
1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_blue_express.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 Blue Express, 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.
On install the extension creates a table for the pickup points of orders. The method is off until you turn on home delivery or the pickup point option and save. If you install the extension again after an uninstall, the Blue Express settings you kept are used again.
Configuration
All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox Blue Express > Edit. The sections are listed on the left. One Save button saves the whole page without reloading it. Every save also clears the cached Blue Express rates and commune data. Only admin users with the modify permission for this extension can save the settings. The conditions, prices and tax class below apply to both options.
Invalid values are refused with an error and nothing is saved: an empty name or a name with the characters < > ; = # { }, a name longer than 64 characters, a negative or invalid number, Min weight (kg) greater than Max weight (kg), a Sort order that is not a whole number, or an unknown tax class or geo zone.
Warnings about settings that would hide the options or the live rate are shown at the top of the page: no API key, a store currency other than CLP without an exchange rate, an empty fixed price table, no zones for Chile, and a store without a kilogram weight class or a centimeter length class whose default unit the extension does not know (weights are then read as kg and dimensions as cm).
General
Enable/Disable: turns Blue Express home delivery on or off.
Name: the shipping method name shown at checkout for home delivery. Default: Blue Express. Required, at most 64 characters.
Tax class: the tax class of the shipping cost, or None (no tax on shipping) (default). Blue Express prices include IVA. Choose None if OpenCart should not add tax on top. It applies to both options.
Sort order: the position of Blue Express among the shipping methods at checkout. A whole number.
Pickup at Blue Express points (PUDO)
Pickup point option: offers delivery to a Blue Express point chosen by the customer, as a second option next to home delivery. Off by default.
Pickup point name: the shipping method name shown at checkout for pickup at a Blue Express point. Default: Blue Express pickup point. Required, at most 64 characters.
Blue Express API (needed for live rates)
API key: your Blue Express API key (header x-api-key). Without it only the fixed prices are used. After saving, the field stays empty and shows A key is saved - leave empty to keep it. Type a new value only to change it.
Remove the saved API key: switch on and save to delete the saved key.
Service: the Blue Express service used for the rate: Express (EX) (default), Prioritario (PY) or SameDay (MD). It must be enabled in your Blue Express contract.
Origin district code: the Blue Express district code of the place you ship from, for example SCL for Santiago (default). Ask Blue Express if unsure.
CLP per 1 (your currency): the label shows your store default currency, for example CLP per 1 EUR. Blue Express prices are in Chilean pesos (CLP). Enter how many CLP one unit of your store default currency is worth, for example 1050. Without it, live rates are not used. Ignored when the store currency is CLP.
Price
Rate source: how the price is calculated. The live rate needs a Chilean address with region and commune (city). Errors are written to the log, never shown to the customer.
Fixed prices: one line per country in the format COUNTRY_CODE=PRICE, in your store default currency, tax excluded, for example CL=4500 in a CLP store or CL=4.50 in a EUR store. A comma or a point is accepted as the decimal separator. Invalid lines are ignored and listed in a warning when you save. A country without a line gets no fixed price, so the options are hidden for it when the fixed price is needed. Fixed prices can be used for any country.
Fixed price per: Order (default) charges the price once. Item (price x quantity) multiplies it by the number of items in the cart. This applies to the fixed price only. The API rate is always for the whole shipment.
Conditions
Min weight (kg): hide the method when the cart weighs less. 0 means no limit (default).
Max weight (kg): hide the method when the cart weighs more. Default: 100. 0 means no limit, an empty field means 100 kg.
Minimum order subtotal: show the method only from this cart subtotal (store currency, products that need shipping, after the coupon, without tax). Leave it empty to always show it.
Free shipping
Free shipping: turn on free shipping from a cart subtotal.
Free from subtotal: the cart subtotal (store currency, products that need shipping, after the coupon, without tax) from which shipping is free. No request goes to Blue Express then. Used only when Free shipping is on.
Availability
Geo zone: offer Blue Express only for addresses in this geo zone. All zones (default) means no limit. Geo zones are managed in System > Localisation > Geo Zones. Not checked with Ignore shipping zones.
Ignore shipping zones: offer both options in every geo zone. The countries are then limited by the list below.
Countries: the destination countries for that mode. Leave it empty to allow all countries. Only used with Ignore shipping zones.
Chilean regions (shown only when Chilean regions are missing in your store)
Blue Express needs the region of a Chilean address (RM, VS and so on) for the live rate. The region is taken from the zone of the address, by its code or its name. The section shows how many zones Chile has in your store and which regions are missing (a standard OpenCart 3.0.5 store has 15 of the 16, without Ñuble). Click Add Chilean regions to add the missing regions as zones of Chile, with the codes Blue Express uses. Regions you already have, by code or by name, are not added twice. Nothing is changed until you click the button. You can also add them yourself in System > Localisation > Zones.
Advanced
Debug log: logs requests and decisions to storage/logs/vfd_blex_debug.log.php. The file cannot be read from the web. API errors are always logged. The API key and customer addresses are never logged. Turn the log off when you are done. The log is rotated when it reaches 5 MB.
Log: shows the size and the latest entries of the log. Click Clear log to empty it.
Remove data on uninstall: when on, uninstalling the extension deletes the settings, cached rates and the log. When off (default), they are kept for a re-install. Pickup points saved in orders are 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 price of each enabled option. If a Geo zone is set (and Ignore shipping zones is off) and the address is outside it, Blue Express is not offered. With Ignore shipping zones the Countries list decides. Only products with Requires Shipping set to Yes count: other products add no weight and are not included in the subtotal. The extension checks the cart weight and Minimum order subtotal. 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. If free shipping applies, the price is 0 and no request goes to Blue Express.
For a live rate the address must be in Chile with a region and a city (commune). The extension first asks Blue Express to recognise the commune, then requests the price for the service, the origin district, the destination and the parcels. Each product is sent with its weight and dimensions converted to kg and cm from its weight and length classes. Products without weight or size are sent as 0.01 kg, 10 x 10 x 10 cm. The declared value is sent in CLP. The CLP price is converted to your store default currency, rounded to its decimals, and shown to the customer in their currency with the tax of the selected Tax class.
Rates are cached for 1 hour and commune data for up to 12 hours, but not longer than the OpenCart cache lifetime (1 hour by default). A failed API call is remembered for 5 minutes, and the timeout is 10 seconds, so a slow or unavailable API does not slow down every checkout refresh. API errors are never shown to the customer: the option is hidden, or the fixed price is used in the fallback mode. The reason is written to the log.
The extension does not create shipments or labels in Blue Express, assign tracking numbers or show tracking updates. Create the shipment in your Blue Express account. There are no regional rate tables per commune: use the Blue Express API rate or one fixed price per country. Live rates work only for Chile.
On OpenCart 4 the customer clicks Choose in the shipping method block of the checkout page and picks Blue Express or Blue Express pickup point in the window Shipping method options. The options work the same way as on OpenCart 3; the pickup point box is described in Pickup points.
Pickup points
When the pickup point option is on, a box with the button Choose pickup point appears under Blue Express pickup point in the Delivery Method step of the OpenCart checkout. The button opens the official Blue Express map, where the customer picks a point. The chosen point is shown with its name and address, and the button changes to Change pickup point. The point is saved for the checkout session, and the rate is recalculated with the Blue Express pickup (PUDO) price. If the price changes, the option shows the new price. If the option is no longer offered for that point, the delivery step reloads. Until a point is chosen, the option shows the home delivery parcel price.
The customer cannot continue without a point: Continue in the delivery step is refused with Please choose a Blue Express pickup point. This is checked in the browser and again by the store. A malformed point code is refused with The selected Blue Express pickup point is not valid. Please choose it again on the map., and the previous choice stays. If saving fails, the customer sees The pickup point could not be saved. Please try again.
On OpenCart 4 the customer clicks Choose in the shipping method block of the checkout page. The window Shipping method options shows the same box with Choose pickup point under Blue Express pickup point while that option is selected. When the price changes with the chosen point, the option in the window shows the new price, and if the pickup option was already saved for the checkout, the shipping method field and the order confirmation block are updated too. If the option is no longer offered for that point, the window is closed and the list of shipping methods is loaded again. Continue in the window without a point is held back with Please choose a Blue Express pickup point. in the box, and the store checks it again. OpenCart 4 keeps one order for the checkout and updates it at every confirmation; the pickup point of the order is updated with it, and it is removed when the order is changed to another shipping method.
When the order is placed, the point is saved in the order with its Blue Express agency code, name, address and region. It is also added to the shipping method of the order after the name of the pickup option, for example Blue Express pickup point: Blue Point Providencia, Av. Providencia 1234, so the customer sees it in the order e-mails and on the order pages of their account.
On the admin order page (Sales > Orders, View) the point is shown in the Blue Express pickup point panel with its code and region. If the order has no point, the panel shows Not chosen. Click Edit to pick another point with Choose on the Blue Express map or to enter the Agency code, Name and Address by hand, then click Save pickup point. The shipping method text of the order is updated too, and the change is added to the order history without notifying the customer (Blue Express pickup point changed: old code -> new code). Changing the point needs only the modify permission for orders, not access to the extension settings. Existing orders keep their pickup point data.
License key
The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Blue Express is the first block on Extensions > Extensions > Shipping > VibeFox Blue Express > 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-blue-express 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, Blue Express 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
Blue Express does not appear at checkout: check that the license is active and Enable/Disable (or Pickup point option) is on. Read the warnings at the top of the extension page. Check Geo zone (or Ignore shipping zones and Countries), the weight limits, Minimum order subtotal, and that Fixed prices has a line for the country if you use fixed prices or the fallback. Check that the products have Requires Shipping set to Yes.
Live rates do not appear: with Blue Express API only the options are hidden when there is no rate. Turn on Debug log, reload the checkout and look at the Log field on the extension page. Typical reasons: no API key, store currency not CLP without an exchange rate, missing region or commune in the address, a commune not recognised by Blue Express, or an API error (for example HTTP 401 or 403 when the API key is rejected). With Blue Express API, fixed price if the API gives no rate customers still get the fixed price while you fix the problem.
Chilean addresses have no region: the page shows a warning about missing regions. Click Add Chilean regions on the extension page. Customers whose addresses were saved without a region need to edit the address and choose the region.
Tax is added on top of the Blue Express price: Blue Express prices include IVA. Set Tax class to None (no tax on shipping).
The map does not open: the map is loaded from widget-pudo.blue.cl in the customer's browser, so this address must be reachable and not blocked on your site.
Rates look outdated after a change: click Save on the extension page. This clears the cached rates and commune data.
The page says "Warning: You do not have permission to modify VibeFox Blue Express!": your admin user group may only view the settings. Give the group the modify permission for extension/shipping/vfd_blue_express (OpenCart 3) or extension/vfd_blue_express/shipping/vfd_blue_express (OpenCart 4) in System > Users > User Groups.
For developers: the Blue Express API and map addresses can be replaced with the settings vfd_blex_api_url and vfd_blex_widget_url (for tests); they have no fields on the settings page.
Uninstall
Go to Extensions > Extensions, choose the type Shipping and click Uninstall (the red − button) next to VibeFox Blue Express. The license key and license status of this extension are always removed. OpenCart always resets the method status, Sort order, Tax class and Geo zone. The cached rates are always removed. If Remove data on uninstall is on, the Blue Express 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. Pickup points saved in orders are never removed, and the shipping method text of existing orders keeps the pickup point.
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 Blue Express in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.
Blue Express is a trademark of its respective owner. This extension is not affiliated with or endorsed by Blue Express.