VibeFox EasyPost for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本，并启用 cURL 扩展。缺少这些条件时模块将拒绝安装。
EasyPost 账户（仅用于实时运费）：在 EasyPost 网站上创建账户，在 EasyPost 控制台中连接您的承运商账户（USPS、UPS、FedEx 等），并从 EasyPost Dashboard > Account Settings > API Keys 复制 API 密钥。EasyPost 对已购买的运单收费，而不是对运费查询收费。如果您只使用备用价格，则无需 EasyPost 账户。
商品：商品需要设置重量，最好同时设置尺寸。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或之后在模块列表中找到 VibeFox EasyPost，再点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，于 License key 字段输入您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。
4. 粘贴您的 EasyPost API 密钥，并填写 Ship from 地址。实时运费需要填写邮政编码。
5. 如果您的默认货币不是 USD，请输入 USD exchange rate。也可以选择输入备用价格（参见配置）。点击 Save。
安装时，模块会创建 EasyPost Shipping 承运商，配送时间文本为 Live carrier rate (EasyPost)。该承运商会分配给所有区域和所有顾客群组。您可以在 Shipping > Carriers 中更改区域、顾客群组、配送时间、徽标和尺寸限制。请勿在那里设置价格：价格始终来自模块。
配置
所有设置都在模块页面中：Modules > Module Manager > VibeFox EasyPost > Configure。每个部分都有自己的 Save 按钮，保存时会保存整个页面。每次保存也会清除已缓存的 EasyPost 运费。
页面顶部，当无法使用实时运费时，模块会显示警告：未设置 API 密钥（无论是否设置备用价格）、未填写发货邮政编码或国家，或默认货币不是 USD 且未设置汇率。设置了测试 API 密钥时会显示提示；模块的承运商被删除时会显示错误；店铺的重量或尺寸单位（International > Localization）不是模块支持的单位时（kg、g、lb、oz；cm、mm、m、in）会显示警告。
保存时，不是数字（或为负数）的值不会被保存：警告会指出该字段，并保留之前的值。当 USD exchange rate 为 0，或 Minimum weight 大于 Maximum weight 时，也会发生同样的情况。
常规
Enable EasyPost shipping: 启用或停用该承运商。这与 Shipping > Carriers 中的承运商状态使用同一开关。默认：on。
Name: 结账时显示给顾客的承运商名称，最多 64 个字符（超过的名称会被拒绝，且不保存任何内容）。默认：EasyPost Shipping。如果名称为空，或包含 PrestaShop 不允许用于承运商名称的字符，则使用默认名称。
EasyPost 账户
API key: 来自 EasyPost Dashboard > Account Settings > API Keys 的 EasyPost API 密钥。生产密钥（以 EZAK 开头）返回真实运费。测试密钥（以 EZTK 开头）返回 EasyPost 测试运费；请仅用于测试。保存后，该字段保持为空，并以掩码形式显示已保存的密钥，例如 EZAK******abcd。留空即可保留该密钥。只有在需要更改时才输入新值。
Remove the saved API key: 勾选此框并点击 Save，即可删除已保存的密钥。
Allowed carriers / services: 可选，用逗号分隔。按 EasyPost 的名称输入承运商（USPS），或承运商和服务（USPS:Priority、UPS:Ground）。将显示允许范围内最便宜的运费。留空则显示任何承运商中最便宜的运费。
发货地址
包裹的寄出地址。如果 Country 是您店铺所在国家，空白字段将从 Shop Parameters > Contact > Stores 中的店铺地址获取（寄件人名称取自店铺名称）。
Sender name / company: 寄件人姓名或公司名称。
Street address: 发货地址的街道。
City: 发货地址的城市。
State: 两位字母的州代码，例如 CA 或 NY。
ZIP code: 发货地址的邮政编码。实时运费必填。
Country: 您发货所在的国家。默认：United States。
运费
Parcels: 购物车如何发送给 EasyPost。
重量会从店铺单位换算为盎司（最少 1 oz），尺寸换算为英寸。如果任何商品没有尺寸，则仅按重量计算包裹运费。
USD exchange rate: EasyPost 运费以美元计。请输入 1 美元对应的默认货币价格，例如 0.92。未设置时不会使用实时运费，只使用备用价格。默认货币为 USD 时无需设置。使用 USD 和 CAD 的店铺会要求 EasyPost 以其自身货币报价。小数点和逗号都可作为小数分隔符。
Tax: 承运商的税务规则，或 No tax。EasyPost 运费不含销售税。请选择适用于运费的税务规则。
备用价格
当没有实时运费时使用：未设置 API 密钥、无法连接 EasyPost、密钥被拒绝，或没有承运商对该地址有运费。价格以默认货币计，不含税。在这种情况下，若要隐藏承运商，请将两个字段都留空。
Country prices: 每个国家一行：两位字母的国家代码、冒号和价格，例如 US:9.99。格式不同的行会被忽略，并在保存时列在警告中。
Other countries: 上面列表中未包含的国家的价格。留空则对这些国家隐藏承运商。
条件
Free shipping from: 购物车小计（待发货商品、扣除折扣后、税前，以默认货币计）达到该金额即免运费。此时不会向 EasyPost 发出请求。留空则关闭此功能。
Minimum subtotal: 只有当购物车小计（待发货商品、扣除折扣后、税前）至少达到该金额时才显示承运商。留空则始终显示。
Minimum weight: 购物车重量低于该值时隐藏承运商，单位为店铺的重量单位（显示在字段标签中）。0 表示无限制。
Maximum weight: 购物车重量高于该值时隐藏承运商，单位为店铺的重量单位。0 表示无限制。
无配送区域时的可用性
通常，承运商在 Shipping > Carriers 中分配给它的区域内提供。另外，也可以不考虑区域，按国家提供。
Ignore shipping zones: 对下方列出的国家提供承运商，无论其所在区域是否分配给该承运商。启用此选项保存时，承运商会被分配到所有区域，包括之后创建的区域。关闭此选项时，承运商将恢复其之前的区域。
Countries: 该模式下的目的地国家。使用 Ctrl+点击可选择多个。留空则使用店铺中所有启用的国家。仅当 Ignore shipping zones 启用时，才会使用此字段。
高级
Debug log: 将 EasyPost 请求写入 modules/vfd_easypost/logs/vfd_ep.log.php。该文件无法通过网页打开，并在达到 5 MB 时轮换。即使此选项关闭，API 错误也始终会被记录。API 密钥和顾客地址从不记录。
Remove data on uninstall: 启用时，卸载模块会删除其设置、数据表和日志。停用模块永远不会删除设置。
Log: 设置下方的面板显示日志的最近 100 行。点击 Clear log 可清空日志。
结账时的工作方式
在配送步骤中，PrestaShop 会向模块请求 EasyPost 价格。只有实体商品计入：虚拟商品不增加重量，也不计入小计。模块首先检查条件：目的地国家（使用 Ignore shipping zones 时）、购物车重量和最低小计。如果适用免运费，价格为 0，且不会向 EasyPost 发出请求。
否则，模块会将发货地址、收货地址和包裹发送给 EasyPost，并接收您所有承运商账户的运费。它会选择允许范围内最便宜的运费，将其换算为默认货币，并以顾客的购物车货币显示。对于需要邮政编码的国家，只有收货地址中有邮政编码时才会发出请求。在顾客填写地址之前，只知道访客所在的国家，因此需要邮政编码的国家会在地址填写前使用备用价格。
每个响应会针对相同的地址和包裹缓存 1 小时。没有可用运费的地址会被记住 10 分钟。发生超时、密钥被拒绝、速率限制或 EasyPost 服务器错误后，5 分钟内不会发出任何请求。API 超时时间为 10 秒。在所有这些情况下，顾客都不会看到错误：使用备用价格，如果没有备用价格，则隐藏承运商。原因会写入日志。
如果承运商在拥有订单之后，您在 Shipping > Carriers 中编辑了它，PrestaShop 会将其保存为新的承运商版本。模块会自动跟随新版本。
模块只计算运费。它不购买运单、不跟踪包裹、不验证地址、不提供取件或投递网点，也不添加保险或签收选项。它只显示一个选项（允许范围内最便宜的运费），而不是服务列表。除了将商品放入一个包裹外，不进行装箱，也没有运费加价或手续费。
订单
使用 EasyPost 承运商下单时，结账时显示的运费会与订单一起保存。后台订单页面会显示 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 账户中购买运单。已放弃购物车的运费会在 30 天后删除。
许可证密钥
本模块需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox EasyPost 是 Modules > Module Manager > VibeFox EasyPost > Configure 中的第一个区块，位于设置上方。请将密钥输入 License key，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从此商店移除密钥）。其下方有一行 Product: presta-shipping-easypost，以及打开您 vibefox.net 账户的链接 Manage licenses and domains in your account。只有拥有本模块 Configure 权限的员工才能更改密钥。该区块的文字跟随后台语言显示（包括英语和俄语）。
如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或带有日期的 License expired on。商店地址变更后，或在您的账户中释放了域名名额后，请点击 Check now。如果无法连接许可证服务器，模块将按照最后已知的状态继续运行。
一个密钥只能用于一个域名：主商店的域名，多店铺配置下同样如此。从商店中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效的密钥时，结账时不会向顾客显示 EasyPost 承运商，也不会计算运费。PrestaShop 前台无法得知您已登录后台，因此该承运商对您也是隐藏的：您可以在购买密钥之前设置模块，但无法在结账时进行测试。Modules > Module Manager 的 Alerts 选项卡中会出现提醒。现有订单不受影响。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。您在后台工作时，状态会自动重新检查：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时没有显示 EasyPost：请检查许可证是否有效，以及 Enable EasyPost shipping 是否已启用。在 Shipping > Carriers 中，检查该承运商是否已启用，并覆盖顾客所在国家的区域和顾客群组（或者 Ignore shipping zones 已启用且已选择该国家）。检查重量限制和 Minimum subtotal。没有实时运费时，承运商需要为该国家或 Other countries 设置备用价格。在商品页面中，也可以将商品限制为特定承运商。
实时运费未显示：请阅读模块页面顶部的警告，然后启用 Debug log，重新加载结账页面，并查看 Log 面板。常见原因：未设置 API 密钥或发货邮政编码；非 USD 店铺未设置 USD exchange rate；收货地址尚无邮政编码；您的 EasyPost 账户中没有承运商服务该地址；或 Allowed carriers / services 过滤掉了所有运费。
运费看起来像测试价格：已设置测试密钥（EZTK...）。请在正式店铺中使用生产密钥（EZAK...）。
运费暂停了几分钟：发生超时、密钥被拒绝或 EasyPost 服务器错误后，模块会暂停请求 5 分钟，并使用备用价格。请检查 API 密钥和日志。
是否含税？EasyPost 运费不含销售税。请在 Tax 中选择税务规则，以便为运费添加税款。
更改后运费似乎过时：在模块页面点击 Save。这会清除已缓存的 EasyPost 运费。
页面提示未找到模块的承运商：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块，以重新创建它。
开发者钩子：钩子 actionVfdEpShipmentRequest（请求正文）、actionVfdEpSelectedRate（所选运费）和 actionVfdEpApiUrl（API 基础 URL）可用于调整模块。
卸载
进入 Modules > Module Manager，打开 VibeFox EasyPost 旁边的菜单，然后选择 Uninstall。许可证密钥和许可证状态始终会被删除。承运商会从结账中移除（订单保留其历史记录），并且已缓存的运费始终会被删除。如果 Remove data on uninstall 已启用，设置、已保存的订单运费和日志也会被删除。如果已关闭，则保留设置以及已下单订单的 EasyPost 数据，以便重新安装。安装或重置模块会创建新的承运商。如果保留了设置，它将沿用之前承运商的状态（启用或停用）。
EasyPost 是其各自所有者的商标。本模块与 EasyPost 无关联，也未获得 EasyPost 的认可。