VibeFox USPS for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本，并启用 cURL 扩展。

USPS Developer Portal 应用（仅用于实时费率）：使用免费的 USPS 商业账户登录 USPS Developer Portal（developers.usps.com），创建一个应用，并复制其 Consumer Key 和 Consumer Secret。本扩展通过 OAuth 2.0 使用当前的 USPS API。旧的 Web Tools User ID 无法用于此扩展。没有密钥时，仅使用固定价格。

发货邮政编码：实时费率需要包裹寄出地的 5 位美国邮政编码。

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

安装

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

OpenCart 3

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

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

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

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

5. 输入 Consumer Key 和 Consumer Secret、5 位数的 Ship from ZIP code，并选择 Services。如果您店铺的默认货币不是 USD，请输入 USD exchange rate。

6. 可选：输入固定价格作为备用，开启 Enable USPS shipping，然后点击 Save。

OpenCart 4

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

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

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

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

安装后，该方式保持关闭状态，直到您开启 Enable USPS shipping 并保存。如果您卸载后重新安装扩展，之前保留的 USPS 设置将再次生效。

配置

所有设置都在扩展页面中：Extensions > Extensions > Shipping > VibeFox USPS > Edit。各个部分列在左侧。页面底部的一个 Save 按钮会保存整个页面，无需重新加载。每次保存都会清除缓存的 USPS 令牌和费率。只有对本扩展拥有修改权限的管理员用户，才能保存设置、清除缓存或清空日志。

无效的值不会被保存：页面会指出对应字段，恢复之前的值，并显示 The other settings were saved. 这适用于以下情况：名称为空、过长或包含禁用字符；数字为负数或不是数字；邮政编码不是 5 位；箱子尺寸有误；Min weight (kg) 大于 Max weight (kg)（两个上限都保留原值）；排序不是整数；以及税类或地理区域未知。不是数字的国家价格会被清除并列出。设置上方的警告会告诉您：仅设置了两个密钥中的一个；没有任何密钥且没有固定价格（此时该方式永远不会显示）；缺少邮政编码；未选择任何服务；缺少 USD 汇率；测试环境已开启；或店铺的重量或长度单位无法被本扩展识别。

常规

这些设置适用于所有地理区域。USPS 在结账时作为一个配送选项提供。

Enable USPS shipping：在结账时提供 USPS 配送。默认：关闭。

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

Tax class：配送费的税类。USPS 价格不含税。No tax（默认）表示配送费不征税。

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

USPS API（实时费率）

Consumer Key：您的 USPS 开发者应用的 Consumer Key（client_id）。清空它也会删除已保存的 Consumer Secret。

Consumer Secret：同一应用的 Consumer Secret（client_secret）。保存后该字段为空，并显示 Saved — leave empty to keep it. Clearing the Consumer Key removes it too. 只有在需要更改时才输入新值。

Test environment：对发件人使用 USPS Testing Environment。仅适用于有权访问该环境的应用。要获取真实价格，请保持关闭。默认：关闭。

Prices：使用哪一种 USPS 价格表。

Services：可用于报价的 USPS 服务。将显示 USPS 为该包裹提供的、所选服务中最便宜的一项。可从 USPS Ground Advantage、Priority Mail / Priority Mail International、Priority Mail Express / Priority Mail Express International、First-Class Package International Service、Media Mail (books and media only) 和 Library Mail (libraries and schools only) 中选择。默认：Ground Advantage、Priority Mail 和 First-Class Package International。Flat Rate、Cubic、Hold for Pickup 和 Sunday 价格从不使用。如果未选择任何服务，则不使用实时费率。

USD exchange rate：USPS 价格以 USD 计价。如果您店铺的默认货币不是 USD，请输入 1 USD 等于多少您的货币的数值，例如 0.92。该值必须大于 0。没有它，就不使用实时费率，而是应用固定价格。如果您店铺的货币是 USD，则无需设置。汇率不会自动更新。

Cache：报价缓存 1 小时，失败的报价缓存 10 分钟。在超时、服务器错误、频率限制或密钥被拒绝之后，5 分钟内不会调用 USPS。点击 Clear cached USPS token and rates 可立即清空缓存。

发货与包裹（USPS 价格取决于发货邮政编码、重量和包裹尺寸；购物车按一个包裹报价）

Ship from ZIP code：包裹寄出的 5 位美国邮政编码。ZIP+4 会被截取为 5 位。OpenCart 没有店铺邮编字段，因此请在此处输入。

Box size (L x W x H)：可选的箱子尺寸，单位为您店铺的长度单位（显示在字段名称中），例如 30x20x15。留空则使用商品尺寸：最长边、最宽边和叠加后的高度。没有尺寸的商品按 10 x 8 x 4 英寸的箱子报价。

Default product weight (kg)：用于没有重量的商品的重量，用于 USPS 费率、重量限制和重量区间。默认：0.5。留空也表示 0.5 千克。

固定价格（以店铺默认货币计价，不含税；在未输入 API 密钥时使用，并在 USPS 未返回费率时作为备用；若两者都为空，则在此情况下隐藏该方式）

Country prices：按目的国家和购物车重量设定的价格。点击 Add country 添加一行，点击删除按钮可删除一行。重量区间为：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：当没有任何国家价格匹配时使用的固定运费。留空则在这种情况下隐藏该方式。

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。留空表示 30 kg，0 表示无限制。USPS 最多接受 70 磅（31.7 kg）：更重的包裹使用固定价格。

