VibeFox SF 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 extension.

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. Magento has the provinces of China in its standard list of regions, and the module reads them from there.

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-sf-express-shipping. Without Composer: unpack the ZIP file into app/code/Vibefox/SfExpressShipping/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_SfExpressShipping and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Delivery Methods and open VibeFox SF 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. Fill in the price table and / or the fallback cost. For live prices in mainland China, enter the customer code and the checkword, the sender province and city (or set a Chinese shipping origin) and, if your base currency is not CNY, the currency conversion rate. Test with Sandbox = Yes and sandbox credentials first. Set Enable to Yes and click Save Config.

The module adds the SF Express shipping method to Magento. Customers see it as SF Express - Courier delivery (method title and method name). It is off after installation (Enable = No).

Configuration

All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox SF Express, in the standard Magento configuration form. Like other Magento settings, most of them can be changed for a website with the Scope switcher at the top of the page; Method title and Method name also for a store view. Remove data on uninstall is read from the Default Config only. Save Config saves the whole page. Saving a change to the SF Express settings also clears the cached SF Express prices. Amounts accept "9.99" and "9,99".

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Method title or Method name, longer than 64 bytes or with one of the characters < > ; = # { }; a Sort order that is not a whole number; an amount or weight that is not a non-negative number; a currency conversion rate of 0; a Minimum weight (kg) greater than the Maximum weight (kg); a price in the price table that is not a non-negative number.

While Enable is Yes, warnings after saving tell you when live prices are partly set up (the missing settings are listed), when the currency conversion rate is missing for a base currency other than CNY, when the customer code and checkword are saved but Magento has no regions for China, or when the weight unit of your store is not known to the module. The warnings are shown only while the method is enabled, because the Delivery Methods page is shared by all shipping methods.

General

Enable: shows or hides SF Express at checkout. Default: No.

Method title: the carrier name shown in the cart and at checkout. Default: SF Express. Required, at most 64 bytes (fewer characters for Chinese text).

Method name: shown after the method title, as "Method title - Method name". Default: Courier delivery. Required, at most 64 bytes.

Sort order: the position among the shipping methods at checkout. A whole number, negative numbers are allowed.

SF Express FengQiao API (optional, for live prices to 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 in one step.

Checkword: the checkword (校验码) of the same environment. It is used only to sign requests and is never sent or written to the log. Magento stores it encrypted and shows only a mask after saving. Leave the mask as it is to keep the saved checkword, type a new value to change it. To delete it, clear the field and click Save Config.

Sandbox: Yes uses the FengQiao sandbox (sfapi-sbox.sf-express.com) for testing with sandbox credentials. Sandbox prices are not real. Set it to No in a live store. Default: No.

SF Express product: which SF Express product price is shown.

Sender province: the province the parcels are sent from. Use native shipping origin (the default) takes the region of the shipping origin in Stores > Configuration > Sales > Shipping Settings > Origin, when its country is China.

Sender city: the standard Chinese city name, for example 深圳市. Leave it empty to use the city of the shipping origin, when its country is China.

Currency conversion rate: SF Express prices are in CNY (yuan). If the base currency of your store is not CNY, enter the value of 1 CNY in your base currency, for example 0.14. Without it, live prices are not used and the price table applies. No exchange-rate service is contacted. If your base currency is CNY, prices are used as they are.

Native Chinese provinces: shows how many provinces of China from the standard Magento list of regions the module recognises. The module does not add or change regions and does not change the address forms.

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 the base currency of your store, tax excluded)

Price per country and weight: a table with a base price per country. Click Add country to add a row and Delete 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 up to 1 kg, S up to 2 kg, M up to 3 kg, L up to 5 kg and XL over 5 kg. An empty or zero tier uses Base. A base price of 0 means free shipping. An empty base price means no price for this country, and the fallback cost is used. A row without any price is not saved. If a country has two rows, the last one is kept.

