VibeFox EasyPost for OpenCart — 帮助

系统要求

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

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

EasyPost 账户（仅用于实时运费）：在 EasyPost 网站上创建账户，在 EasyPost 控制面板中连接您的承运商账户（USPS、UPS、FedEx 等），并从 EasyPost Dashboard > Account Settings > API Keys 复制 API 密钥。EasyPost 对购买的面单收费，而不是对运费查询收费。如果您只使用备用价格，则无需 EasyPost 账户。

商品：商品需要设置重量，最好也设置尺寸。

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

安装

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

OpenCart 3

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

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

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

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

5. 粘贴您的 EasyPost API 密钥，并填写 Ship from 地址。实时运费需要邮政编码。

6. 如果默认货币不是 USD，请输入 USD exchange rate。也可以输入备用价格（参见配置）。开启 Enable EasyPost shipping，然后点击 Save。

OpenCart 4

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

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

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

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

安装后，该方式保持关闭，直到您开启 Enable EasyPost shipping 并保存。如果您卸载后重新安装该扩展，将重新使用您保留的设置。

配置

所有设置都位于扩展页面：Extensions > Extensions > Shipping > VibeFox EasyPost > Edit。分区列在左侧。点击一个 Save 按钮即可保存整个页面，无需刷新。每次保存还会清除缓存的 EasyPost 运费。只有拥有该扩展修改权限的管理员用户才能保存设置或清空日志。

页面顶部，当无法使用实时运费时，扩展会显示警告：没有 API 密钥（无论是否有备用价格）、没有发货邮政编码或国家，或者默认货币不是 USD 且没有汇率。设置了测试 API 密钥时还会出现提示；如果您店铺的重量或长度单位（System > Settings > Option）不是扩展支持的单位（kg、g、lb、oz；cm、mm、m、in），则会出现警告。

保存时，超过 64 个字符的名称、不是整数的 Sort order，或未知的税类或地理区域都会阻止保存，此时不会保存任何内容。不是数字（或为负数）的值不会被保存：警告会指出该字段，并保留之前的值，其他设置仍会保存。当 USD exchange rate 为 0，或 Minimum weight 大于 Maximum weight 时，也会出现同样的情况。

常规

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

Name：顾客在结账时看到的配送方式名称，最多 64 个字符。默认：EasyPost Shipping。如果名称为空，则使用默认名称。包含字符 < > ; = # { } 的名称会被替换为默认名称，并给出警告。

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

EasyPost 账户

API key：您在 EasyPost Dashboard > Account Settings > API Keys 中的 EasyPost API 密钥。生产密钥（以 EZAK 开头）会返回真实运费。测试密钥（以 EZTK 开头）会返回 EasyPost 测试运费；仅用于测试。保存后该字段保持为空，并以掩码形式显示已保存的密钥，例如 Saved key: EZAK******abcd. Leave the field empty to keep it. 只有需要更改时才输入新值。没有密钥时，只使用备用价格。

Remove the saved API key：开启后点击 Save，即可删除已保存的密钥。

Allowed carriers / services：可选，用逗号分隔。按 EasyPost 的名称输入承运商（USPS），或承运商和服务（USPS:Priority、UPS:Ground）。将显示允许范围内最便宜的运费。留空则显示任何承运商中最便宜的运费。

发货地址

您的包裹寄出的地址。如果 Country 是您店铺所在的国家，则空的 Sender name / company 会取自店铺名称，空的 State 会取自您店铺所在的地区（System > Settings）。OpenCart 没有店铺邮政编码，因此必须在此处输入邮政编码。

Sender name / company：发件人姓名或公司。留空表示使用店铺名称（仅限同一国家）。

Street address：发货地址的街道。

City：发货地址的城市。

State：两字母州代码，例如 CA 或 NY。

ZIP code：发货地址的邮政编码，例如 94105。实时运费必填。

Country：您发货所在的国家。默认：United States。

运费

Parcels：购物车如何发送给 EasyPost。

重量会从店铺的重量单位换算为盎司（最少 1 oz），尺寸会从店铺的长度单位换算为英寸。如果任何商品没有尺寸，则仅按重量计算包裹运费。

USD exchange rate：EasyPost 运费以 USD 计。请输入 1 USD 等于店铺默认货币的价格，例如 0.92。没有此项时，不使用实时运费，只使用备用价格。默认货币为 USD 时无需设置。USD 和 CAD 店铺会要求 EasyPost 以其自身货币报价。小数点和逗号均可作为小数分隔符。

Tax class：应用于配送费用的税类，或 No tax。EasyPost 运费不包含销售税。

备用价格

在没有实时运费时使用：没有 API 密钥、无法连接 EasyPost、密钥被拒绝，或没有承运商为该地址提供运费。价格以店铺默认货币计，不含税。两个字段都留空时，在这种情况下会隐藏该方式。

Country prices：每个国家一行：两字母国家代码、冒号和价格，例如 US:9.99。其他格式的行会被忽略，并在保存时列在警告中。

Other countries：未在上方列表中的国家所使用的价格。留空则对这些国家隐藏该方式。

条件

Free shipping from：购物车小计（待发货商品，扣除优惠券后、税前，以默认货币计）达到此金额后免运费。在这种情况下不会向 EasyPost 发送请求。留空则关闭。

Minimum subtotal：仅当购物车小计（待发货商品，扣除优惠券后、税前）至少为此金额时才显示该方式。留空则始终显示。

