VibeFox Shippo for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本。

Shippo 账户：创建 Shippo 账户，连接或启用承运商（USPS、UPS、FedEx、DHL 等），并从 Shippo > Settings > Advanced > API 复制 API 令牌。Shippo 对购买的面单收费，而非运费查询。新的 Shippo 账户可能需要先经过 Shippo 验证，才会返回实时运费。没有令牌时，仅使用备用价格。

商品：商品应具有重量和尺寸。没有尺寸的商品使用默认箱子尺寸。

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

安装

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

OpenCart 3

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

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

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

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

5. 粘贴您的 Shippo API 令牌，并填写 Ship from 发货地址。实时运费需要邮政编码。

6. 选择 Shippo rate currency（若从美国发货则选 USD）；如果您店铺的默认货币不同，请输入 Exchange rate。

7. 可选择填写备用价格，开启 Enable Shippo shipping，然后点击 Save。

OpenCart 4

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

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

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

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

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

配置

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

页面顶部的警告会告诉您：该方式永远无法显示，或实时运费无法使用的情况，例如：没有 API 令牌、没有发货邮政编码或国家、缺少汇率，或店铺的重量或长度单位不被本扩展识别（请在 System > Settings 的 Local 选项卡中使用 kg、g、lb 或 oz，以及 cm、mm、m 或 in）。当设置了测试令牌时，会显示提示。保存时，无效的名称、非数字的值、负数或负的价格单元格、Minimum weight (kg) 大于 Maximum weight (kg)，或者不是整数的排序值，都会作为错误报告，在您修正之前不会保存任何内容。

常规

Enable Shippo shipping：在结账时提供该方式。这是 Extensions > Extensions > Shipping 中的扩展状态。

Name：结账时显示给顾客的配送方式名称。默认：Shippo Shipping。必填，最多 64 个字符，不得包含 < > ; = # { } 字符。

Tax class：运费的税率类别，或 No tax。Shippo 运费不含销售税。No tax 会按报价原样显示；选择税率类别则会根据您的税务规则为运费加收税费。

Sort order：该方式在结账时配送方式中的位置。整数。

Shippo 账户

API token：您的 Shippo API 令牌。在正式店铺中获取实时运费请使用实时令牌（shippo_live_...），测试 Shippo 运费则使用测试令牌（shippo_test_...）。令牌只会发送给 Shippo，并且绝不会写入日志。保存后，该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。

Remove the saved API token：开启并保存，即可删除已保存的令牌。

Allowed carriers / services：可选，用逗号分隔。请按 Shippo 的名称输入承运商（USPS、UPS、FedEx、DHL Express），或输入 Shippo 服务等级令牌（usps_priority、ups_ground）。将显示允许范围内最便宜的运费。留空则显示任何承运商中最便宜的运费。

Ship from（您包裹的发货地址）

当发货国家与您的店铺所在国家相同时，留空的发件人姓名和省/州会取自 System > Settings 中的店铺名称和地区。OpenCart 没有结构化的店铺街道、城市或邮政编码，因此请在此处填写。

Sender name / company：发件人姓名。该姓名也用于签署海关报关单。如果为空，则使用店铺名称。

Street address：发件人街道地址。

City：发件人城市。

State / province：两位字母的州代码，例如 CA 或 NY。部分承运商需要此项。

Postal / ZIP code：实时运费必填，例如 94105。

Country：您发货的国家。默认：美国。

运费

Parcels：购物车发送给 Shippo 的方式。

Default box size：以您店铺的长度单位（显示在字段名称中）表示的 长 x 宽 x 高，例如 30 x 20 x 10。Shippo 需要箱子尺寸。当购物车中的商品没有尺寸时使用此尺寸。留空则使用 30 x 20 x 10 cm。无法读取的值会在保存后以提示忽略，其他设置仍会保存。

Shippo rate currency：Shippo 为您的承运商报价所用的货币，即发货国家的货币：USD（美国）、CAD（加拿大）、GBP（英国）、EUR（欧元区）或 AUD（澳大利亚）。默认：USD。Shippo 以您店铺默认货币返回的运费始终按原样使用。

