VibeFox USPS for WooCommerce — 帮助
系统要求
WordPress：5.8 或更高版本。
WooCommerce：7.0 或更高版本，已安装并启用。未安装时插件无法启用。
PHP：8.0 或更高版本。
USPS Developer Portal 应用（仅用于实时运费）：使用免费的 USPS 商务账户登录 USPS Developer Portal（developers.usps.com），创建应用并复制其 Consumer Key 和 Consumer Secret。本插件通过 OAuth 2.0 使用 USPS 当前 API。USPS 已于 2026 年 1 月 25 日关闭旧版 Web Tools API（User ID 和 XML），因此 Web Tools User ID 不再有效。不填写密钥时，仅使用固定价格。
Ship-from ZIP code：实时运费需要填写包裹寄出地的 5 位美国邮编。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件 ZIP 文件，然后点击 Install Now。也可以通过 FTP 将 vfd_usps 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Shipping > VibeFox USPS，或在插件页面点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 填写 Consumer Key 和 Consumer Secret、5 位 Ship from ZIP code 并选择服务。如果店铺货币不是美元，请填写 USD exchange rate。
6. 在 WooCommerce > Settings > Shipping > Shipping zones 中将 VibeFox USPS 添加到配送区域，或开启 Ignore shipping zones 并选择国家。
7. 可选：填写固定价格作为备用。
配置
所有设置都在同一页面：WooCommerce > Settings > Shipping > VibeFox USPS。它们适用于所有配送区域。将该方式添加到某个区域时，区域窗口只有一个字段：
Title (zone)：该选项在结账时的名称。留空则使用全局的 Name。
每次保存设置时，缓存的 USPS 令牌和运费都会被清除。您也可以点击 USPS API 部分中的 Clear cached USPS token and rates。设置上方的警告会提示：仅填写了其中一个密钥、未填写任何密钥且没有固定价格、缺少 Ship from ZIP code、未选择任何服务、缺少 USD exchange rate，或已开启测试环境。
常规
Enable/Disable：在所有区域中同时启用或禁用该方式。
Name：结账时显示的配送方式名称。默认：USPS。
Tax status：USPS 价格不含税。Taxable 允许 WooCommerce 在运费上加收配送税，None 则不加收。
USPS API（实时运费）
Consumer Key：您 USPS 开发者应用的 Consumer Key（client_id）。
Consumer Secret：同一应用的 Consumer Secret（client_secret）。
Test environment：使用 USPS Testing Environment for Mailers。仅适用于具有访问权限的应用。获取真实价格时请保持关闭。默认：关闭。
Prices：使用哪种 USPS 价格。
Services：可提供的 USPS 服务。显示 USPS 为该包裹提供的所选服务中最便宜的一项。Flat Rate、Cubic、Hold for Pickup 和 Sunday 价格从不使用。默认：USPS Ground Advantage、Priority Mail 和 First-Class Package International Service。
USD exchange rate：USPS 价格以美元计。如果店铺货币不是美元，请输入 1 美元对应的店铺货币价格，例如 0.92。未填写时不使用实时运费，而是采用固定价格。店铺货币为美元时无需填写。
发货地与包裹（USPS 价格取决于发货邮编、重量和包裹尺寸）
Ship from ZIP code：包裹寄出地的 5 位美国邮编。ZIP+4 会被截取为 5 位。其他值会被拒绝并显示提示。
Box size：可选的箱子尺寸，单位为店铺的尺寸单位，例如 30x20x15。留空则根据商品尺寸计算：最长边、最宽边以及堆叠的高度。如果商品没有尺寸，则使用 10 x 8 x 4 英寸的箱子。
Default product weight (kg)：用于没有重量的商品，参与 USPS 运费、重量限制和重量区间计算。默认：0.5。
固定价格（价格以店铺货币计；未输入任何 API 密钥时使用，USPS 未返回运费时作为备用：API 故障、密钥错误、无可用服务或目的地没有美国邮编；两项都留空则在这种情况下隐藏该方式）
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 行适用于其他所有国家。非数字的值会被清除并显示提示。
Fallback cost：当没有匹配的国家价格时使用的固定价格。留空则在这种情况下隐藏该方式。
Fixed price is：Per order 只收取一次价格。Per item (each item priced by its own weight x quantity) 按每件商品自身重量（无重量则用默认重量）计价，再乘以数量。USPS 实时运费始终按整个包裹报价。
条件
Free shipping from：购物车小计达到此金额即免运费。此时不会向 USPS 发送请求。留空则从不提供免运费。
Minimum subtotal：仅当购物车小计至少达到此金额时显示该方式。留空则始终显示。
Min weight (kg)：该方式出现所需的最低购物车重量。0 表示不限制。
Max weight (kg)：购物车重量超过此值时隐藏该方式。默认：30。USPS 最多接受 70 磅（31.7 kg）。0 表示不限制。
Excluded shipping classes：如果购物车包含任一这些 WooCommerce 配送等级的商品，则隐藏该方式。
不使用配送区域时的可用性
Ignore shipping zones：即使未将该方式添加到配送区域，也对下方所列国家提供该方式。
Countries：该模式下的目的国家。留空则使用店铺的所有配送国家。仅在开启 Ignore shipping zones 时使用此字段。
高级
Debug log：将 API 请求和运费计算记录到 WooCommerce > Status > Logs，来源为 vfd-usps。即使此选项关闭，API 错误也始终会记录。密钥、令牌和顾客地址从不记录。
Remove data on uninstall：开启后，删除插件会移除所有插件设置和区域方式。停用插件永远不会删除设置。
结账时的工作方式
当顾客输入配送地址时，WooCommerce 会向插件请求运费。插件首先检查条件：购物车重量、最低小计和排除的配送等级。如果适用免运费，则以 0 元价格显示该方式，并且不会向 USPS 发送请求。
插件从 USPS 获取 OAuth 令牌，并在其过期前保留。被 USPS 拒绝的令牌会被更新，报价请求随后重试。对于美国及其属地（包括波多黎各、美属维尔京群岛和关岛）的目的地，插件会调用 Domestic Prices API，并需要顾客的 5 位邮编。对于其他国家，插件会使用国家和邮政编码调用 International Prices API。
请求包含发货邮编、以磅计的购物车重量、以英寸计的包裹尺寸以及价格类型。超过 70 磅的包裹使用固定价格。顾客会看到一个选项，即所选服务中最便宜的一项，并已换算为您的店铺货币。
每个报价缓存 1 小时。失败的报价会记住 10 分钟。发生超时、服务器错误、速率限制或密钥被拒绝后，5 分钟内不会调用 USPS。HTTP 超时时间为 10 秒。停用插件会清除缓存的令牌和运费。
如果 USPS 未返回运费，价格将依次取自 Country prices，然后是 Fallback cost。两者都不适用时，该方式会被隐藏。顾客永远看不到 USPS 的错误信息。
该方式可用于经典结账以及购物车和结账区块。它兼容 WooCommerce 高性能订单存储（HPOS）。
插件仅计算运费。不购买邮资或运单，不预约取件，不追踪包裹，也不允许顾客选择邮局或取件点。它只显示一个选项，而不是多个 USPS 服务。不进行箱子装箱：购物车按一个包裹计算。不包括保险和其他额外服务。
订单
对于实时运费，订单的配送项会保存 USPS service，例如 USPS Ground Advantage。店铺管理员可在后台订单页面看到该信息。
许可证密钥
本插件需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Shipping > VibeFox USPS 页面顶部。将密钥粘贴到 License key 中并点击 Activate。该区块会显示状态，例如许可证有效期截止日期以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从此站点移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。
没有有效密钥时，顾客在结账时看不到 USPS。已登录的店铺管理员仍可看到，并标注为 (unlicensed — visible to admins only)，以便您在购买密钥前设置和测试插件。插件页面和 WooCommerce 页面会显示提醒。现有订单不受影响。
许可证过期后，插件仍可继续工作，但更新和支持需要续费。状态会在后台自动重新检查。
故障排除
结账时没有显示 USPS：请检查许可证是否有效、Enable/Disable 是否开启，并确认该方式已添加到顾客所在国家的区域中（或已开启 Ignore shipping zones 且该国家被允许）。检查重量限制、Minimum subtotal 和 Excluded shipping classes。如果没有可用的 USPS 密钥，该方式需要固定价格（Country prices 或 Fallback cost）。
实时运费未显示：请查看设置页面顶部的警告。开启 Debug log 并打开 WooCommerce > Status > Logs，来源为 vfd-usps。错误的密钥、错误的环境和 USPS 错误信息都会记录在那里。国内运费需要顾客的 5 位邮编。
我的店铺不是美元：USPS 只提供美元报价。请填写 USD exchange rate。未填写时，不会使用实时运费，而是显示固定价格。
Web Tools User ID 无效：旧版 Web Tools API 已关闭。请在 USPS Developer Portal 中创建应用，并使用其 Consumer Key 和 Consumer Secret。
更改后运费似乎过时：保存设置时会清除缓存。您也可以点击 Clear cached USPS token and rates。
许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在另一个域名上使用，请在您的 vibefox.net 账户中释放名额，然后点击 Check now。如果站点地址已更改，请点击 Check now 为新域名激活密钥。如果无法连接许可证服务器，插件将继续使用最近一次已知的状态。
卸载
停用插件会保留设置，仅清除缓存的令牌和运费。要删除插件，请先停用，然后在 Plugins 页面将其删除。本插件的许可证密钥和许可证状态，以及缓存的令牌和运费，始终会被删除。只有在 Remove data on uninstall 已开启时，设置和区域方式才会被删除。否则它们将保留，以便日后重新安装。现有订单保留其配送项。
USPS 是其各自所有者的商标。本插件与 USPS 没有关联，也未获得 USPS 的认可。