VibeFox SF Express for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝在更早的 PHP 版本上安装。
SF Express 账户（仅用于实时运费）：实时运费使用 SF Express FengQiao 开放平台（open.sf-express.com）。您需要一个 SF Express 月结账户以及 FengQiao 开发者账户。请在该平台注册，创建应用，向应用添加 API "Delivery time standard and price query"（EXP_RECE_QUERY_DELIVERTM），并复制客户编码和校验码。沙箱与生产环境的校验码不同。如果您只使用价格表，则不需要 SF Express 账户。
中国省份（仅用于实时运费）：实时运费需要收货地址的省份。PrestaShop 默认没有中国省份。模块可以为您添加（请参见下方的 Chinese provinces）。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥对应一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或之后在模块列表中找到 VibeFox SF Express，点击 Configure。
3. 在 Configure 页面顶部的许可证区块中的 License key 处输入您的 VibeFox 许可证密钥，然后点击 Activate（见许可证密钥）。
4. 填写价格表和/或备用运费，点击 Save。
5. 若要在中国大陆使用实时运费，请输入客户编码和校验码、发件省份和城市（或设置中国的店铺地址），如果您的店铺货币不是人民币（CNY），还需填写货币转换汇率。如页面提示，请点击 Add Chinese provinces。请先使用 Sandbox 和沙箱凭据进行测试。
安装时，模块会创建 SF Express 承运商，配送时间文本为 Courier delivery。该承运商分配给所有配送区域和所有顾客群组。您可以在 Shipping > Carriers 中更改配送区域、顾客群组、配送时间、Logo 和尺寸限制。请不要在那里设置价格：价格始终来自模块。
配置
所有设置都在模块页面：Modules > Module Manager > VibeFox SF Express > Configure。它们适用于承运商的所有配送区域。每个部分都有各自的 Save 按钮，点击后会保存整个页面。每次保存也会清除缓存的 SF Express 运费。
保存时，模块会检查数字。非数字值、负数金额或重量、汇率为 0、Min weight 大于 Max weight，或价格表中的错误价格都会被拒绝并给出提示，在您更正之前不会保存任何内容。设置上方的警告会告知您：实时运费只配置了一部分（会列出缺失的设置）、缺少货币转换汇率、中国地址没有省份字段，或模块无法识别店铺的重量或尺寸单位。单位在 International > Localization 中设置（Local units）。
常规
Enable SF Express：开启或关闭该承运商。这与 Shipping > Carriers 中承运商的状态是同一个开关。
Method title：在购物车和结账时显示的承运商名称。默认：SF Express。必填，最多 64 个字符。
Tax：承运商的税规则，或 No tax。选择税规则后，店铺的运费税会加在运费上。如果 SF Express 的运费已包含您想收取的全部费用，请选择 No tax。
SF Express FengQiao API（实时运费）（可选，用于中国大陆的收货地址）
Customer code (partnerID)：您的 FengQiao 应用的客户编码（顾客编码）。清空它也会清除已保存的校验码，因此您可以删除凭据。
Checkword：同一环境的校验码（校验码）。仅用于对请求签名，从不发送或记录。保存后，该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。
Sandbox：使用 FengQiao 沙箱（sfapi-sbox.sf-express.com）配合沙箱凭据进行测试。沙箱运费不是真实的。在正式店铺中请关闭。默认：关闭。
SF Express product：显示哪个 SF Express 产品的运费。
Sender province：包裹的发出省份。如果店铺位于中国，留空即可使用 Shop Parameters > Contact > Stores 中店铺地址的省份。
Sender city：标准的中文城市名称，例如 深圳市。如果店铺位于中国，留空即可使用店铺所在城市。
Currency conversion rate：SF Express 运费以人民币（CNY，元）计算。如果您的店铺默认货币不是人民币，请输入一个人民币等于多少您的货币单位（1 CNY = ? 单位）。未设置时不使用实时运费。如果您的店铺货币是人民币，则直接使用运费。小数点和逗号都可作为小数分隔符。
Chinese provinces：显示中国地址是否可以有省份。如果没有，请点击 Add Chinese provinces。该按钮会将 32 个省、自治区和直辖市添加为中国的州/省（states）（ISO 代码如 GD 和 BJ，名称如 "Guangdong / 广东"），为中国启用 "Contains states"，并在中文地址表单中添加省份字段。已存在的省份不会重复添加。不点击此按钮则不会更改任何内容。
价格表与备用运费（用于香港、澳门、台湾及其他国家，适用于未配置实时运费或 SF Express 未返回运费的情况；价格以店铺默认货币计算，不含税）
Country prices：按国家设置基础运费的表格。点击 Add country 添加一行，点击垃圾桶图标删除一行。* All other countries 行适用于没有自己一行的所有国家。高于 0 的重量段价格会替代该段包裹的基础运费：XS ≤1 kg、S ≤2 kg、M ≤3 kg、L ≤5 kg 和 XL >5 kg。基础运费为 0 表示免运费。基础运费为空表示该国家没有运费，将使用备用运费。"9.99" 和 "9,99" 均可接受。没有任何价格的行不会被保存。
Fallback cost：当 SF Express 和价格表都无法给出运费时使用。留空则在这种情况下隐藏该承运商。
Table / fallback price is：价格表和备用运费的计费方式。
SF Express 实时运费始终按整个订单计算。
条件
Free shipping from：购物车小计（折扣后、税前）达到该金额即免运费。留空则从不提供免运费。免运费会在查询任何运费之前检查，因此达到该金额后，对于该承运商可配送的每个目的地都免费提供，即使是没有价格表行或 Fallback cost 的国家。
Minimum subtotal：只有当购物车小计（折扣后、税前）达到该金额时才显示该承运商。留空则始终显示。
Min weight：购物车的最低重量（kg）。商品重量从您的店铺重量单位换算。0 表示不限。
Max weight：购物车的最高重量（kg）。默认：50。0 或留空表示不限。
无配送区域的可用性
Ignore shipping zones：无论哪个配送区域匹配，都为下方指定的国家提供 SF Express。保存时，该承运商会被添加到所有配送区域，之后创建的配送区域也会添加。关闭此选项会移除这些已添加的配送区域。关闭时，该承运商只出现在其自身的配送区域中。
Countries：该模式下的目的国家。留空则允许所有启用的国家。此字段仅在 Ignore shipping zones 开启时使用。
高级
Debug log：将运费计算写入模块文件夹中的 logs/vfd_sfex_debug.log.php。该文件无法通过网页打开。即使此选项关闭，API 错误也始终会被记录。不会写入校验码或顾客地址。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Remove data on uninstall：开启时，卸载模块会删除设置、承运商、缓存运费和日志。关闭时，所有内容都会保留，以便重新安装。
结账时的运作方式
在配送步骤，PrestaShop 向模块请求 SF Express 运费。只有实物商品计入：虚拟商品不增加重量，也不计入小计。模块首先检查条件：允许的国家（使用 Ignore shipping zones）、购物车重量和最低小计。如果小计达到 Free shipping from，运费为 0，不会向 SF Express 发送请求。
对于中国大陆的收货地址，且已设置客户编码和校验码时，模块会向 SF Express 发送您的发件省份和城市、顾客所在省份和城市、购物车重量，以及购物车体积（取自三个尺寸都有的商品）。请求使用您的校验码签名。SF Express 以人民币返回运费，模块会将所选运费转换为您店铺的默认货币。运费随后以顾客购物车的货币显示。
SF Express 通过标准的中文名称识别地址。顾客的省份取自地址的州/省字段。城市必须用中文填写，例如 广州市。对于北京、上海、天津和重庆，城市会自动填充。使用拉丁字母填写的城市（如 "Guangzhou"）将使用价格表的运费。
每个运费缓存一小时，因此同一购物车不会触发新的请求。失败的请求缓存 10 分钟，这样结账页面在每次刷新时都不必等待 SF Express。HTTP 超时时间为 10 秒。
如果没有实时运费，则使用价格表中的运费，其次使用 Fallback cost。如果两者都不适用，则隐藏该承运商。顾客永远不会看到错误。错误会写入日志。
如果您在承运商已有订单后，在 Shipping > Carriers 中编辑该承运商，PrestaShop 会将其保存为新的承运商版本。模块会自动跟随新版本。
模块仅计算运费。它不会生成运单或面单，不会在 SF Express 创建订单，不会预约取件，不会取消或跟踪运单。请照常在您的 SF Express 账户中创建和跟踪运单。顾客不能选择顺丰网点或快递柜。SF Express 用作上门配送的快递。实时运费仅适用于中国大陆的收货地址。该模块是根据 FengQiao 文档和模拟响应开发的，因此在正式上线前，请先在 SF Express 账户（先使用沙箱）中核实运费。
许可证密钥
模块需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox SF Express 位于 Modules > Module Manager > VibeFox SF Express > Configure 页面的最上方，位于设置之上。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会显示被遮蔽的密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入另一个密钥）和 Remove key（从此店铺中移除密钥）。其下方有一行 Product: presta-shipping-sf-express 和链接 Manage licenses and domains in your account，点击后会打开您的 vibefox.net 账户。只有拥有该模块 Configure 权限的员工才能更改密钥。该区块的文字跟随后台语言显示（包含英语和俄语）。
如果密钥未被接受，该区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或 License expired on 加某个日期。在店铺地址更改后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，模块会继续使用上次已知的状态运行。
一个密钥对应一个域名：即主店铺的域名，多店铺设置中也是如此。从店铺中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 SF Express 承运商，也不会计算运费。PrestaShop 前台无法知道您已登录后台，因此承运商对您也是隐藏的：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 中的 Alerts 选项卡上会出现提醒。现有订单不受影响。
许可证到期后，模块仍会继续工作，但更新和支持需要续订。在您使用后台时，系统会自动再次检查状态：输入密钥后的前 14 天每天检查一次，之后每周检查一次。无需设置 cron 任务。卸载或重置模块时，总会删除许可证密钥和许可证状态。
故障排除
结账时没有 SF Express：检查许可证是否有效，以及 Enable SF Express 是否已开启。在 Shipping > Carriers 中，检查该承运商是否覆盖顾客所在国家的配送区域以及顾客群组（或开启 Ignore shipping zones 并检查 Countries）。检查重量限制和 Minimum subtotal。检查价格表或 Fallback cost 是否为该国家设置了运费。产品页面中也可能将商品限制为某些承运商。
运费来自价格表，而非 SF Express：实时运费需要客户编码和校验码、发件省份和城市、中国大陆的收货地址（包含省份和中文城市名称），以及（对于非人民币店铺）货币转换汇率。请阅读模块页面顶部的警告，然后开启 Debug log，刷新结账页面，并查看 Log 字段以了解原因。失败的请求会在 10 分钟后重试。
中国地址表单没有省份：在模块页面的 API 部分点击 Add Chinese provinces。
日志中的错误 A1006：签名无效。校验码有误或属于另一环境。请检查 Sandbox 设置。
日志中的错误 A1004：价格查询 API 未添加到您的 FengQiao 应用中。
香港：使用价格表和备用运费。FengQiao 运费查询仅适用于中国大陆地址。
修改后运费看起来过时：在模块页面点击 Save。这会清除缓存的 SF Express 运费。
页面提示未找到 SF Express 承运商：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块以重新创建。
面向开发者：钩子 actionVfdSfExpressQuoteRequest 可修改运费请求，例如更改为其他产品代码。actionVfdSfExpressApiUrl 可更改网关 URL。
卸载
进入 Modules > Module Manager，打开 VibeFox SF Express 旁边的菜单，选择 Uninstall。许可证密钥和许可证状态始终会被删除。缓存的运费始终会被删除。如果 Remove data on uninstall 已开启，承运商会被删除（订单保留历史记录），设置和日志也会被删除。如果关闭，承运商仅被停用，所有设置都会保留。重新安装模块或执行 Reset 会使承运商恢复到之前的状态。现有订单保留其配送行。
SF Express 是其各自所有者的商标。本模块与 SF Express 无关联，也未获得 SF Express 的认可。