Exchange rate：1 个 Shippo 运费货币单位等于多少店铺默认货币，例如 0.92。若两者相同则无需填写。如果不填写，则不使用其他货币的运费，而是使用备用价格。扩展不会自动换算货币。

备用价格（在没有实时运费时使用：没有 API 令牌、无法连接 Shippo、令牌被拒绝，或该地址没有承运商运费；价格以店铺默认货币计，不含税；若要在这种情况下隐藏该方式，请将两个字段都留空）

Country prices：按国家和购物车重量设置的价格表。点击 Add country 添加一行。各列为 Price，以及重量区间 XS（最高 1 kg）、S（1 至 2 kg）、M（2 至 3 kg）、L（3 至 5 kg）和 XL（超过 5 kg）。空白或为 0 的区间使用 Price 列。* Default 行适用于没有自有行的国家。所有单元格均为空保存的行将收取 0 元，因此请删除您不打算填写的行。

Other countries：上表中未列出的国家（没有 * Default 行时）的价格。留空则对这些国家隐藏该方式。

条件

Free shipping from：需要配送的商品小计（使用优惠券后、税前）达到该金额时免运费。届时不会向 Shippo 发出请求。留空则关闭此功能。

Minimum subtotal：仅当需要配送的商品小计（使用优惠券后、税前）达到此金额时才显示该方式。留空则始终显示。

Minimum weight (kg)：显示该方式所需的最低购物车重量。0 表示无限制（默认）。

Maximum weight (kg)：购物车重量超过此值时隐藏该方式。默认：30。0 表示无限制。空白字段保存为 30。

无配送区域时的可用性

通常由地理区域决定在哪里提供该方式。另外，也可以不考虑地理区域，按国家提供。

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

Ignore shipping zones：无论是否位于地理区域内，都为下方列出的国家提供此方式。

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

高级

Debug log：将 Shippo 请求记录到 storage/logs/vfd_shpo_debug.log.php（在 OpenCart 4 中为 system/storage/logs/vfd_shpo_debug.log.php）。该文件无法通过网页读取。即使此选项关闭，API 错误也始终会记录。API 令牌和顾客地址绝不会写入日志。文件达到 5 MB 时，会被移动到 vfd_shpo_debug.old.log.php，并开始新的日志。

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

Remove data on uninstall：开启时，卸载本扩展会删除 Shippo 设置和日志。关闭时（默认），这些内容会保留，以便重新安装。已缓存的运费始终会被删除。订单保存的承运商和服务属于订单历史，会被保留。

导入 / 导出

Export：点击 Download JSON，将设置保存为 JSON 文件。API 令牌不会被导出。

Import：粘贴之前导出的 JSON，然后点击 Import，即可恢复设置，例如在另一个店铺中使用。这些值会像正常保存一样进行检查。已保存的 API 令牌不会被更改。

结账时的工作方式

当 OpenCart 显示配送方式时，它会向本扩展请求 Shippo 运费。如果设置了 Geo zone（且 Ignore shipping zones 关闭），并且地址不在该区域内，则不提供此方式。只有 Requires Shipping 设为 Yes 的商品才会计入：其他商品不增加重量，也不计入小计。然后，扩展会检查条件：Ignore shipping zones 中的国家、购物车重量和最低小计。礼品卡、积分和店铺余额不计入。如果适用免运费，运费为 0，且不会向 Shippo 发出请求。

随后，扩展会向 Shippo 发送店铺的发货地址、顾客的地址和包裹信息。对于 OpenCart 要求填写邮政编码的国家，请求会等待顾客输入邮政编码。对于国际运输，会附加海关报关信息，其中包括商品名称（含所选选项）、数量、重量和价值。Shippo 返回您承运商的运费，扩展使用允许范围内最便宜的运费。运费以店铺默认货币计算，并按小数位数取整，然后以顾客的货币显示，并附加所选 Tax class 的税费。

在按订单计费的模式下，商品会装入一个箱子：取最大商品的最长边和中间边，再加上所有单位的最短边之和。若任何商品没有尺寸，则整个包裹使用默认箱子尺寸。在按商品计费的模式下，每件商品作为单独的包裹计算运费，并乘以其数量。

