VibeFox USPS for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块会拒绝在更早的 PHP 版本上安装。
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. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者之后在模块列表中找到 VibeFox USPS，然后点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入 License key 字段，然后点击 Activate（参见许可证密钥）。
4. 输入 Consumer Key 和 Consumer Secret、5 位的 Ship from ZIP code，并选择服务。如果店铺默认货币不是美元，请输入 USD exchange rate。可选择输入固定价格作为备用。点击 Save。
安装时，模块会创建 USPS 承运商，配送时间文本为 Delivery by USPS。该承运商分配给所有区域和所有客户组。您可以在 Shipping > Carriers 中更改区域、客户组、配送时间、Logo 和尺寸限制。请不要在那里设置价格：价格始终来自模块。
配置
所有设置都在模块页面中：Modules > Module Manager > VibeFox USPS > Configure。它们适用于该承运商的每个区域。每个部分都有自己的 Save 按钮，点击后会保存整个页面。每次保存也会清除缓存的 USPS 令牌和运费。
无效的值不会被保存：保留之前的值，并通过错误信息指出该字段，其他字段仍会保存。页面顶部的警告会告诉您：只填写了其中一个密钥、没有密钥也没有固定价格（此时承运商永远不会显示）、缺少发货邮编、未选择任何服务、缺少美元汇率、测试环境已开启、店铺的重量或尺寸单位未知（请在 International > Localization 的 Local units 中设置），或者 USPS 承运商已被删除。
常规
Enable USPS shipping：开启或关闭承运商。这与 Shipping > Carriers 中的承运商状态使用同一个开关。
Name：结账时显示给顾客的承运商名称。默认：USPS。必填，最多 64 个字符。
Tax status：承运商的税务规则。USPS 价格不含税。选择一个税务规则以添加运费税，或选择 None，表示运费不征税。
USPS API（实时运费）
Consumer Key：您的 USPS 开发者应用的 Consumer Key（client_id）。
Consumer Secret：同一应用的 Consumer Secret（client_secret）。保存后，该字段保持为空，并显示 Saved — leave empty to keep it. 只有需要更改时才输入新值。清空 Consumer Key 也会删除已保存的密钥。
Test environment：使用 USPS Testing Environment for Mailers（apis-tem.usps.com）。仅适用于拥有该环境访问权限的应用。要获取真实价格，请保持关闭（apis.usps.com）。默认：关闭。
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。没有此项时，不使用实时运费，而是应用固定价格。如果默认货币是美元，则无需填写。必须大于 0。
Cache：按钮 Clear cached USPS token and rates 可立即清空缓存。报价缓存 1 小时，失败的报价缓存 10 分钟。发生超时、服务器错误、频率限制或密钥被拒绝后，5 分钟内不会调用 USPS。
发货与包裹（USPS 价格取决于发货邮编、重量和包裹尺寸；购物车按一个包裹报价，超过 70 磅的包裹使用固定价格）
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 (any other country) 这一行适用于其他所有国家。某个国家的行如果没有任何价格，则该国家会使用 Fallback cost。不是数字的值会被清空并给出提示。
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 表示无限制。如果 Min weight 大于 Max weight，将显示错误，并保留之前的限制。
无配送区域时的可用性
Ignore shipping zones：对下方所列国家，在所有区域中提供此承运商。保存时，承运商会关联店铺的所有区域，包括之后创建的区域。关闭后，承运商将恢复其之前的区域。
Countries：此模式下的目的国家。留空则允许店铺可配送的所有国家。此字段仅在 Ignore shipping zones 开启时使用。
高级
Debug log：将 API 请求和运费计算记录到模块文件夹中的 logs/vfd_usps_debug.log.php。该文件无法通过网页访问。即使此选项关闭，API 错误也始终会被记录。密钥、令牌和顾客地址永远不会被记录。
Log：显示日志的大小和最新条目。点击 Clear log 可清空。
Remove data on uninstall：开启时，卸载模块会删除 USPS 设置、承运商、已保存的订单服务、缓存的运费和日志。关闭时，所有内容都会保留，以便重新安装。
结账时的工作流程
在配送步骤，PrestaShop 会向模块请求 USPS 价格。只有实体商品计入：虚拟商品不增加重量，也不计入小计。模块首先检查条件：允许的国家（使用 Ignore shipping zones 时）、购物车重量和最低小计。如果适用免运费，价格为 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 的错误信息。原因会写入日志。
如果您在承运商已有订单之后，在 Shipping > Carriers 中编辑该承运商，PrestaShop 会将其保存为新的承运商版本。模块会自动跟随新版本。
模块仅计算运费。它不购买邮资或运输面单，不预约取件，不追踪包裹，也不允许顾客选择邮局或取件点。它只显示一个选项，而不是多个 USPS 服务。没有装箱功能：购物车按一个包裹报价。保险和其他额外服务不包括在内。
订单
使用 USPS 承运商下单时，模块会保存运费的计算方式。后台订单页面会显示一个 USPS 区块，包含 USPS service（实时运费时，例如 USPS Ground Advantage）以及 Price source：USPS live rate、Fixed price 或 Free shipping。
许可证密钥
本模块需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox USPS 位于 Modules > Module Manager > VibeFox USPS > Configure 页面的最上方，位于设置之上。请将密钥输入 License key，然后点击 Activate。此后，该区块会以掩码形式显示密钥，并显示状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺中移除密钥）。其下方有一行 Product: presta-shipping-usps，以及一个链接 Manage licenses and domains in your account，点击后可打开您的 vibefox.net 账户。只有拥有该模块 Configure 权限的员工才能更改密钥。区块中的文本跟随后台语言（已包含英语和俄语）。
如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或 License expired on 加上日期。店铺地址更改后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，模块将继续使用上一次已知的状态运行。
一个密钥只能用于一个域名：主店铺的域名，多店铺设置中也是如此。从店铺中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效的密钥时，USPS 承运商不会在结账时显示给顾客，也不会计算任何运费。PrestaShop 前台无法得知您已登录后台，因此承运商对您也会被隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试。在 Modules > Module Manager 的 Alerts 标签页中会出现提醒。已有订单不受影响。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。在您使用后台期间，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时没有显示 USPS：请检查许可证是否有效，并确认 Enable USPS shipping 已开启。在 Shipping > Carriers 中，检查承运商是否覆盖顾客所在国家的区域和顾客所属的客户组；或者开启 Ignore shipping zones 并检查 Countries。检查重量限制和 Minimum subtotal。如果没有可用的 USPS 密钥，承运商需要设置固定价格（Country prices 或 Fallback cost）。此外，也可能在商品页面中将商品限定为特定承运商。
实时运费没有显示：请检查模块页面顶部的警告。开启 Debug log，重新加载结账页面，然后查看 Log 字段。错误的密钥、错误的环境以及 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。
页面提示找不到 USPS 承运商：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块，以重新创建它。
卸载
进入 Modules > Module Manager，打开 VibeFox USPS 旁边的菜单，然后选择 Uninstall。许可证密钥和许可证状态始终会被删除。缓存的令牌和运费也始终会被删除。如果 Remove data on uninstall 已开启，承运商会被删除（订单保留其历史记录），同时删除设置、已保存的订单服务和日志。如果关闭，承运商仅被停用，所有设置都会保留。重新安装模块或点击 Reset 后，已保存的承运商会恢复其之前的状态：原本开启的会再次开启，原本停用的仍保持停用。
USPS 是其各自所有者的商标。本模块与 USPS 无关联，也未获得 USPS 的认可。