VibeFox SF Express for OpenCart — 帮助

系统要求

OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。

PHP：8.0 或更高版本。

顺丰账户（仅用于实时运费）：实时运费使用顺丰丰桥开放平台（open.sf-express.com）。您需要顺丰月结账户和丰桥开发者账户。在丰桥注册，创建应用，为该应用添加 API “Delivery time standard and price query”（EXP_RECE_QUERY_DELIVERTM），然后复制客户编码和校验码。沙盒环境和生产环境的校验码不同。如果您只使用价格表，则不需要顺丰账户。

中国省份（仅用于实时运费）：实时运费需要收货地址所在的省份，即该地址的 OpenCart 区域（Region / State）。OpenCart 已有中国的区域，但缺少西藏。本扩展可以为您添加（见下方的 Chinese provinces）。

VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。

安装

下载文件是一个 zip 压缩包，内含适用于两个 OpenCart 版本的安装包。请解压到您的电脑上。其中包括 README.txt、OpenCart 3 安装包 vfd_sf_express-oc3-(version).ocmod.zip，以及 OpenCart 4 安装包 vfd_sf_express.ocmod.zip。请只安装与您的 OpenCart 版本对应的安装包。两个版本使用同一个许可证密钥。

OpenCart 3

1. 在后台进入 Extensions > Installer，点击 Upload，选择文件 vfd_sf_express-oc3-(version).ocmod.zip。本扩展不添加 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用 Installer，而是将安装包中 upload 文件夹的内容复制到店铺的根目录。

2. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox SF Express，点击 Install（绿色 + 按钮）。

3. 点击 Edit（铅笔按钮）打开设置页面。

4. 在 Edit 页面顶部的许可证区块中，将 VibeFox 许可证密钥输入 License key 字段，然后点击 Activate（见许可证密钥）。

5. 填写价格表和/或备用运费。

6. 如需在中国大陆使用实时运费，请输入客户编码和校验码、发货省份和城市；如果您店铺的货币不是人民币（CNY），还需输入货币转换汇率。如页面提示，请点击 Add Chinese provinces。请先使用 Sandbox 和沙盒凭据进行测试。

7. 开启 Enable SF Express，然后点击 Save。

OpenCart 4

1. 在后台进入 Extensions > Installer，点击 Upload，选择文件 vfd_sf_express.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包无法使用。

2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。

3. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox SF Express，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。

4. 请按 OpenCart 3 的第 4 至第 7 步输入许可证密钥和设置。两个版本的设置页面及其字段相同。

安装后，在您开启 Enable SF Express 并保存之前，该配送方式处于关闭状态。如果卸载后重新安装本扩展，之前保留的顺丰设置会再次生效。

配置

所有设置都位于扩展页面：Extensions > Extensions > Shipping > VibeFox SF Express > Edit。各部分列在左侧。这些设置适用于所有地理区域。页面底部的一个 Save 按钮可在不重新加载页面的情况下保存整个页面。每次保存也会清除已缓存的顺丰运费。只有拥有本扩展修改权限的后台用户才能保存设置。

保存时，扩展会检查各项数值。以下情况会被提示并拒绝保存，直到您更正为止：配送方式名称为空、超过 64 个字符或包含 < > ; = # { } 字符；数值不是数字；金额或重量为负数；货币转换汇率为 0；Min weight (kg) 大于 Max weight (kg)；价格表中的价格有误；排序值不是整数。设置上方的警告会告诉您：实时运费的设置不完整（会列出缺少的项目）、缺少货币转换汇率、店铺没有中国区域，或者店铺没有以千克为单位的重量类别或以厘米为单位的长度类别，并且其默认单位不被本扩展识别。

常规

Enable SF Express：在结账页面显示或隐藏顺丰。默认：关闭。

Method title：购物车和结账页面上显示的配送方式名称。默认：SF Express。必填，最多 64 个字符。

Tax class：运费的税率类别，或 No tax。选择税率类别后，将在运费之上加收您店铺的运费税。如果顺丰运费已包含您想收取的全部费用，请选择 No tax。