Geo zone：仅向此地理区域内的地址提供 USPS。All zones（默认）表示无限制。地理区域在 System > Localisation > Geo Zones 中管理。与 Ignore shipping zones 一起使用时无效。

不使用配送区域时的可用性

Ignore shipping zones：不检查地理区域。该方式将提供给下列国家。

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

高级

Debug log：将 API 请求和费率计算记录到 storage/logs/vfd_usps_debug.log.php（OpenCart 4 上为 system/storage/logs/vfd_usps_debug.log.php）。该文件无法通过网页读取。即使此选项关闭，API 错误也始终会被记录。密钥、令牌、邮政编码和顾客地址从不记录。文件达到 5 MB 时，会被移动到 vfd_usps_debug.old.log.php，并开始新的日志。

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

Remove data on uninstall：开启时，卸载扩展会删除 USPS 设置和日志。缓存的费率始终会被删除。已下单订单的 USPS 服务始终会保留。关闭时，设置会被保留，以便重新安装。

导入 / 导出

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

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

结账时的工作方式

OpenCart 显示配送方式时，会向扩展请求 USPS 价格。如果设置了 Geo zone 且地址在其之外，则不提供 USPS（若启用 Ignore shipping zones，则改由国家列表决定）。只有 Requires Shipping 设为 Yes 的商品才会计入：其他商品不增加重量，也不计入小计。礼品卡、积分和店铺余额不计入。随后，扩展检查条件：购物车重量和最低小计。如果适用免运费，价格为 0，并且不会向 USPS 发送请求。

扩展从 USPS 获取一个 OAuth 令牌，并在其即将过期前一直保留。对于美国及其领土（波多黎各、美属维尔京群岛、关岛、美属萨摩亚、北马里亚纳群岛、密克罗尼西亚、马绍尔群岛和帕劳）的目的地，扩展请求国内价格，并且需要顾客的 5 位邮政编码：没有邮编则不发送请求。对于其他国家，扩展请求国际价格。

请求包含发货邮政编码、购物车重量、包裹尺寸和价格类型。超过 70 磅的包裹使用固定价格。顾客看到一个选项，即所选服务中最便宜的一项。USD 价格会换算为您的默认货币，按其小数位取整，并以顾客的货币显示，同时加上所选 Tax class 的税费。

每个报价缓存 1 小时。失败的报价会被记住 10 分钟。在超时、服务器错误、频率限制或密钥被拒绝之后，5 分钟内不会调用 USPS。HTTP 超时时间为 10 秒。

如果 USPS 未返回费率，价格取自 Country prices，然后取自 Fallback cost。如果两者都不适用，则隐藏该方式。顾客永远看不到 USPS 的错误文本。原因会被写入调试日志。

本扩展仅计算费率。它不购买邮资或配送标签，不预约取件，不追踪包裹，也不允许顾客选择邮局或取件点。它只显示一个选项，而不是多个 USPS 服务。没有箱子装箱功能：购物车按一个包裹报价。保险及其他额外服务不包括在内。

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

订单

使用 USPS 下单时，扩展会保存配送价格的获取方式。Sales > Orders 中的订单页面会显示一个 USPS 面板，包括 USPS service（对于实时费率，例如 USPS Ground Advantage）、Price source（USPS live rate、Fixed price 或 Free shipping）以及 Calculated price (excl. tax)。这些值在下单时保存。

OpenCart 4 为结账保留一个订单，每当顾客再次确认时都会更新该订单。保存的值会随之更新。如果顾客改用其他配送方式，这些值会从订单中移除。在 OpenCart 4 中，USPS 面板显示在 History 部分上方。

许可证密钥

本扩展需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox USPS 是 Extensions > Extensions > Shipping > VibeFox USPS > Edit 页面中的第一个区块，位于设置上方。请将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以隐藏方式显示密钥，并显示状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now 用于重新检查状态，Change key 用于输入另一个密钥，Remove key 用于从本店铺中移除密钥。其下方是 Product: opencart-shipping-usps 一行和链接 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 账户中释放名额。

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

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

故障排除

结账时不显示 USPS：检查许可证是否有效，以及 Enable USPS shipping 是否已开启。检查 Geo zone，或开启 Ignore shipping zones 并检查 Countries。检查重量限制和 Minimum subtotal。如果没有可用的 USPS 密钥，该方式需要固定价格（Country prices 或 Fallback cost）。检查商品的 Requires Shipping 是否设为 Yes。

不显示实时费率：检查 Edit 页面顶部的警告：两个密钥、邮政编码、至少一个服务，以及对于非 USD 店铺的汇率。美国顾客必须输入邮政编码。开启 Debug log，重新加载结账页面，然后查看扩展页面中的 Log 字段。

费率不是真实价格：关闭 Test environment。

页面提示重量或长度单位问题：如果没有使用 kg 单位的重量类别，无法识别的重量单位将按 kg 处理。请在 System > Localisation > Weight Classes 中添加一个 kg 重量类别。店铺中无法识别的长度单位将按 cm 处理。请使用 cm、mm、m 或 in 作为店铺的长度类别（System > Settings，Option 选项卡）。

更改后费率看起来过时：点击扩展页面上的 Save，或点击 Clear cached USPS token and rates。

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

面向开发者：USPS API 地址可通过设置 vfd_usps_api_url（用于测试）进行替换；设置页面中没有对应字段。

卸载

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

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

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