VibeFox SF 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.
SF Express account (for live prices only): live prices use the SF Express FengQiao open platform (open.sf-express.com). You need an SF Express monthly account and a developer account on FengQiao. Register there, create an application, add the API "Delivery time standard and price query" (EXP_RECE_QUERY_DELIVERTM) to it and copy the customer code and the checkword. The sandbox and production checkwords differ. If you only use the price table, you do not need an SF Express account.
Chinese provinces (for live prices only): the live price needs the province of the delivery address. PrestaShop has no Chinese provinces by default. The module can add them for you (see Chinese provinces below).
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 SF 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. Fill in the price table and / or the fallback cost and click Save.
5. For live prices in mainland China, enter the customer code and the checkword, the sender province and city (or set a Chinese shop address) and, if your shop currency is not CNY, the currency conversion rate. Click Add Chinese provinces if the page asks for it. Test with Sandbox and sandbox credentials first.
On install the module creates the SF Express carrier with the delivery time text Courier delivery. The carrier is assigned to all zones and 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 SF Express > Configure. They apply to every zone of the carrier. Each section has its own Save button, which saves the whole page. Every save also clears the cached SF Express prices.
When you save, the module checks the numbers. A value that is not a number, a negative amount or weight, a currency conversion rate of 0, a Min weight above Max weight or a wrong price in the price table is refused with a message, and nothing is saved until you correct it. Warnings above the settings tell you when live prices are partly set up (the missing settings are listed), when the currency conversion rate is missing, when Chinese addresses have no province field, or when your shop weight or dimension unit is not known to the module. Units are set in International > Localization (Local units).
General
Enable SF Express: turns the carrier on or off. This is the same switch as the carrier status in Shipping > Carriers.
Method title: the carrier name shown in the cart and at checkout. Default: SF Express. Required, 64 characters at most.
Tax: the tax rule of the carrier, or No tax. With a tax rule, your shop shipping tax is added on top of the cost. Choose No tax if the SF Express price already includes everything you want to charge.
SF Express FengQiao API (live prices) (optional, for delivery addresses in mainland China)
Customer code (partnerID): the customer code (顾客编码) of your FengQiao application. Clearing it also clears the saved checkword, so you can remove the credentials.
Checkword: the checkword (校验码) of the same environment. It is used only to sign requests and is never sent or logged. After saving, the field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it.
Sandbox: use the FengQiao sandbox (sfapi-sbox.sf-express.com) for testing with sandbox credentials. Sandbox prices are not real. Switch it off in a live shop. Default: off.
SF Express product: which SF Express product price is shown.
Sender province: the province the parcels are sent from. Leave it empty to use the province of the shop address in Shop Parameters > Contact > Stores, when the shop is in China.
Sender city: the standard Chinese city name, for example 深圳市. Leave it empty to use the shop city, when the shop is in China.
Currency conversion rate: SF Express prices are in CNY (yuan). If your shop default currency is not CNY, enter how many units of your currency one CNY is worth (1 CNY = ? units). Without it, live prices are not used. If your shop currency is CNY, prices are used as they are. Both a point and a comma are accepted as the decimal separator.
Chinese provinces: shows whether Chinese addresses can have a province. If not, click Add Chinese provinces. The button adds the 32 provinces, autonomous regions and municipalities as states of China (ISO codes such as GD and BJ, names such as "Guangdong / 广东"), turns on "Contains states" for China and adds the state field to the Chinese address form. Provinces that already exist are not added again. Nothing is changed without this click.
Price table and fallback (used for Hong Kong, Macao, Taiwan and other countries, when live prices are not configured, or when SF Express gives no price; prices are in your shop default currency, tax excluded)
Country prices: a table with a base price per country. Click Add country to add a row and the trash icon to remove one. The row * All other countries applies to all countries without their own row. A weight tier price above 0 replaces the base price for parcels in that tier: XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg and XL >5 kg. A base price of 0 means free shipping. An empty base price means no price for this country, and the fallback cost is used. Both "9.99" and "9,99" are accepted. A row without any price is not saved.
Fallback cost: used when neither SF Express nor the table gives a price. Leave it empty to hide the carrier in that case.
Table / fallback price is: how table and fallback prices are charged.
Live SF Express prices are always for the whole order.
Conditions
Free shipping from: the cart subtotal (after discounts, before tax) from which shipping is free. Leave it empty to never offer free shipping. Free shipping is checked before any price is looked up, so from this amount the carrier is offered free for every destination it is available for, even a country without a table row or Fallback cost.
Minimum subtotal: show the carrier only when the cart subtotal (after discounts, before tax) reaches this amount. Leave it empty to always show it.
Min weight: the minimum cart weight in kg. Product weights are converted from your shop weight unit. 0 means no limit.
Max weight: the maximum cart weight in kg. Default: 50. 0 or empty means no limit.
Availability without shipping zones
Ignore shipping zones: offer SF Express for the countries below whatever zone matches. On save the carrier is added to all zones, and zones created later are added too. Switching the option off removes those added zones again. When off, the carrier appears only in its own zones.
Countries: the destination countries for that mode. Leave empty to allow all active countries. This field is used only when Ignore shipping zones is on.
Advanced
Debug log: writes price calculations to logs/vfd_sfex_debug.log.php in the module folder. The file cannot be opened from the web. API errors are always logged, even when this option is off. No checkword or customer addresses are written.
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, the carrier, cached prices and logs. When off, everything is kept for a re-install.
How it works at checkout
At the shipping step PrestaShop asks the module for the SF Express price. Only physical products count: virtual products add no weight and are not included in the subtotal. The module first checks the conditions: allowed countries (with Ignore shipping zones), cart weight and minimum subtotal. If the subtotal reaches Free shipping from, the price is 0 and no request goes to SF Express.
For a delivery address in mainland China with the customer code and checkword set, the module sends SF Express your sender province and city, the customer's province and city, the cart weight and the cart volume (from products with all three dimensions). The request is signed with your checkword. SF Express returns prices in CNY, and the module converts the chosen one to your shop default currency. The price is then shown in the customer's cart currency.
SF Express recognises addresses by standard Chinese names. The customer's province comes from the state field of the address. The city must be written in Chinese, for example 广州市. For Beijing, Shanghai, Tianjin and Chongqing the city is filled in automatically. A city in Latin letters, such as "Guangzhou", gets the table price.
Each price is cached for an hour, so the same cart does not trigger a new request. A failed request is cached for 10 minutes, so the checkout does not wait for SF Express on every refresh. The HTTP timeout is 10 seconds.
If there is no live price, the price comes from the price table, then from Fallback cost. If neither applies, the carrier is hidden. The customer never sees an error. The error is written to the log.
If you edit the 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 calculates prices only. It does not create waybills or labels, create orders in SF Express, book pickups, cancel or track shipments. Create and track shipments in your SF Express account as usual. Customers cannot choose an SF service point or locker. SF Express is used as a door-to-door courier. Live prices exist only for delivery addresses in mainland China. The module was built against the FengQiao documentation and mocked responses, so confirm the prices with your SF Express account (sandbox first) before going live.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox SF Express is the first block on Modules > Module Manager > VibeFox SF 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-sf-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 SF Express carrier is not shown to customers at checkout and no price 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
SF Express does not appear at checkout: check that the license is active and Enable SF Express 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). Check the weight limits and Minimum subtotal. Check that the table or Fallback cost has a price for the country. Products can also be limited to certain carriers in the product page.
The price comes from the table, not from SF Express: live prices need the customer code and checkword, a sender province and city, a delivery address in mainland China with a province and a Chinese city name, and (for non-CNY shops) the currency conversion rate. Read the warnings at the top of the module page, then turn on Debug log, reload the checkout and look at the Log field to see the reason. A failed request is retried after 10 minutes.
The address form for China has no province: click Add Chinese provinces in the API section of the module page.
Error A1006 in the log: invalid signature. The checkword is wrong or belongs to the other environment. Check the Sandbox setting.
Error A1004 in the log: the price query API is not added to your FengQiao application.
Hong Kong: works with the price table and the fallback cost. The FengQiao price query is for mainland China addresses.
Rates look outdated after a change: click Save on the module page. This clears the cached SF Express prices.
The page says the SF Express carrier was not found: the carrier was deleted in Shipping > Carriers. Reset the module in Modules > Module Manager to create it again.
For developers: the hook actionVfdSfExpressQuoteRequest changes the price request, for example to another product code. actionVfdSfExpressApiUrl changes the gateway URL.
Uninstall
Go to Modules > Module Manager, open the menu next to VibeFox SF Express and choose Uninstall. The license key and the license status are always removed. The cached prices are always removed. If Remove data on uninstall is on, the carrier is deleted (orders keep their history) and the settings and log are removed. If it is off, the carrier is only disabled and all settings are kept. Installing the module again, or a Reset, gives the carrier back the status it had before. Existing orders keep their shipping lines.
SF Express is a trademark of its respective owner. This module is not affiliated with or endorsed by SF Express.