Sort order：顺丰在结账页面各配送方式中的排列位置。整数。

顺丰丰桥 API（实时运费）（可选，适用于中国大陆的收货地址）

Customer code (partnerID)：您丰桥应用的客户编码（顾客编码）。清空该项也会清除已保存的校验码，因此您可以删除凭据。

Checkword：同一环境的校验码（校验码）。仅用于对请求签名，绝不会发送或记录。保存后，该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。

Sandbox：使用丰桥沙盒（sfapi-sbox.sf-express.com）配合沙盒凭据进行测试。沙盒运费不是真实价格。在正式运营的店铺中请关闭。默认：关闭。

SF Express product：显示哪一款顺丰产品的运费。

Cheapest product offered by SF Express：默认选项。使用顺丰返回的最低价格。

SF Express Priority (顺丰特快, code 1)：仅使用该产品的价格。

SF Standard Express (顺丰标快, code 2)：仅使用该产品的价格。

Sender province：包裹的发货省份，例如 Guangdong / 广东。当店铺位于中国时，第一个选项会使用您店铺的地区（System > Settings > Store > Local）。然后显示 Same as the store region 及省份名称；否则显示 — Select —。

Sender city：标准的中文城市名称，例如深圳市。实时运费必填：OpenCart 中的店铺地址为自由文本，因此不会从中获取城市。

Currency conversion rate：顺丰运费以人民币（元）计价。如果您店铺的默认货币不是人民币，请输入 1 人民币等于多少单位您的货币（1 CNY = ? 单位），例如 0.13。未设置时，不使用实时运费。如果您店铺的货币是人民币，该字段会提示无需设置，并直接使用运费。小数点和逗号均可作为小数分隔符。

Chinese provinces：显示顺丰 32 个省、自治区和直辖市中，有多少在 OpenCart 中已是中国区域，以及缺少哪些。位于缺少省份的地址将使用价格表中的运费。点击 Add Chinese provinces，仅将缺少的省份添加为中国区域（ISO 代码及名称，例如 "Tibet / 西藏"）。现有区域不会被修改。如果不点击此按钮，任何内容都不会改变。以此方式添加的区域在卸载后仍会保留在店铺中。

价格表与备用运费（用于香港、澳门、台湾及其他国家；在未配置实时运费、或顺丰未返回运费时使用；价格以店铺默认货币计，不含税）

Country prices：按国家设置基础运费的表格。点击 Add country 添加一行，点击删除按钮可删除一行。* All other countries 行适用于没有自有行的所有国家。重量区间的运费大于 0 时，会替代该区间包裹的基础运费：XS 为 1 kg 及以下，S 为 2 kg 及以下，M 为 3 kg 及以下，L 为 5 kg 及以下，XL 为 5 kg 以上。Base 运费为 0 表示免运费。基础运费为空表示该国家没有运费，将使用备用运费。"9.99" 和 "9,99" 均可接受。没有任何价格的行不会被保存。

Fallback cost：在顺丰和价格表都无法提供运费时使用。留空则在这种情况下隐藏该配送方式。

Table / fallback price is：价格表和备用运费的计费方式。

Per order (tier by the total cart weight)：按购物车总重量所对应区间的运费计算，只收取一次。

Per item (every item is priced by its own weight)：每件商品按其自身重量区间计价，再乘以数量。备用运费会乘以商品件数。

顺丰实时运费始终按整个订单计算。

条件

Free shipping from：需要配送的商品小计（使用优惠券后、税前）达到该金额即免运费。留空则不提供免运费。免运费会在查询任何运费之前检查，因此达到该金额后，对于该配送方式可用的每个目的地都免费提供，即使是没有价格表行或没有 Fallback cost 的国家也是如此。

Minimum subtotal：仅当购物车小计达到该金额时才显示此配送方式。留空则始终显示。

Min weight (kg)：显示此配送方式所需的最低购物车重量（千克）。商品重量会按其重量类别换算。0 表示无限制。

Max weight (kg)：购物车重量超过此值时隐藏此配送方式。默认：50。0 或留空表示无限制。

