VibeFox SF 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.
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, which is the OpenCart zone (Region / State) of the address. OpenCart has the zones of China, but Tibet is missing. The extension can add it for you (see Chinese provinces below).
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_sf_express-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_sf_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_sf_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 SF 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. Fill in the price table and / or the fallback cost.
6. For live prices in mainland China, enter the customer code and the checkword, the sender province and city and, if your store 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.
7. Turn on Enable SF Express and click Save.
OpenCart 4
1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_sf_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 SF Express, click Install (the green + button), then Edit (the pencil button).
4. Enter the license key and the settings as in steps 4 to 7 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 SF Express and save. If you install the extension again after an uninstall, the SF Express settings you kept are used again.
Configuration
All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox SF Express > Edit. The sections are listed on the left. They apply to every geo zone. One Save button at the bottom saves the whole page without reloading it. Every save also clears the cached SF Express prices. Only admin users with the modify permission for this extension can save the settings.
When you save, the extension checks the values. A method title that is empty, longer than 64 characters or contains < > ; = # { }, a value that is not a number, a negative amount or weight, a currency conversion rate of 0, a Min weight (kg) above Max weight (kg), a wrong price in the price table or a sort order that is not a whole number 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 the store has no zones of China, or when your store has no kg weight class or cm length class and its default unit is not known to the extension.
General
Enable SF Express: shows or hides SF Express at checkout. Default: off.
Method title: the method name shown in the cart and at checkout. Default: SF Express. Required, 64 characters at most.
Tax class: the tax class of the shipping cost, or No tax. With a tax class, your store shipping tax is added on top of the cost. Choose No tax if the SF Express price already includes everything you want to charge.
Sort order: the position of SF Express among the shipping methods at checkout. A whole number.
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 store. Default: off.
SF Express product: which SF Express product price is shown.
Sender province: the province the parcels are sent from, for example Guangdong / 广东. The first option uses the region of your store (System > Settings > Store > Local) when the store is in China. It then reads Same as the store region with the province name, otherwise — Select —.
Sender city: the standard Chinese city name, for example 深圳市. Required for live prices: the OpenCart store address is free text, so the city is never taken from it.
Currency conversion rate: SF Express prices are in CNY (yuan). If your store default currency is not CNY, enter how many units of your currency one CNY is worth (1 CNY = ? units), for example 0.13. Without it, live prices are not used. If your store currency is CNY, the field says it is not needed and prices are used as they are. Both a point and a comma are accepted as the decimal separator.
Chinese provinces: shows how many of the 32 SF Express provinces, autonomous regions and municipalities are zones of China in OpenCart, and which are missing. Addresses in a missing province get the table price. Click Add Chinese provinces to add only the missing ones as zones of China (ISO code, a name such as "Tibet / 西藏"). Existing zones are not changed. Nothing is changed without this click. Zones added this way stay in the store after an uninstall.
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 store default currency, tax excluded)
Country prices: a table with a base price per country. Click Add country to add a row and the remove button to delete 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 up to 1 kg, S up to 2 kg, M up to 3 kg, L up to 5 kg and XL above 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 method 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 (products that need shipping, after the coupon, 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 method is offered free for every destination it is available for, even a country without a table row or Fallback cost.
Minimum subtotal: show the method only when that cart subtotal reaches this amount. Leave it empty to always show it.
Min weight (kg): the minimum cart weight in kg. Product weights are converted from their weight class. 0 means no limit.
Max weight (kg): the maximum cart weight in kg. Default: 50. 0 or empty means no limit.
Geo zone: offer SF Express only for addresses in this geo zone. All zones (default) means no limit. Geo zones are managed in System > Localisation > Geo Zones. It is not checked when Ignore shipping zones is on.
Availability without shipping zones
Ignore shipping zones: offer SF Express for the countries below whatever the geo zone. When off, the geo zone decides and the country list is not used.
Countries: the destination countries for that mode. Leave empty to allow all enabled countries. This field is used only when Ignore shipping zones is on.
Advanced
Debug log: writes price calculations to storage/logs/vfd_sfex_debug.log.php. The file cannot be read from the web. API errors are always logged, even when this option is off. No checkword or customer addresses are written. When the file reaches 5 MB, it is moved to vfd_sfex_debug.old.log.php and a new log is started.
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 and the log. When off (default), the settings are kept for a re-install. Cached prices are always deleted.
Import / Export
Export: click Download JSON to save the settings as a JSON file, without the checkword.
Import: paste previously exported JSON and click Import to restore the settings. The values are checked like a normal save. The saved checkword is kept.
How it works at checkout
When OpenCart shows the shipping methods, it asks the extension for the SF Express price. If a Geo zone is set and the address is outside it, SF Express is not offered (unless Ignore shipping zones is on). Only products with Requires Shipping set to Yes count: other products add no weight and are not included in the subtotal. The subtotal is the price of these products after the coupon discount and before tax. Gift certificates, reward points and store credit are not taken into account. The extension then 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 extension sends SF Express your sender province and city, the customer's province and city, the cart weight (at least 0.1 kg) 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 extension converts the chosen one to your store default currency and rounds it to its decimals. The price is then shown in the customer's currency with the tax of the selected Tax class.
SF Express recognises addresses by standard Chinese names. The customer's province comes from the Region / State zone of the address, matched by its name. The zone "Hong Kong" is not a mainland province and gets the table price. 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 method is hidden. The customer never sees an error. The error is written to the log.
The extension 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 extension was built against the FengQiao documentation and mocked responses, so confirm the prices with your SF Express account (sandbox first) before going live.
On OpenCart 4 the customer clicks Choose in the shipping method block of the checkout page and picks SF Express in the window Shipping method options, where the method title is shown with the price. The method works the same way as on OpenCart 3.
License key
The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox SF Express is the first block on Extensions > Extensions > Shipping > VibeFox SF 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-sf-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, the SF Express shipping method is not shown to customers at checkout and no price 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
SF Express does not appear at checkout: check that the license is active and Enable SF Express is on. Check Geo zone, 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. Check that the products have Requires Shipping set to Yes.
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 stores) the currency conversion rate. Read the warnings at the top of the extension 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 log shows a signature error: the checkword is wrong or belongs to the other environment. Check the Sandbox setting. If SF Express says the API is not allowed, add the price query API to your FengQiao application.
Addresses in Tibet get the table price: click Add Chinese provinces in the API section of the extension page.
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 extension page. This clears the cached SF Express prices.
The page says "Warning: You do not have permission to modify VibeFox SF Express!": your admin user group may only view the settings. Give the group the modify permission for extension/shipping/vfd_sf_express (OpenCart 3) or extension/vfd_sf_express/shipping/vfd_sf_express (OpenCart 4) in System > Users > User Groups.
For developers: the OpenCart events vfd_sf_express/quote_request and vfd_sf_express/api_url let another extension change the price request (for example to another product code) and the gateway URL.
Uninstall
Go to Extensions > Extensions, choose the type Shipping and click Uninstall (the red − button) next to VibeFox SF Express. The license key and license status of this extension are always removed. OpenCart always resets Enable SF Express, Sort order, Tax class and Geo zone. The cached prices are always removed. If Remove data on uninstall is on, the other settings and the log are deleted as well. If it is off, they are kept and are used again when you install the extension again. Chinese zones added with Add Chinese provinces stay. Existing orders keep their shipping method and cost.
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 SF Express in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.
SF Express is a trademark of its respective owner. This extension is not affiliated with or endorsed by SF Express.