VibeFox Purolator for OpenCart — 帮助
系统要求
OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP：8.0 或更高版本，并启用 cURL 扩展。无需 PHP SOAP 扩展。
Purolator E-Ship Web Services（仅用于实时运费）：请在 Purolator 网站的 Purolator E-Ship Resource Centre 中注册 E-Ship Web Services。Purolator 会为开发环境和正式环境分别提供密钥和密码。您还需要 Purolator 结算账户号码，以及您发货所在的加拿大邮政编码。如果只使用固定价格，则无需 API 密钥。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
下载文件是一个 zip 压缩包，内含两个 OpenCart 版本的安装包。请在您的电脑上解压。其中包括 README.txt、OpenCart 3 安装包 vfd_purolator-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 vfd_purolator.ocmod.zip。请只安装与您的 OpenCart 版本对应的安装包。两个版本使用相同的许可证密钥。
OpenCart 3
1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_purolator-oc3-(version).ocmod.zip。本扩展不添加 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用 Installer，而是将安装包中 upload 文件夹的内容复制到商店的根目录。
2. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Purolator，点击 Install（绿色的 + 按钮）。
3. 点击 Edit（铅笔按钮）打开设置页面。
4. 在 Edit 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥粘贴到 License key，然后点击 Activate（参见许可证密钥）。
5. 如需实时运费，请填写 Purolator API (live rates) 部分：API 密钥、密码、结算账户号码、加拿大发货邮政编码，如果店铺货币不是 CAD，还需填写 CAD 汇率。测试时，请使用开发密钥开启 Development environment。如需固定价格或备用价格，请填写 Country prices 或 Fallback price（参见配置）。开启 Enable Purolator 并点击 Save。
OpenCart 4
1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_purolator.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包无法使用。
2. 安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。
3. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Purolator，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按 OpenCart 3 第 4 和第 5 步的方式输入许可证密钥和设置。两个版本的设置页面及其字段相同。
安装后，直到您开启 Enable Purolator 并保存，该配送方式都保持关闭。如果您卸载后重新安装本扩展，之前保留的 Purolator 设置会再次生效。
配置
所有设置都在扩展页面中：Extensions > Extensions > Shipping > VibeFox Purolator > Edit。各分区列在左侧。页面底部的一个 Save 按钮可在不重新加载页面的情况下保存整个页面。每次保存还会清除缓存的 Purolator 运费。只有拥有本扩展修改权限的管理员用户才能保存设置。
如果实时运费无法使用已保存的值工作（缺少密钥、密码或结算账户，没有加拿大发货邮政编码，没有 CAD 汇率），或者既没有 API 凭据也没有固定价格，则 General 部分会显示警告。警告还会说明在此之前是使用固定价格，还是隐藏该配送方式。如果店铺的重量单位不是扩展所支持的单位，也会显示警告。此时商品重量会按 kg 读取；请在 System > Localisation > Weight Classes 中添加单位为 kg 的重量等级。
不包含 0 或更大数字的数字字段不会被保存。点击 Save 后显示的消息会指出字段和值。该字段会留空，或在重量字段中使用默认值。Country prices 中的错误值会保存为 0，消息会列出国家和列。如果配送方式名称为空或超过 64 个字符，如果 Min cart weight (kg) 大于 Max cart weight (kg)，如果排序不是整数，或者税类或地理区域无效，则不会保存任何内容，并会显示错误。
常规
顾客只会看到一个 Purolator 运费。这些设置适用于所有地理区域。您可以在 Availability 中将该配送方式限制在某个地理区域或某些国家。
Enable Purolator：在结账时显示或隐藏 Purolator。默认：关闭。
Method title：结账时向顾客显示的配送方式名称。默认：Purolator。必填，最多 64 个字符。
Tax class：运费的税类，或 No tax（默认）。它决定店铺是否在运费之上加收税费。对于加拿大地址，Purolator 总价已包含 GST/HST/PST/QST。请参阅下方的 Canadian sales taxes。
Sort order：Purolator 在结账时配送方式中的位置。一个整数。
Purolator API（实时运费）
填写 API 密钥、密码和结算账户后，价格来自 Purolator E-Ship Estimating 网络服务（按购物车总重量进行 Quick Estimate）。如果 Purolator 未返回运费，则使用固定价格，若没有固定价格则隐藏该配送方式。该部分包含一个指向 Purolator E-Ship Resource Centre 的链接，您可以在那里注册并获取密钥。错误详情会记录到日志中，绝不会显示给顾客。
API key：所选环境的 E-Ship Web Services 密钥。保存后，该字段保持为空，并显示 Saved — leave empty to keep it. 只有需要更改时才输入新值。
API password：与密钥对应的密码。与密钥一样，保存后不会再次显示。
Billing account number：您的 Purolator 账户号码。估价使用该账户的运费。开发环境接受 Purolator 文档中的测试账户。清空此字段也会删除已保存的 API 密钥和密码。
Development environment：使用 Purolator 开发环境（devwebservices）和开发密钥。价格为测试数据。在正式运营的店铺中请关闭此项。
Ship-from postal code：包裹发出所在的加拿大邮政编码，例如 L4W 5M8。OpenCart 没有店铺邮政编码，因此不会从店铺地址中获取：请在此处输入。
Service in Canada：Cheapest available（默认）、Purolator Ground、Purolator Ground 9AM、Purolator Ground 10:30AM、Purolator Ground Evening、Purolator Express、Purolator Express 9AM、Purolator Express 10:30AM、Purolator Express 12PM 或 Purolator Express Evening。
Service to the USA：Cheapest available（默认）、Purolator Ground U.S.、Purolator Express U.S.、Purolator Express U.S. 9AM、Purolator Express U.S. 10:30AM 或 Purolator Express U.S. 12:00。
International service：Cheapest available（默认）、Purolator Express International、Purolator Express International 9AM、Purolator Express International 10:30AM 或 Purolator Express International 12:00。
如果所选服务不适用于该地址，则使用可用的最便宜服务。
Canadian sales taxes：使用不含 GST/HST/PST/QST 的 Purolator 价格。对于加拿大地址，Purolator 总价包含这些税费。当店铺自行对运费加收税费时（在 General 中设置税类），请开启此项，以免重复收税。默认：关闭。
CAD → (store currency) rate：Purolator 价格以加元（CAD）计。如果店铺默认货币不是 CAD，请填写 1 加元等于多少单位您的货币，例如 0.68。没有此值时，不会使用实时运费。如果您的默认货币是 CAD，请留空。
Default product weight (kg)：用于没有重量的每个商品。默认：0.5。重量会根据商品的重量等级换算，并以整磅为单位（向上取整）作为总重量发送给 Purolator。
固定价格（在没有 API 凭据时使用，并在 API 未返回运费时作为备用）
Country prices：按国家和购物车重量设置的价格，以店铺默认货币计，不含税。点击 Add country 添加一行，点击 × 按钮删除一行。选择 * Default (all other countries) 可设置覆盖所有没有自有行的国家的一行。每行包含一个 Base 价格和尺寸列：XS 为 1 kg 及以下，S 为 1–2 kg，M 为 2–3 kg，L 为 3–5 kg，XL 为 5 kg 以上。尺寸价格为空或为零时使用 Base。Base 为 0，或 Base 为空，表示对于没有自有尺寸价格的重量免运费。9.99 和 9,99 均可接受。没有任何价格的行不会被保存，并且每个国家只保留一行。
Fallback price：适用于在 Country prices 中既没有行、也没有 * 行的国家的价格。将其留空即可对这些国家隐藏该配送方式。
Fixed price per：Order（默认）只收取一次价格。Item (price x quantity) 则按购物车中的商品数量相乘。这仅适用于固定价格。实时运费始终按整个发货量计算。
条件
Min cart weight (kg)：购物车重量低于此值时隐藏该配送方式。0 表示无限制（默认）。
Max cart weight (kg)：购物车重量高于此值时隐藏该配送方式。默认：30。如果留空，则使用 30 kg。0 表示无限制。
Minimum order amount：仅当需要配送的商品小计（扣除优惠券后、税前）达到此金额时才显示该配送方式。留空则始终显示。
Free shipping from：需要配送的商品小计（扣除优惠券后、税前）达到此金额时免运费。此时不会向 Purolator 发送请求。留空则从不提供免运费。
可用性
Geo zone：仅对此地理区域内的地址提供 Purolator。All zones（默认）表示无限制。地理区域在 System > Localisation > Geo Zones 中管理。开启 Ignore shipping zones 时不进行检查。
Ignore shipping zones：无论选择哪个地理区域，都对下方列出的国家提供该配送方式。
Countries：此模式下的目的国家。留空则使用店铺中启用的所有国家。仅当 Ignore shipping zones 开启时才使用此字段。
高级
Debug log：将运费计算写入 storage/logs/vfd_prlr_debug.log.php（OpenCart 4 上为 system/storage/logs/vfd_prlr_debug.log.php）。该文件无法通过网页读取。即使调试日志关闭，API 错误也始终会被记录。API 密钥、结算账户和顾客邮政编码不会被记录。完成后请关闭日志。当文件达到 5 MB 时，它会被移至 vfd_prlr_debug.old.log.php，并开始新的日志。
Log：显示调试日志的大小和最新条目。点击 Clear log 可清空。
Remove data on uninstall：开启时，卸载扩展会删除 Purolator 设置和日志。关闭时，这些内容会被保留，以便重新安装。缓存的运费始终会被删除。已下单订单中的 Purolator 服务始终保留。
导入 / 导出
Export：点击 Download JSON，将设置保存为 JSON 文件。API 密钥和密码不会被导出。
Import：粘贴之前导出的 JSON，然后点击 Import 恢复设置，例如在另一家店铺中使用。数值的检查方式与普通保存相同。已保存的 API 密钥和密码会保留。
结账时的工作方式
OpenCart 显示配送方式时，会向扩展询问 Purolator 价格。如果设置了 Geo zone 且地址在其之外，则不会提供 Purolator（除非开启了 Ignore shipping zones）。只有 Requires Shipping 设为 Yes 的商品才会计算在内：其他商品不增加重量，也不计入订单金额。扩展首先检查条件：允许的国家（配合 Ignore shipping zones）、购物车重量和最低订单金额。订单金额是需要配送的商品在扣除优惠券折扣后、税前的价格。礼品卡、积分和店铺余额不计入。如果适用免运费，价格为 0，且不会向 Purolator 发送请求。否则，扩展会查找价格：先是 Purolator 实时运费，然后是国家价格表，最后是备用价格。如果没有价格，则隐藏该配送方式。
在有 API 凭据的情况下，扩展会向 Purolator 发送 Quick Estimate 请求：您的结算账户、发货邮政编码、顾客的城市、省份或州、国家和邮政编码，以及以整磅为单位的购物车总重量。加拿大需要有效的邮政编码，美国需要有效的 ZIP 码；其他国家则按输入的邮政编码发送。不会发送尺寸（体积重量）。当顾客以法语查看店铺时，Purolator 以法语回复，否则以英语回复。Purolator 会返回所有服务的价格；扩展会采用您选择的服务或最便宜的服务，如已设置则扣除加拿大销售税，并将加元价格换算。价格以店铺默认货币计算，按其小数位取整，并以顾客的货币显示，同时包含所选 Tax class 的税费。
每个响应缓存 1 小时，因此相同的购物车不会触发新的请求。失败的请求缓存 10 分钟，因此 Purolator 的故障不会拖慢每次结账刷新。API 超时时间为 10 秒。
如果 Purolator 未返回运费（API 不可用、凭据或邮政编码错误、服务不可用、没有 CAD 汇率），顾客不会看到错误。将使用固定价格，如果没有固定价格，则隐藏该配送方式。原因会写入日志。
扩展仅计算运费。它不会创建 Purolator 运单、不打印面单、不预约取件、不处理退货，也不跟踪包裹。它不使用 Full Estimate（尺寸、多件包裹、签收或危险品等选项），不显示配送日期，不将多个服务作为单独选项显示，也不自动获取汇率。顾客看不到 Purolator 服务名称，只会看到您设置的配送方式名称。
在 OpenCart 4 上，顾客在结账页面的配送方式区块中点击 Choose，然后在 Shipping method options 窗口中选择 Purolator。该配送方式的工作方式与 OpenCart 3 相同。
订单
使用 Purolator 实时运费下单时，服务会与订单一起保存。在 Sales > Orders 中，订单页面在历史记录上方显示 Purolator 面板，包含 Purolator service（名称和代码）以及 Live rate (excl. tax)。即使之后关闭该配送方式，面板仍会保持可见。使用固定价格或免运费的订单没有该面板。订单本身会像 OpenCart 的其他配送方式一样显示配送方式名称和运费。
OpenCart 4 为结账保留一个订单，并在顾客每次重新确认时更新它。已保存的 Purolator 服务会随之更新为最新的实时运费。如果订单改用其他配送方式，或改为没有实时运费的价格，已保存的服务将从订单中移除。
许可证密钥
本扩展需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Purolator 是 Extensions > Extensions > Shipping > VibeFox Purolator > Edit 页面中设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会显示隐藏部分字符的密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now 用于重新检查状态，Change key 用于输入另一个密钥，Remove key 用于从本店铺中移除该密钥。其下方有一行 Product: opencart-shipping-purolator，以及链接 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 账户中释放该名额。
如果没有有效的密钥，Purolator 配送方式不会在结账时显示给顾客，也不会请求或计算运费。以同一浏览器登录后台的管理员仍可在商店中看到该配送方式，并标记为 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试扩展。在 OpenCart 4 上没有此预览：商店看不到后台登录状态，因此没有有效密钥时，所有人都看不到该配送方式。打开一次 Edit 页面后，后台 Dashboard 会出现提醒。点击 × 关闭，可隐藏 7 天。现有订单不受影响。
许可证到期后，扩展仍会继续运行，但更新和支持需要续费。打开后台 Dashboard 或 Edit 页面时会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 Cron 任务。卸载扩展时始终会删除许可证密钥和许可证状态。
故障排除
结账时没有显示 Purolator：请检查许可证是否有效，以及 Enable Purolator 是否已开启。检查 Geo zone（或 Ignore shipping zones 已开启且该国家被允许）、重量限制和 Minimum order amount。如果 Purolator 未返回运费，则只有在存在国家价格、* 行或 Fallback price 时才会显示该配送方式。检查商品的 Requires Shipping 是否设为 Yes。
实时运费未显示：查看扩展页面上的 Log 字段。API 错误始终会显示在那里。开启 Debug log 并重新加载结账页面以查看详细信息。使用 API 密钥时，地址必须有有效的邮政编码（加拿大）或 ZIP 码（美国）。另请检查 General 部分中的警告。
日志中出现 HTTP 401：API 密钥或密码与所选环境不匹配。开发密钥仅在开启 Development environment 时有效，正式密钥仅在关闭时有效。
运费与 Purolator 网站不一致：Quick Estimate 使用您结算账户的运费，并按整磅向上取整的总重量计算，不包含体积重量。对于加拿大地址，总价包含销售税；如果您设置了 Tax class，请使用 Canadian sales taxes。价格会使用您的 CAD → (store currency) rate 进行换算。
保存后某个值消失了：请阅读 Save 后显示的消息。该值不是 0 或更大的数字，因此未被保存。请以普通数字的形式重新输入。
修改后运费看起来过时：在扩展页面点击 Save。这会清除缓存的 Purolator 运费。
页面显示“Warning: You do not have permission to modify VibeFox Purolator!”：您的管理员用户组可能只能查看设置。请在 System > Users > User Groups 中为该组授予 extension/shipping/vfd_purolator（OpenCart 3）或 extension/vfd_purolator/shipping/vfd_purolator（OpenCart 4）的修改权限。
面向开发人员：可以通过设置 vfd_prlr_api_url（用于测试）替换 Purolator API 地址；该设置在设置页面中没有对应字段。
卸载
进入 Extensions > Extensions，选择类型 Shipping，然后点击 VibeFox Purolator 旁边的 Uninstall（红色 − 按钮）。此扩展的许可证密钥和许可证状态总会被删除。OpenCart 总会重置 Enable Purolator、Sort order、Tax class 和 Geo zone。缓存的运费总会被删除。如果 Remove data on uninstall 已开启，Purolator 设置和调试日志也会被删除。如果已关闭，其他设置会保留，并在您重新安装扩展时再次使用。现有订单会保留其配送方式和费用；订单中已保存的 Purolator 服务始终保留。
在 OpenCart 4 上，如需同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox Purolator 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）删除已上传的安装包。
Purolator 是其各自所有者的商标。本扩展与 Purolator 无关联，也未获得 Purolator 的认可。