Geo zone：仅向该地理区域内的地址提供顺丰配送。All zones（默认）表示无限制。地理区域在 System > Localisation > Geo Zones 中管理。当 Ignore shipping zones 开启时，不检查此项。

无配送区域时的可用性

Ignore shipping zones：无论地理区域如何，都为下方列出的国家提供顺丰配送。关闭时，由地理区域决定，国家列表不使用。

Countries：该模式下的目的地国家。留空则允许所有已启用的国家。仅当 Ignore shipping zones 开启时才使用此字段。

高级

Debug log：将运费计算过程记录到 storage/logs/vfd_sfex_debug.log.php。该文件无法通过网页读取。即使此选项关闭，API 错误也始终会记录。不会写入校验码或客户地址。文件达到 5 MB 时，会被移动到 vfd_sfex_debug.old.log.php，并开始新的日志。

Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。

Remove data on uninstall：开启时，卸载本扩展会删除设置和日志。关闭时（默认），设置会保留以便重新安装。已缓存的运费始终会被删除。

导入 / 导出

Export：点击 Download JSON，将设置保存为 JSON 文件，不包含校验码。

Import：粘贴之前导出的 JSON，然后点击 Import 恢复设置。这些值会像正常保存一样进行检查。已保存的校验码会保留。

结账时的工作方式

当 OpenCart 显示配送方式时，它会向本扩展请求顺丰运费。如果设置了 Geo zone 且地址在其之外，则不提供顺丰（除非开启了 Ignore shipping zones）。只有 Requires Shipping 设为 Yes 的商品才会计入：其他商品不增加重量，也不计入小计。小计是这些商品在使用优惠券折扣后、税前的价格。礼品卡、积分和店铺余额不计入。随后，扩展会检查条件：允许的国家（适用于 Ignore shipping zones）、购物车重量和最低小计。如果小计达到 Free shipping from，运费为 0，且不会向顺丰发出请求。

对于中国大陆的收货地址（已设置客户编码和校验码），扩展会向顺丰发送您的发货省份和城市、顾客的省份和城市、购物车重量（至少 0.1 kg）以及购物车体积（取自三边尺寸均已填写的商品）。请求使用您的校验码签名。顺丰以人民币返回运费；扩展会将所选运费换算为您店铺的默认货币，并按小数位数取整。随后，运费会以顾客的货币显示，并附加所选 Tax class 的税费。

顺丰通过标准中文名称识别地址。顾客的省份来自地址的 Region / State 区域，按其名称匹配。"Hong Kong" 区域不是中国大陆的省份，将使用价格表中的运费。城市必须以中文填写，例如广州市。对于北京、上海、天津和重庆，城市会自动填写。以拉丁字母填写的城市（如 "Guangzhou"）将使用价格表中的运费。

每个运费结果缓存一小时，因此同一购物车不会触发新的请求。失败的请求缓存十分钟，以免结账页面在每次刷新时都等待顺丰响应。HTTP 超时时间为 10 秒。

如果没有实时运费，则从价格表获取运费，再从 Fallback cost 获取。如果两者都不适用，则隐藏该配送方式。顾客永远不会看到错误。错误会记录到日志中。

本扩展仅计算运费。它不会生成运单或面单，不会在顺丰系统中创建订单，不会预约取件，也不会取消或跟踪运单。请像平常一样在顺丰账户中创建和跟踪运单。顾客无法选择顺丰服务点或智能柜。顺丰作为上门配送的快递使用。实时运费仅适用于中国大陆的收货地址。本扩展基于丰桥文档和模拟响应开发，因此在正式上线前，请先在顺丰账户（先使用沙盒）中核对运费。

在 OpenCart 4 中，顾客在结账页面的配送方式区块中点击 Choose，然后在 Shipping method options 窗口中选择顺丰，该窗口会显示配送方式名称及运费。该配送方式的工作方式与 OpenCart 3 相同。

许可证密钥