Minimum weight：购物车重量低于此值时隐藏该方式，单位为店铺的重量单位（显示在字段标签中）。0 表示不限制（默认）。

Maximum weight：购物车重量高于此值时隐藏该方式，单位为店铺的重量单位。0 表示不限制（默认）。

可用性

通常由地理区域决定该方式在哪里提供。也可以选择按国家提供，与地理区域无关。

Geo zone：仅向该地理区域内的地址提供该方式。All zones（默认）表示不限制。地理区域在 System > Localisation > Geo Zones 中管理。与 Ignore shipping zones 不同时使用。

Ignore shipping zones：无论是否在地理区域内，都向下方列出的国家提供该方式。

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

高级

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

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

Remove data on uninstall：开启后，卸载扩展会删除其设置和日志。已下单订单中的 EasyPost 数据会保留。关闭该方式从不删除设置。

导入 / 导出

Export：点击 Download JSON 可将设置保存为 JSON 文件。API 密钥不会被导出。

Import：粘贴之前导出的 JSON，然后点击 Import 恢复设置，例如在另一家商店中。这些值会像正常保存一样进行检查。已保存的 API 密钥不会被更改。

结账时的工作方式

OpenCart 显示配送方式时，会向扩展请求 EasyPost 的价格。如果设置了 Geo zone（且 Ignore shipping zones 已关闭），而地址不在该区域内，则不会提供该方式。只有 Requires Shipping 设为 Yes 的商品才会计入：其他商品不增加重量，也不计入小计。扩展首先检查条件：目的国家（配合 Ignore shipping zones）、购物车重量和最低小计。小计是需要配送的商品价格，即扣除优惠券折扣后、税前的金额。礼品卡、积分和店铺余额不计入。如果适用免运费，则价格为 0，并且不会向 EasyPost 发送请求。

否则，扩展会将发货地址、收货地址和包裹发送给 EasyPost，并接收您所有承运商账户的运费。它会选择允许范围内最便宜的运费，将其换算为店铺默认货币，并以顾客的货币显示，同时包含所选 Tax class 的税款。对于在 System > Localisation > Countries 中标记为 Postcode Required 的国家，只有在收货地址有邮政编码时才会发出请求。在 OpenCart 的标准数据中，美国的该标记是关闭的，因此没有邮政编码的美国地址也会被发送；此时 EasyPost 会返回错误，并使用备用价格。

每个响应会针对相同的地址和包裹缓存 1 小时。没有可用运费的地址会被记住 10 分钟。超时、密钥被拒绝、请求频率受限或 EasyPost 服务器错误后，5 分钟内不会发出任何请求。API 超时时间为 10 秒。在所有这些情况下，顾客都不会看到错误：使用备用价格；如果没有备用价格，则隐藏该方式。原因会写入日志。

本扩展只计算运费。它不购买面单、不追踪包裹、不验证地址、不提供取货或寄存点，也不添加保险或签收选项。它只显示一个选项（允许范围内最便宜的运费），而不是服务列表。除了将商品装入一个包裹外，没有任何箱子优化，也不加收运费附加费或手续费。

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

订单

使用 EasyPost 方式下单后，结账时显示的运费会与订单一起保存。后台订单页面（Sales > Orders）在历史记录上方显示 EasyPost shipping 面板：

Carrier / service：该运费对应的 EasyPost 承运商和服务，例如 USPS Priority。在每件商品一个包裹模式下，会列出所有使用的服务。

Estimated delivery days：EasyPost 返回的配送天数（仅在每个订单一个包裹模式下，且 EasyPost 返回时）。

Price source：Live EasyPost rate、Fallback price (no live rate) 或 Free shipping threshold。

Calculated price (excl. tax)：店铺默认货币下的价格。

即使之后关闭该扩展，此面板仍会显示。之后在后台对订单所做的更改不会改变这些值。请使用这些信息在您的 EasyPost 账户中购买面单。每当结账进入确认步骤时，OpenCart 都会创建一条订单记录；这些未完成订单保存的运费会在 30 天后删除。

在 OpenCart 4 中，结账会保留一个订单，并在顾客每次重新确认时更新它。保存的运费随之更新：它是顾客在结账时看到的运费。如果顾客切换到其他配送方式，该订单的面板将不再显示。

许可证密钥

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

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

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

故障排除

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

实时运费未显示：请阅读扩展页面顶部的警告，然后开启 Debug log，重新加载结账页面，并查看 Log 字段。常见原因：没有 API 密钥或发货邮政编码；非 USD 店铺却没有 USD exchange rate；收货地址还没有邮政编码；您的 EasyPost 账户中没有承运商为该地址提供服务；或 Allowed carriers / services 过滤掉了所有运费。

运费看起来像测试价格：已设置测试密钥（EZTK...）。请在正式店铺中使用生产密钥（EZAK...）。

运费停止了几分钟：超时、密钥被拒绝或 EasyPost 服务器错误后，扩展会暂停请求 5 分钟，并使用备用价格。请检查 API 密钥和日志。

是否包含税款？EasyPost 运费不包含销售税。请在 Tax class 中选择税类，以便为配送费用加税。

更改后运费看起来过时：在扩展页面点击 Save。这会清除缓存的 EasyPost 运费。

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

面向开发者：其他扩展可以通过 OpenCart 事件 vfd_easypost/shipment_request、vfd_easypost/selected_rate 和 vfd_easypost/api_url 调整请求正文、所选运费和 API 基础 URL。

卸载

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

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

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