VibeFox Blue Express for PrestaShop — Help
Requirements
PrestaShop: 8.0 to 9.x.
PHP: 8.0 or later. The module refuses to install on older PHP versions.
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 shop has no regions for Chile, the module 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
1. In the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.
2. When the upload finishes, click Configure, or find VibeFox Blue Express in the module list later and click Configure.
3. Paste your VibeFox license key into License key in the license block at the top of the Configure page and click Activate (see License key).
4. Enter the API key, the service, the origin district code (for example SCL), the CLP exchange rate if your shop currency is not CLP, and fixed prices (for example CL=4500). Turn on Pickup point carrier if you want to offer pickup at Blue Express points. Click Save. See Configuration.
On install the module creates two carriers: Blue Express (home delivery, delivery time text Home delivery, turned on) and Blue Express pickup point (delivery time text Pickup at a Blue Express point, turned off until you enable it). Both are assigned to the zone of Chile and to all customer groups. You can change zones, customer groups, delivery time, logo and size limits in Shipping > Carriers. Do not set prices there: the price always comes from the module.
Configuration
All settings are on the module page: Modules > Module Manager > VibeFox Blue Express > Configure. Each section has its own Save button, which saves the whole page. Every save also clears the cached Blue Express rates and commune data. Warnings about settings that would hide the carriers or the live rate are shown at the top of the page: no API key, shop currency not CLP without an exchange rate, an empty fixed price table, no regions for Chile, a shop weight or dimension unit the module does not know (weights are then read as kg and dimensions as cm), or a deleted carrier. Invalid values are refused with an error and nothing is saved: an empty or invalid carrier name, a name longer than 64 characters, a negative or invalid number, or Min weight (kg) greater than Max weight (kg). The conditions and prices below apply to both carriers.
General
Enable/Disable: turns the home delivery carrier on or off. This is the same switch as the carrier status in Shipping > Carriers.
Name: the carrier name shown at checkout for home delivery. Default: Blue Express. Required, at most 64 characters.
Tax status: None (no tax on shipping) or Taxable with one of your tax rules. Blue Express prices include IVA. Choose None if PrestaShop should not add tax on top. It applies to both carriers.
Pickup at Blue Express points (PUDO)
Pickup point carrier: offers delivery to a Blue Express point chosen by the customer, as a second carrier next to home delivery. Off by default. This is the same switch as the status of the Blue Express pickup point carrier in Shipping > Carriers.
Pickup point name: the carrier 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. Tick Remove the saved API key and save to delete it.
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 unit of store currency: when your shop default currency is not CLP, the label shows it, for example CLP per 1 EUR. Blue Express prices are in Chilean pesos (CLP). Enter how many CLP one unit of your shop default currency is worth, for example 1050. Without it, live rates are not used. Ignored when the shop 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 shop default currency, tax excluded, for example CL=4500 in a CLP shop or CL=4.50 in a EUR shop. 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 carriers are hidden for it when the fixed price is needed. Fixed prices can be used for any country.
Fixed price per: Order 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 carriers when the cart weighs less. 0 means no limit.
Max weight (kg): hide the carriers when the cart weighs more. Default: 100. 0 means no limit, an empty field means 100 kg. Min weight (kg) cannot be greater than Max weight (kg).
Minimum order subtotal: show the carriers only from this cart subtotal (shop currency, after discounts, without tax). Leave empty to always show them.
Free shipping
Free shipping: turn on free shipping from a cart subtotal.
Free from subtotal: the cart subtotal (shop currency, after discounts, without tax) from which shipping is free. Used only when Free shipping is on.
Availability without shipping zones
Ignore shipping zones: offers both carriers in every zone. The countries are then limited by the list below. Zones created later are added too. When you switch it off again, the carriers get back the zones they had before.
Countries: the destination countries for that mode. Leave empty to use all countries you ship to. Only used with Ignore shipping zones.
Advanced
Debug log: logs requests and decisions to logs/vfd_blex_debug.log.php in the module folder. The file cannot be opened 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.
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 module deletes the settings and the carriers. Pickup points saved in orders are kept.
Chilean regions (shown only when your shop has no usable regions for Chile)
Blue Express needs the region of a Chilean address (RM, VS and so on) for the live rate. PrestaShop does not include Chilean regions by default. Click Add Chilean regions to add the 16 Chilean regions as states of Chile, with the codes Blue Express uses, and to show the region field in the Chilean address form. 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 International > Locations > States with the codes RM, VS and so on.
How it works at checkout
At the shipping step PrestaShop asks the module for the price of each Blue Express carrier. Only physical products count: virtual products add no weight and are not included in the subtotal. The module checks Countries (with Ignore shipping zones), the cart weight and Minimum order subtotal. 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 module 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. 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 shop default currency and then shown in the customer's cart currency.
Rates are cached for 1 hour and commune data for 12 hours. 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 carrier is hidden, or the fixed price is used in the fallback mode. The reason is written to the log.
If you edit a carrier in Shipping > Carriers after it has orders, PrestaShop saves it as a new carrier version. The module follows the new version automatically.
The module 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.
Pickup points
When the customer selects Blue Express pickup point in the delivery step, a box with the button Choose pickup point appears under it. 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 in the cart, and the rate is recalculated with the Blue Express pickup (PUDO) price. If the price changes, the page reloads to show it. Until a point is chosen, the carrier shows the home delivery parcel price.
The customer cannot continue without a point: Please choose a Blue Express pickup point. This is checked by the shop when the customer clicks Continue in the delivery step. 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.
When the order is placed, the point is saved in the order with its Blue Express agency code, name and address. On the admin order page it is shown in the Blue Express pickup point block. 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 change is recorded as a private order message. Changing the point needs only edit rights for orders, not access to the Modules pages. The customer sees the point on the order confirmation page, on the order detail page and in the order confirmation e-mail, next to the carrier name. The new order e-mail to the shop (from the Mail alerts module) also shows the agency code. Existing orders keep their pickup point data.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Blue Express is the first block on Modules > Module Manager > VibeFox Blue Express > Configure, 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 shop. Below them are the line Product: presta-shipping-blue-express and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office 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 shop 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 main shop, also in a multistore setup. Removing the key from the shop does not free its domain slot. Free the slot in your vibefox.net account.
Without an active key, the Blue Express carriers are not shown to customers at checkout and no rate is calculated. The PrestaShop storefront does not know that you are logged in to the back office, so the carrier 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 Modules > Module Manager on the Alerts tab. 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 while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module 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 carrier) is on. In Shipping > Carriers check that the carrier covers the zone of the customer's country and the customer's group, or turn on Ignore shipping zones and check Countries. Read the warnings at the top of the module page. Check the weight limits, Minimum order subtotal, and that Fixed prices has a line for the country if you use fixed prices or the fallback. Products can also be limited to certain carriers in the product page.
Live rates do not appear: with Blue Express API only the carriers are hidden when there is no rate. Turn on Debug log, reload the checkout and look at the Log field on the module page. Typical reasons: no API key, shop 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 module 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 status 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 module page. This clears the cached rates and commune data.
The page says a Blue Express carrier is missing: the carrier was deleted in Shipping > Carriers. Reset the module in Modules > Module Manager to create it again. Reset keeps your settings and the status of the carriers.
Uninstall
Go to Modules > Module Manager, open the menu next to VibeFox Blue Express and choose Uninstall. The license key, the license status and the cached rates are always removed. If Remove data on uninstall is on, both carriers are deleted (orders keep their history), and the settings, the log and pickup points not linked to an order are removed. If it is off, the carriers are only disabled and all settings are kept. Installing the module again restores the carriers with the status they had before. Pickup points saved in orders are never removed.
Blue Express is a trademark of its respective owner. This module is not affiliated with or endorsed by Blue Express.