本扩展需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox SF Express 位于 Extensions > Extensions > Shipping > VibeFox SF Express > Edit 页面的最上方，位于设置之上。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、许可状态（例如许可有效期截止日期和您的域名），并提供以下按钮：Check now 重新检查状态，Change key 输入其他密钥，Remove key 从本店移除密钥。其下方是 Product: opencart-shipping-sf-express 一行，以及打开您 vibefox.net 账户的链接 Manage licenses and domains in your account。只有拥有本扩展 Modify 权限的后台用户才能更改密钥。该区块的文字跟随后台语言显示（包括英文和俄文）。

如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached 或 License expired on 加日期。在店铺地址变更后，或在您的账户中释放了域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展将继续按最近一次已知的状态运行。

一个密钥只能用于一个域名：即 OpenCart 配置中的店铺地址。从店铺中移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。

没有有效密钥时，顺丰配送方式不会在结账时显示给顾客，也不会计算运费。以同一浏览器登录后台的管理员用户仍能在店铺中看到该方式，并标有 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试本扩展。在 OpenCart 4 中，此预览不可用：店铺看不到后台的登录状态，因此没有有效密钥时，该方式对所有人都隐藏。打开一次 Edit 页面后，后台的 Dashboard 上会出现提醒。点击 × 关闭，可隐藏 7 天。现有订单不受影响。

许可证到期后，扩展仍会继续运行，但更新和支持需要续费。当您打开后台的 Dashboard 或 Edit 页面时，会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置计划任务（cron）。卸载扩展时，始终会删除许可证密钥和许可状态。

故障排除

结账时未显示顺丰：请检查许可证是否有效，以及 Enable SF Express 是否已开启。检查 Geo zone，或开启 Ignore shipping zones 并检查 Countries。检查重量限制和 Minimum subtotal。检查价格表或 Fallback cost 是否为该国家设置了价格。检查商品的 Requires Shipping 是否设为 Yes。

运费来自价格表，而不是顺丰：实时运费需要客户编码和校验码、发货省份和城市、位于中国大陆且带有省份和中文城市名的收货地址，以及（对于非人民币店铺）货币转换汇率。请阅读扩展页面顶部的警告，然后开启 Debug log，重新加载结账页面，并查看 Log 字段以了解原因。失败的请求将在 10 分钟后重试。

日志显示签名错误：校验码有误，或属于另一个环境。请检查 Sandbox 设置。如果顺丰提示该 API 不被允许，请将价格查询 API 添加到您的丰桥应用中。

西藏的地址使用价格表运费：在扩展页面的 API 部分点击 Add Chinese provinces。

香港：使用价格表和备用运费运作。丰桥运费查询仅适用于中国大陆地址。

修改后运费看起来过时：在扩展页面点击 Save。这会清除已缓存的顺丰运费。

页面提示 "Warning: You do not have permission to modify VibeFox SF Express!"：您的管理员用户组可能只能查看设置。请在 System > Users > User Groups 中为该组授予 extension/shipping/vfd_sf_express（OpenCart 3）或 extension/vfd_sf_express/shipping/vfd_sf_express（OpenCart 4）的修改权限。

面向开发者：OpenCart 事件 vfd_sf_express/quote_request 和 vfd_sf_express/api_url 允许其他扩展修改运费请求（例如改为其他产品代码）以及网关 URL。

卸载

进入 Extensions > Extensions，选择类型 Shipping，然后点击 VibeFox SF Express 旁边的 Uninstall（红色 − 按钮）。本扩展的许可证密钥和许可状态始终会被删除。OpenCart 始终会重置 Enable SF Express、Sort order、Tax class 和 Geo zone。已缓存的运费始终会被删除。如果开启了 Remove data on uninstall，其他设置和日志也会被删除。如果未开启，这些内容会保留，并在您重新安装本扩展时再次使用。通过 Add Chinese provinces 添加的中国区域会保留。现有订单保留其配送方式和运费。

在 OpenCart 4 上，如需同时删除扩展的文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox SF Express 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。

SF Express 是其各自所有者的商标。本扩展与顺丰速运没有关联，也未获得顺丰速运的认可。