VibeFox SF Express for WooCommerce — 帮助
系统要求
WordPress:5.8 或更高版本。
WooCommerce:5.0 或更高版本，已安装并启用。未安装时插件无法启用。
PHP:8.0 或更高版本。
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 账户。
VibeFox 许可证密钥:在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 vfd_sf_express 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Shipping > VibeFox SF Express，或在插件页面点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 填写价格表和/或备用运费。
6. 若要在中国大陆使用实时运费，请输入客户编码和校验码、发件省份和城市（或设置中国境内的商店地址）；如果您的商店货币不是人民币，还需填写汇率。请先使用 Sandbox 和沙箱凭据进行测试。
7. 在 WooCommerce > Settings > Shipping > Shipping zones 中，将 VibeFox SF Express 添加到某个配送区域，或开启 Ignore shipping zones 并选择国家。
配置
所有设置都在同一页面：WooCommerce > Settings > Shipping > VibeFox SF Express。它们适用于所有配送区域。将该方式添加到某个区域时，区域窗口中只有一个字段：
Title (zone):顾客在该区域看到的名称。留空则使用全局的 Method title。
每次保存设置时，已缓存的 SF Express 运费都会被清除。如果实时运费只完成了部分设置，设置页面顶部的提示会列出缺少的设置或缺少的汇率。
常规
Enable/Disable:一次性在所有区域启用或禁用该方式。
Method title:在购物车和结账页面显示的配送方式名称。区域可以覆盖此名称。默认：SF Express。
Tax status:Taxable 会在运费之上加收商店的配送税，None 则不加。如果 SF Express 运费已包含您想收取的全部费用，请选择 None。
SF Express FengQiao API（实时运费）（可选，适用于中国大陆的收货地址）
Customer code (partnerID):您的 FengQiao 应用的客户编码（顾客编码）。
Checkword:同一环境的 checkword（校验码）。仅用于对请求签名，绝不会发送或记录。
Sandbox:使用 FengQiao 沙箱配合沙箱凭据进行测试。沙箱运费并非真实价格。在正式商店中请关闭。默认：off。
SF Express product:显示哪一款 SF Express 产品的运费。
Sender province:包裹寄出的省份。若商店位于中国，留空则使用 WooCommerce > Settings > General 中商店地址的省份。
Sender city:标准中文城市名称，例如 深圳市。若商店位于中国，留空则使用商店所在城市。
Currency conversion rate:SF Express 运费以人民币（CNY，元）计算。如果您的商店货币不是人民币，请填写一个人民币相当于多少商店货币单位。未填写时不使用实时运费。若商店货币为人民币，则直接使用运费。小数点和逗号均可作为小数分隔符。
价格表和备用运费（适用于香港、澳门、台湾及其他国家；在未配置实时运费或 SF Express 未返回运费时使用；价格以您的商店货币计）
Country prices:按国家设置基础运费的表格。* Any other country 行适用于没有单独行的所有国家。某重量段的运费高于 0 时，将替代该段包裹的基础运费：≤ 1 kg、≤ 2 kg、≤ 3 kg、≤ 5 kg 和 > 5 kg。基础运费为 0 表示免运费。基础运费留空表示该国没有价格，将使用备用运费。
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 表示无限制。
Excluded shipping classes:如果购物车包含这些 WooCommerce 配送类别的商品，则隐藏该方式。
不使用配送区域时的可用性
Ignore shipping zones:即使该方式未添加到某个区域，也会为下方所列国家提供。关闭时，该方式仅出现在已添加它的配送区域中。
Countries:该模式下的目的国家。留空则使用您发货的所有国家。仅当 Ignore shipping zones 开启时才使用此字段。
高级
Debug log:将运费计算写入 WooCommerce 日志：WooCommerce > Status > Logs，来源 vfd-sf-express。即使此选项关闭，API 错误也始终会记录。不会写入校验码或顾客地址。
Remove data on uninstall:开启后，删除插件会移除其设置、配送区域中的方式和缓存。停用插件从不删除任何内容。
结账时的工作方式
顾客输入收货地址时，WooCommerce 会向插件请求运费。插件首先检查条件：收货国家、购物车重量、最低小计以及排除的配送类别。若适用免运费，且价格表或 Fallback cost 为目的地提供了价格，则该方式以 0 元显示，并且不会向 SF Express 发送请求。否则，插件会先向 SF Express 请求实时运费，只有当返回运费时才将该方式显示为免费。
对于中国大陆的收货地址，且已设置客户编码和校验码时，插件会向 SF Express 发送发件省市、顾客所在省市、购物车重量，以及购物车体积（取自三个尺寸均已填写的商品）。请求使用您的校验码签名。SF Express 以人民币返回运费，插件会将所选运费换算为您的商店货币。
SF Express 通过标准中文名称识别地址。顾客的省份取自结账页面的州/省字段。城市必须用中文填写，例如 广州市。北京、上海、天津和重庆的城市会自动填写。使用拉丁字母填写的城市（如 "Guangzhou"）将使用价格表运费。
每个运费缓存一小时，因此相同购物车不会触发新请求。失败的请求缓存 10 分钟，使结账页面在每次刷新时不必等待 SF Express。HTTP 超时时间为 10 秒。
如果没有实时运费，运费依次取自价格表，再取自 Fallback cost。两者都不适用时，该方式会被隐藏。顾客永远不会看到错误。错误会写入日志。
该方式适用于经典结账页面，以及购物车和结账区块。它兼容 WooCommerce 高性能订单存储（HPOS）。内置英文与简体中文翻译。
插件仅计算运费。它不会生成运单或面单，不会在 SF Express 创建订单，不会预约取件，也不会取消或跟踪运单。请照常在您的 SF Express 账户中创建和跟踪运单。顾客不能选择顺丰网点或快递柜。SF Express 作为上门快递使用。实时运费仅适用于中国大陆的收货地址。本插件依据 FengQiao 文档和模拟响应开发，因此请在正式上线前，先在沙箱中、再通过您的 SF Express 账户核实运费。
许可证密钥
本插件需要 vibefox.net 提供的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Shipping > VibeFox SF Express 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期至何时以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从本站点移除。链接 Manage licenses and domains in your account 可打开您的 vibefox.net 账户。
一个密钥只适用于一个域名。从某个站点移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，SF Express 不会在结账页面向顾客显示。已登录的商店管理员仍可看到它，并标注 (unlicensed — visible to admins only)，方便您在购买密钥前完成设置与测试。插件页面和 WooCommerce 页面会显示提醒。现有订单不受影响。
许可证过期后，插件仍可继续工作，但更新和支持需要续费。状态会在后台自动重新检查。
故障排除
结账时不显示 SF Express:请检查许可证是否有效、Enable/Disable 是否开启、该方式是否已添加到顾客所在国家的区域（或 Ignore shipping zones 已开启且该国家被允许）。检查重量限制、Minimum subtotal 和 Excluded shipping classes。检查价格表或 Fallback cost 是否为该国家设置了价格。
运费来自价格表，而非 SF Express:实时运费需要客户编码和校验码、发件省市、中国大陆收货地址（含省份和中文城市名称），以及（非人民币商店的）汇率。请打开 WooCommerce > Status > Logs，选择来源 vfd-sf-express，查看原因。失败的请求会在 10 分钟后重试。
日志中的错误 A1006:签名无效。校验码有误，或属于另一环境。请检查 Sandbox 设置。
日志中的错误 A1004:价格查询 API 未添加到您的 FengQiao 应用中。
香港：使用价格表和备用运费即可工作。FengQiao 运费查询仅适用于中国大陆地址。
更改后运费看起来过时：保存设置页面即可。这会清除已缓存的 SF Express 运费。
面向开发者：vfd_sfex_quote_request 过滤器可修改运费请求，例如改用其他产品代码。vfd_sfex_api_url 可修改网关 URL。
许可证区块显示错误：请按区块中的提示操作。例如，若该密钥已在其他域名上使用，请在 vibefox.net 账户中释放一个名额，然后点击 Check now。若站点地址已更改，请点击 Check now，为新域名激活密钥。若无法连接许可证服务器，插件将沿用最后已知状态继续工作。
卸载
停用插件会保留所有数据。若要移除，请先停用，然后在 Plugins 页面删除。该插件的许可证密钥和许可证状态始终会被移除。设置、区域方式和已缓存的运费只有在开启 Remove data on uninstall 时才会移除，否则将保留，以便日后重新安装。现有订单会保留其配送行。
SF Express 是其各自所有者的商标。本插件与 SF Express 无关联，也未获得 SF Express 的认可或背书。