每个响应会按地址和包裹缓存 1 小时。若 Shippo 返回的运费不可用，则该地址会被记住 10 分钟。在发生超时、令牌被拒绝、服务器错误或速率限制后，扩展会暂停请求 5 分钟，并改用备用价格。请求超时时间为 10 秒。

若没有实时运费，则价格来自备用价格表，其次来自 Other countries。如果两者都不适用，则隐藏该方式。顾客永远不会看到错误。原因会写入调试日志。

本扩展只计算运费。它不购买面单，不追踪包裹，不验证地址，不提供取件或投递点、保险、签收选项或退货面单。只显示允许范围内最便宜的运费，而不显示所有服务的列表。除上述装箱方式外，没有其他装箱功能，也没有运费加价或手续费。

在 OpenCart 4 中，顾客在结账页面的配送方式区块中点击 Choose，并在 Shipping method options 窗口中选择 Shippo。该方式的工作方式与 OpenCart 3 相同。

订单

当使用实时 Shippo 运费下单时，扩展会保存所选的 Carrier / service；如果是按订单一个包裹，还会保存 Estimated delivery days。在 Sales > Orders 中打开订单：这些信息会显示在订单历史上方的 Shippo 面板中，便于您在 Shippo 中购买对应的面单。数据随订单保存：之后对购物车或设置的更改不会改变这些数据。即使您已关闭该配送方式，该面板仍会显示。使用备用价格或免运费的订单没有 Shippo 面板。

OpenCart 4 会为结账保留一个订单，并在顾客每次重新确认时更新它。已保存的 Shippo 运费会随之更新。如果顾客改用其他配送方式，或现在适用备用价格，已保存的运费将从订单中移除。

许可证密钥

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

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

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

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

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

故障排除

结账时未显示 Shippo：请检查许可证是否有效，以及 Enable Shippo shipping 是否已开启。检查 Geo zone（或在 Ignore shipping zones 开启时检查 Countries）、重量限制和 Minimum subtotal。如果没有实时运费，请检查该国家、* Default 或 Other countries 是否有价格。检查商品的 Requires Shipping 是否设为 Yes。

实时运费不显示：开启 Debug log，重新加载结账页面，并查看扩展页面上的 Log 字段。常见原因：没有 API 令牌或发货邮政编码；店铺默认货币与 Shippo 运费货币不同，且未设置汇率；顾客尚未输入邮政编码；您的 Shippo 账户中没有承运商覆盖该地址；或 Shippo 账户尚未验证。

在正式店铺中出现测试运费：测试令牌（shippo_test_...）返回的是 Shippo 测试运费。请使用实时令牌（shippo_live_...）。

意外国家免运费：请检查价格表中是否有空行，尤其是空的 * Default 行。所有单元格为空的行将收取 0 元。

重量或箱子尺寸错误：如果页面警告存在未知的重量或长度单位，请在 System > Settings 的 Local 选项卡中设置 kg、g、lb 或 oz 的重量类别，以及 cm、mm、m 或 in 的长度类别。

更改后运费似乎过时：在扩展页面点击 Save。这会清除已缓存的 Shippo 运费。

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

面向开发者：可以通过设置 vfd_shpo_api_url 替换 Shippo API 地址（用于测试）；该设置在设置页面上没有对应字段。

卸载

进入 Extensions > Extensions，选择类型 Shipping，然后点击 VibeFox Shippo 旁边的 Uninstall（红色 − 按钮）。本扩展的许可证密钥和许可状态始终会被删除。OpenCart 始终会重置 Enable Shippo shipping、Sort order、Tax class 和 Geo zone。已缓存的运费始终会被删除。如果开启了 Remove data on uninstall，Shippo 设置和调试日志也会被删除。如果未开启，其他设置会保留，并在您重新安装本扩展时再次使用。现有订单保留其配送方式、运费以及 Shippo 承运商和服务数据。

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

Shippo 是其各自所有者的商标。本扩展与 Shippo 没有关联，也未获得 Shippo 的认可。