Fallback cost: used when neither SF Express nor the table gives a price. Leave it empty to hide the method in that case.

Table or fallback price is: how table and fallback prices are charged.

Live SF Express prices are always for the whole order.

Conditions

Minimum weight (kg): the minimum cart weight to show the method. Empty or 0 means no limit.

Maximum weight (kg): hide the method if the cart is heavier. Default: 50. Empty or 0 means no limit.

Minimum subtotal: show the method only when the cart subtotal (products that need shipping, after discounts, before tax, in the base currency) reaches this amount. Leave it empty to always show it.

Free shipping from: the cart subtotal 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.

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 the cart volume is not sent to SF Express.

Availability

Ship to Applicable Countries: All Allowed Countries offers SF Express for every country your store allows, Specific Countries only for the countries below.

Ship to Specific Countries: the destination countries for Specific Countries. Live prices are requested for China only; other countries use the price table and the fallback cost.

Shipping tax is not a setting of the module. If your store charges tax on shipping (Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping), Magento adds it on top of the SF Express price.

Advanced

Debug log: writes price calculations to var/log/vfd_sfex_debug.log.php in the Magento folder. The file cannot be opened from the web. API errors are always logged, even when this is No. The checkword and the customer's city are never written.

Remove data on uninstall: when Yes, uninstalling the module with its data deletes the SF Express settings and the log (see Uninstall). The license key and the cached prices are always removed. Orders are never changed.

Debug log viewer: shows the size and the latest entries of the log. Click Clear log to empty it.

How it works at checkout

At the shipping step Magento asks the module for the SF Express price. Only products that need shipping count: virtual and downloadable products add no weight and are not included in the subtotal. The module first checks the countries, the cart weight and Minimum subtotal. If the subtotal reaches Free shipping from, the price is 0 and no request goes to SF Express. A Magento cart price rule with free shipping also makes the price 0.

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 and the cart weight. The request is signed with your checkword. SF Express returns prices in CNY, and the module converts the chosen one to your base currency. Magento then shows it in the customer's currency and adds tax on shipping if your store charges it.

SF Express recognises addresses by standard Chinese names. The customer's province comes from the State/Province 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. Expired cache entries are removed by the Magento cron.

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 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 row of the VibeFox SF 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-sf-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 SF Express method is not shown to customers at checkout and no price is calculated. The Magento storefront does not know that you are logged in to the Admin, so the method 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 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.

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

SF Express does not appear at checkout: check that the license is active and Enable is Yes for the website of the store. Check Ship to Applicable Countries and Ship to Specific Countries, the weight limits and Minimum subtotal. Check that the table or Fallback cost has a price for the country.

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 (if your base currency is not CNY) the currency conversion rate. Read the warnings after Save Config, then set Debug log to Yes, reload the checkout and look at the Debug log viewer to see the reason. A failed request is retried after 10 minutes.

The warning says that Chinese regions are missing: your Magento has no regions for China, so the customer types the province as text. Live prices work when the text is a recognised province name, for example Guangdong or 广东省.

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: prices are cached for up to an hour. Saving a change to the SF Express settings with Save Config clears the cached prices.

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.

For developers: the Magento events vfd_sfex_quote_request and vfd_sfex_api_url let an observer change the price request (for example to another product code) and the gateway URL (in the transport object). An error in such an observer does not break the checkout.

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_SfExpressShipping. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_SfExpressShipping to remove the data, then bin/magento module:disable Vibefox_SfExpressShipping, delete the folder app/code/Vibefox/SfExpressShipping and run bin/magento setup:upgrade.

The license key, the license status and the cached prices are always removed. If Remove data on uninstall is Yes, the SF Express settings and the log are removed too. If it is No, the settings and the log are kept for a re-install. Existing orders keep their shipping method and shipping amount.

SF Express is a trademark of its respective owner. This module is not affiliated with or endorsed by SF Express.