VibeFox Blue Express 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.
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 [email protected]. 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. Magento includes the 16 Chilean regions, so customers choose the region in the address form.
Pickup points: the Blue Express map is loaded from widget-pudo.blue.cl in the customer's browser. The pickup point box works with the standard Magento checkout (Luma and Blank based themes). Other checkouts, such as Hyvä or one-step checkout extensions, need their own integration.
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-blue-express-shipping. Without Composer: unpack the ZIP file into app/code/Vibefox/BlueExpressShipping/, so that registration.php is directly in that folder.
2. Run bin/magento module:enable Vibefox_BlueExpressShipping and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy (the module has its own checkout and Admin scripts), then bin/magento cache:flush.
3. In the Admin go to Stores > Configuration > Sales > Delivery Methods and open VibeFox Blue Express. 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 service, the origin district code (for example SCL), the CLP exchange rate if the base currency of your store is not CLP, and fixed prices (for example CL=4500 in a CLP store). Set Pickup point option to Yes if you want to offer pickup at Blue Express points. Set Enable Blue Express to Yes and click Save Config. See Configuration.
The module adds the Blue Express carrier with two methods. Customers see them as Blue Express - Home delivery and Blue Express - Pickup point (method title and method name). After installation the module is off (Enable Blue Express = No), Home delivery is Yes and Pickup point option is No. The module also creates its own table for the pickup points of carts and orders.
Configuration
All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox Blue Express, 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, Name and Pickup point 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 Blue Express rates and commune data. Amounts accept "9.99" and "9,99". The conditions and prices apply to both methods.
If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Method title, Name or Pickup point name, longer than 64 characters or with one of the characters < > ; = # { }; a Sort order that is not a whole number; a number field that does not contain a number of 0 or more; a Min weight (kg) greater than the Max weight (kg).
Warnings at the top of the group remind you of settings that stop live rates or hide the methods: no API key (with Blue Express API only the methods are then hidden at checkout), a base currency other than CLP without CLP per 1 unit of base currency, and an empty fixed price table.
General
Enable Blue Express: shows or hides both Blue Express methods at checkout. Default: No. The two delivery options are switched on in their own sections below.
Method title: the carrier name shown to the customer before the method name, as "Method title - Name". Default: Blue Express. Required, at most 64 characters.
Sort order: the position among the shipping methods at checkout. A whole number, negative numbers are allowed.
Home delivery
Home delivery: offers Blue Express delivery to the customer's address. Default: Yes.
Name: the method name shown at checkout for home delivery, after the method title. Default: Home delivery. Required, at most 64 characters.
Pickup at Blue Express points (PUDO)
Pickup point option: offers delivery to a Blue Express point chosen by the customer, as a second method next to home delivery. Default: No.
Pickup point name: the method name shown at checkout for pickup at a Blue Express point, after the method title. Default: 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. 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.
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. An empty field means SCL.
CLP per 1 unit of base currency: Blue Express prices are in Chilean pesos (CLP). If the base currency of your store is not CLP, enter how many CLP one unit of it is worth, for example 950 for USD. Without it, live rates are not used. Ignored when the base currency is CLP.
Price
All prices are in the base currency of your store, tax excluded. The module has no tax field: if your store charges tax on shipping, set the tax class in Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping. Blue Express prices include IVA.
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 the base currency, tax excluded, for example CL=4500 in a CLP store or CL=4.50 in a USD store. A comma or a point is accepted as the decimal separator. Invalid lines are removed when you save, and a warning lists them. A country without a line gets no fixed price, so the methods 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 methods when the cart weighs less. 0 means no limit.
Max weight (kg): hide the methods when the cart weighs more. Default: 100. 0 means no limit, an empty field means 100 kg.
Minimum order subtotal: show the methods only from this subtotal of the products that need shipping (base currency, after discounts, without tax). Leave empty to always show them.
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 each cart line is sent to Blue Express as a 10 x 10 x 10 cm package.
Free shipping
Free shipping: turns on free shipping from a cart subtotal. Default: No.
Free from subtotal: the subtotal of the products that need shipping (base currency, after discounts, without tax) from which shipping is free. Used only when Free shipping is Yes.
Availability
Ship to Applicable Countries: All Allowed Countries offers Blue Express for every country your store allows, Specific Countries only for the countries below.
Ship to Specific Countries: the destination countries for Specific Countries, usually Chile. Live rates are requested for Chile only; other countries use the fixed prices.
Advanced
Debug log: logs requests and decisions to var/log/vfd_blex_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. 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 Yes, uninstalling the module with its data deletes the Blue Express settings, the log and the pickup points of carts that never became an order (see Uninstall). The license key and the cached rates are always removed. Pickup points saved in orders are always kept.
How it works at checkout
At the shipping step Magento asks the module for the price of each Blue Express method that is switched on. Only products that need shipping count: virtual and downloadable products add no weight and are not included in the subtotal. The module checks the countries, the cart weight and Minimum order subtotal. If free shipping applies, the price is 0 and no request goes to Blue Express. A Magento cart price rule with free shipping also makes the price 0.
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 packages. Products without weight are sent as 0.01 kg. The declared value is sent in CLP. The CLP price is converted to your base currency; Magento then shows it in the customer's currency and adds tax on shipping if your store charges it.
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 method is hidden, or the fixed price is used in the fallback mode. The reason is written to the log.
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 shipping step, a box appears under the shipping methods with the text Choose the Blue Express point where you will pick up your order. and the button Choose pickup point. The button opens the official Blue Express map in a window, 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 cart. With live rates the shipping rates are then requested again with the Blue Express pickup (PUDO) price. Until a point is chosen, the method shows the home delivery parcel price.
The customer cannot go on to payment without a point: clicking Next shows Please choose a Blue Express pickup point. The store checks this again on the server. 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 the point cannot be saved, the customer sees The pickup point could not be saved. Please try again.
When the order is placed, the point is added to the shipping description of the order, for example "Blue Express - Pickup point: Blue Point Providencia, Av. Providencia 1234, Providencia". The customer sees it in the order in their account, in the order e-mails and on invoices.
On the admin order page (Sales > Orders > View, Information tab) the Blue Express pickup point block shows the name, the address, the Blue Express agency code and the region of the point. Click Edit to pick another point with Choose on the Blue Express map or to enter the Agency code, Name, Address and Region by hand, then click Save pickup point. The shipping description of the order changes too, and a changed point is recorded as an order comment the customer is not notified about. Edit needs the role permission to edit orders (Sales > Operations > Orders > Actions > Edit), not access to the configuration. An order placed with the pickup point method but without a point (for example created in the Admin) shows No pickup point was selected for this order., and you can add the point with Edit. The block also works for older orders and when the module is switched off.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Blue Express is the first row of the VibeFox Blue Express 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-blue-express 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 Blue Express methods are 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 methods are 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: their pickup points are still shown and can be changed.
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
Blue Express does not appear at checkout: check that the license is active and Enable Blue Express is Yes for the website of the store, and that Home delivery or Pickup point option is Yes. Read the warnings at the top of the group. Check Ship to Applicable Countries and Ship to Specific 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.
Live rates do not appear: with Blue Express API only the methods are hidden when there is no rate. Turn on Debug log, reload the checkout and look at the Log field in the Advanced section. Typical reasons: no API key, a base currency other than 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.
Tax is added on top of the Blue Express price: Blue Express prices include IVA. Do not tax shipping in Tax Class for 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 Config on the Delivery Methods page. This clears the cached rates and commune data.
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, the settings and the pickup point table stay. To remove the data, uninstall the module with the Magento command:
Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_BlueExpressShipping. It removes the data and the code.
Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_BlueExpressShipping to remove the data, then bin/magento module:disable Vibefox_BlueExpressShipping, delete the folder app/code/Vibefox/BlueExpressShipping and run bin/magento setup:upgrade.
The license key, the license status and the cached rates are always removed. If Remove data on uninstall is Yes, the Blue Express settings, the log and the pickup points of carts that never became an order are removed too. If it is No, the settings are kept for a re-install. Pickup points saved in orders are never removed, and the shipping descriptions of orders keep the point.
Blue Express is a trademark of its respective owner. This module is not affiliated with or endorsed by Blue Express.