VibeFox Shippo for WooCommerce — 帮助
系统要求
WordPress：5.8 或更高版本。
WooCommerce：7.0 或更高版本，已安装并启用。未安装 WooCommerce 时插件无法启用。
PHP：8.0 或更高版本。
Shippo 账户：创建 Shippo 账户，连接或启用承运商（USPS、UPS、FedEx、DHL 等），并从 Shippo > Settings > Advanced > API 复制 API 令牌。Shippo 对购买的面单收费，而不是对运费请求收费。新的 Shippo 账户可能需要先经 Shippo 验证，才能返回实时运费。没有令牌时，仅使用备用价格。
商品：商品应设置重量和尺寸。没有尺寸的商品使用默认箱子尺寸。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 vfd_shippo 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Shipping > VibeFox Shippo，或在插件页面中点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 粘贴您的 Shippo API 令牌，并填写 Ship from 地址。邮政编码为必填项。
6. 选择 Shippo rate currency（若从美国发货则选 USD）；如果您的商店使用其他货币，请输入汇率。
7. 可选：在按国家和重量设置的表格中输入备用价格。
8. 在 WooCommerce > Settings > Shipping > Shipping zones 中将 VibeFox Shippo 添加到某个配送区域，或开启 Ignore shipping zones 并选择国家。
配置
所有设置都在同一页面：WooCommerce > Settings > Shipping > VibeFox Shippo。它们适用于所有配送区域。将该方式添加到某个区域时，区域窗口只有一个字段：
Title (zone)：顾客在该区域看到的名称。留空则使用全局的 Name。
每次保存设置时，缓存的 Shippo 运费都会被清除。设置上方的警告会告诉您该方式何时永远无法显示，或何时无法使用实时运费：没有 API 令牌、没有发货地邮政编码或国家，或缺少汇率。设置了测试令牌时，会有提示提醒您。
常规
Enable/Disable：一次性在所有区域启用或停用该方式。
Name：结账时显示的配送方式名称。某个区域可以用自己的 Title 覆盖它。默认：Shippo Shipping。
Shippo 账户
API token：您的 Shippo API 令牌。正式店铺获取真实运费请使用正式令牌（shippo_live_...），Shippo 测试运费请使用测试令牌（shippo_test_...）。
Allowed carriers / services：可选，用逗号分隔。按 Shippo 的名称填写承运商（USPS、UPS、FedEx、DHL Express），或填写 Shippo 服务等级令牌（usps_priority、ups_ground）。将显示允许范围内最便宜的运费。留空则显示任何承运商的最低运费。
Ship from（包裹的发货地址；若与商店地址在同一国家，空白字段会取自 WooCommerce > Settings > General 中的商店地址）
Sender name / company：发件人姓名。它也用于签署海关申报单。
Street address：发件人街道地址。
City：发件人城市。
State / province：两位字母的州或省代码，例如 CA 或 NY。部分承运商需要此项。
Postal / ZIP code：获取实时运费时必填。
Country：您的发货国家。默认：United States。
运费
Parcels：购物车如何发送给 Shippo。
Default box size：商店尺寸单位下的长 x 宽 x 高，例如 30 x 20 x 10。Shippo 需要箱子尺寸。当购物车中的商品没有尺寸时使用此值。留空则使用 30 x 20 x 10 厘米。
Shippo rate currency：Shippo 为您的承运商报价所用的货币，即发货国家的货币：USD（美国）、CAD（加拿大）、GBP（英国）、EUR（欧元区）或 AUD（澳大利亚）。默认：USD。Shippo 以商店货币返回的运费始终按原样使用。
Exchange rate：1 个 Shippo rate currency 单位相当于商店货币的价格，例如 0.92。两种货币相同时无需填写。如未填写，则不使用其他货币的运费，并适用备用价格。插件不会自动换算货币。
Tax status：Taxable 表示 WooCommerce 会根据您的税务规则对运费征税，None 则不征税。Shippo 运费不含销售税。
备用价格（在没有实时运费时使用：没有 API 令牌、无法连接 Shippo、令牌被拒绝，或该地址没有承运商运费；价格以商店货币计；若两项都留空，则在这种情况下隐藏该方式）
Country prices：按国家和购物车重量设置的价格表。点击 + Add country 添加一行，点击叉号删除一行。各列为 Price，以及重量档位 XS（最多 1 千克）、S（最多 2 千克）、M（最多 3 千克）、L（最多 5 千克）和 XL（超过 5 千克）。空白或为 0 的档位使用 Price 列。* Default 行适用于没有自己一行的国家。新增的行默认为 * Default。保存时所有单元格都为空的行会收取 0 元，因此请删除您不打算填写的行。
Other countries：上表中未列出的国家的价格（当不存在 * Default 行时）。留空则对这些国家隐藏该方式。
条件
Free shipping from：购物车小计达到此金额时免运费。届时不会向 Shippo 发出请求。留空则关闭此功能。
Minimum subtotal：仅当购物车小计至少为此金额时才显示该方式。留空则始终显示。
Minimum weight (kg)：显示该方式所需的最低购物车重量。0 表示不设限制。
Maximum weight (kg)：购物车重量超过此值时隐藏该方式。默认：30。0 表示不设限制。
Disabled shipping classes：如果购物车中包含属于这些 WooCommerce 配送类别的商品，则隐藏该方式。
不使用配送区域时的可用性
Ignore shipping zones：无论该方式是否添加到某个区域，都为下列国家提供该方式。
Countries：该模式下的目标国家。留空则使用商店可配送的所有国家。此字段仅在开启 Ignore shipping zones 时使用。添加到配送区域的方式始终适用于该区域的国家。
高级
Debug log：将 Shippo 请求记录到 WooCommerce > Status > Logs，来源为 vfd-shippo。即使此选项关闭，API 错误也始终会被记录。API 令牌和顾客地址绝不会被记录。
Remove data on uninstall：开启后，删除插件会移除其设置以及配送区域中的该方式。停用插件从不会删除设置。
结账时的工作方式
当顾客输入收货地址时，WooCommerce 会向插件请求运费。插件首先检查条件：购物车重量、最低小计和禁用的配送类别。如果适用免运费，则以 0 元价格显示该方式，并且不会向 Shippo 发出请求。
随后，插件将发货地址、顾客地址和包裹发送给 Shippo。对于 WooCommerce 要求填写邮政编码的国家，请求会等待顾客填写后才发出。对于国际运输，会附加包含商品名称、数量、重量和价值的海关申报单。Shippo 返回您承运商的运费，插件则在方式名称下显示允许范围内最便宜的运费（以商店货币计）。
在按订单模式下，商品装入一个箱子：取最大商品的最长边和中间边，再加上所有单位的最短边之和。如果任何商品没有尺寸，则整个包裹使用默认箱子尺寸。在按商品模式下，每件商品作为单独的包裹计算运费，并将运费乘以其数量。
每个响应会按地址和包裹缓存 1 小时。当 Shippo 的响应中没有可用运费时，该地址会被记住 10 分钟。在超时、令牌被拒绝、服务器错误或请求频率限制之后，插件会暂停请求 5 分钟，并使用备用价格。请求超时时间为 10 秒。
如果没有实时运费，价格将取自备用价格表，然后是 Other countries。如果两者都不适用，则隐藏该方式。顾客不会看到任何错误。
该方式可用于经典结账页面以及购物车和结账区块。它兼容 WooCommerce 高性能订单存储（HPOS）。
插件仅计算运费。它不购买面单，不跟踪包裹，不验证地址，也不提供取货或寄存点、保险、签收选项或退货面单。只显示允许范围内最便宜的运费，而不是所有服务的列表。除上述装箱方式外，不提供其他装箱功能，也不提供运费加价或手续费。
订单
订单的配送行会保存所选的 Carrier / service；如果是按订单一个包裹，还会保存 Estimated delivery days。您可以在后台订单页面看到这些信息，并可以在 Shippo 中购买对应的面单。
许可证密钥
本插件需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Shipping > VibeFox Shippo 页面顶部。将密钥粘贴到 License key 中并点击 Activate。该区块会显示状态（例如许可证有效期截止日期）和您的域名。使用 Check now 可重新检查状态，Change key 用于输入其他密钥，Remove key 用于将其从本站点移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥不会释放其域名名额，请在您的 vibefox.net 账户中释放名额。
没有有效密钥时，Shippo 不会在结账时向顾客显示。已登录的店铺管理员仍能看到它，并标注 (unlicensed — visible to admins only)，以便您在购买密钥之前设置和测试插件。插件页面和 WooCommerce 页面上会出现提醒。现有订单不受影响。
许可证到期后，插件仍可继续工作，但更新和支持需要续费。状态会在后台自动重新检查。
故障排除
Shippo 未在结账时显示：请检查许可证是否有效、Enable/Disable 是否已开启，以及该方式是否已添加到顾客所在国家的区域（或已开启 Ignore shipping zones 且该国家被允许）。检查重量限制、Minimum subtotal 和 Disabled shipping classes。如果没有实时运费，请检查该国家、* Default 或 Other countries 是否设有价格。
实时运费未显示：开启 Debug log，重新加载结账页面，然后打开 WooCommerce > Status > Logs，来源 vfd-shippo。常见原因：没有 API 令牌或发货地邮政编码；店铺货币与 Shippo rate currency 不同且未设置汇率；顾客尚未输入邮政编码；您 Shippo 账户中的承运商都不服务该地址；或 Shippo 账户尚未验证。
在正式店铺测试运费：测试令牌（shippo_test_...）返回的是 Shippo 测试运费。请使用正式令牌（shippo_live_...）。
意外国家免运费：请检查价格表中是否有空行，尤其是空的 * Default 行。所有单元格为空的行会收取 0 元。
修改后运费看起来过时：保存设置页面，这会清除缓存的 Shippo 运费。
面向开发者：过滤器 vfd_shpo_shipment_request、vfd_shpo_customs_declaration、vfd_shpo_selected_rate 和 vfd_shpo_api_url 用于修改请求正文、海关申报单、所选运费以及 API 网址。
许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在其他域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活密钥。如果无法连接许可证服务器，插件将继续按最后已知的状态运行。
卸载
停用插件会保留所有数据。如需移除，请在 Plugins 页面停用并删除插件。本插件的许可证密钥、许可证状态和缓存的运费始终会被删除。只有开启了 Remove data on uninstall 时，设置和区域配送方式才会被删除；否则会保留，以便日后重新安装时使用。现有订单保留其配送行。
Shippo 是其各自所有者的商标。本插件与 Shippo 无关联，也未获得 Shippo 的认可。