VibeFox Purolator for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块不会安装到较旧的 PHP 版本上。不需要 PHP SOAP 扩展。
Purolator E-Ship Web Services（仅用于实时运费）：在 Purolator 网站的 Purolator E-Ship Resource Centre 注册 E-Ship Web Services。Purolator 为开发环境和生产环境分别提供密钥和密码。您还需要 Purolator 结算账户号码，以及发货所在的加拿大邮政编码。如果只使用固定价格，则无需 API 密钥。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox Purolator，然后点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入 License key，然后点击 Activate（参见许可证密钥）。
4. 如需实时运费，请填写 Purolator API (live rates) 部分。测试时，使用开发密钥开启 Development environment。如果需要固定价格或备用价格，请填写 Country prices 或 Fallback price（参见配置）。点击 Save。
安装时，模块会创建 Purolator 承运商，配送时间文本为 Purolator courier。该承运商分配给所有区域和所有顾客群组。您可以在 Shipping > Carriers 中更改区域、顾客群组、配送时间、徽标和尺寸限制。请勿在那里设置价格：价格始终由模块提供。
配置
所有设置都在模块页面中：Modules > Module Manager > VibeFox Purolator > Configure。每个部分都有各自的 Save 按钮，保存时会保存整个页面。每次保存也会清除缓存的 Purolator 运费。
如果实时运费无法使用已保存的值正常工作（缺少密钥、密码或结算账户，没有加拿大发货邮政编码，没有 CAD 汇率），或者既没有 API 凭据也没有固定价格，设置上方会出现警告。如果店铺的重量单位不是模块可识别的单位（kg、g、lb、oz 等），也会出现警告。此时商品重量按千克计算。请在 International > Localization（Local units）中设置重量单位。
未填写 0 或更大数字的数字字段不会被保存。警告会指出字段名称和值。该字段将保持为空，或对于重量字段则使用其默认值。Country prices 中的错误值会被保存为 0，警告会列出国家和列。如果 Min cart weight 大于 Max cart weight，则不会保存任何内容，并显示错误。
常规
Enable Purolator：开启或关闭承运商。这与 Shipping > Carriers 中的承运商状态使用同一开关。
Method title：在购物车和结账时显示的承运商名称。默认值：Purolator。必填，最多 64 个字符。
Tax：承运商的税务规则，或 No tax。它决定店铺是否在运费上另外加税。对于加拿大地址，Purolator 总价已包含 GST/HST/PST/QST。见下文 Canadian sales taxes。
Purolator API（实时运费）
填写 API 密钥、密码和结算账户后，价格来自 Purolator E-Ship Estimating 网络服务。如果 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.purolator.com）和开发密钥。价格为测试数据。在正式店铺中请关闭。
Ship-from postal code：包裹发出的加拿大邮政编码，例如 L4W 5M8。
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 总价包含这些税费。当承运商在 Tax 中设有税务规则时开启此选项，以免重复征税。
CAD → (shop currency) rate：Purolator 价格以 CAD 计价。如果店铺默认货币不是 CAD，请输入 1 CAD 相当于多少单位您的货币，例如 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 × quantity) 按购物车中的商品数量相乘。此设置仅适用于固定价格。实时运费始终按整个包裹计算。
条件
Min cart weight：以 kg 为单位，购物车重量低于此值时隐藏承运商。0 表示不限制。
Max cart weight：以 kg 为单位，购物车重量高于此值时隐藏承运商。默认值：30。0 表示不限制。
Minimum order amount：仅当购物车小计（折扣后、税前）达到此金额时才显示承运商。留空则始终显示。
Free shipping from：购物车小计（折扣后、税前）达到此金额时免运费。此时不会向 Purolator 发送请求。留空则从不提供免运费。
在这些条件中，购物车重量将没有重量的商品计为 0。
无配送区域时的可用性
通常，承运商会在 Shipping > Carriers 中分配给它的区域内提供。
Ignore shipping zones：无论匹配哪个区域，都为下列国家提供 Purolator。保存时，承运商会添加到所有区域，之后创建的区域也会自动添加。关闭此选项后，这些区域会被再次移除。
Countries：此模式下的目标国家。留空则使用店铺所有已启用的国家。此字段仅在 Ignore shipping zones 开启时使用。
高级
Debug log：将运费计算记录写入模块文件夹中的 logs/vfd_prlr_debug.log.php。该文件无法通过网页打开。即使调试日志关闭，API 错误也始终会记录。API 密钥、结算账户和顾客邮政编码不会被记录。完成后请关闭日志。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Remove data on uninstall：开启时，卸载模块会删除设置、承运商、缓存的运费和日志。关闭时，所有内容都会保留，以便重新安装。
结账时的工作方式
在配送步骤，PrestaShop 向模块请求 Purolator 价格。只计算实体商品：虚拟商品不增加重量，也不计入订单金额。在顾客输入地址之前，系统会按店铺用于估价的国家估算价格。模块首先检查条件：允许的国家（使用 Ignore shipping zones 时）、购物车重量和最低订单金额。如果适用免运费，价格为 0，且不向 Purolator 发送请求。然后模块查找价格：先是 Purolator 实时运费，然后是国家价格表，最后是备用价格。如果没有价格，则隐藏承运商。
有 API 凭据时，模块会向 Purolator 发送 Quick Estimate 请求：包括您的结算账户、发货邮政编码、顾客的城市、省份或州、国家和邮政编码，以及以整磅计的购物车总重量。加拿大需要有效的邮政编码，美国需要有效的 ZIP 代码；其他国家按输入的邮政编码发送。不发送尺寸（体积重量）。Purolator 会根据顾客的语言以法语或英语回复。Purolator 返回所有服务的价格；模块取您所选服务或最便宜的服务，若已设置则去除加拿大销售税，并将价格从 CAD 换算。价格以店铺默认货币计算，然后以顾客购物车的货币显示。
每个响应缓存 1 小时。失败的请求缓存 10 分钟，以免 Purolator 中断时每次结账刷新都变慢。API 超时时间为 10 秒。
如果 Purolator 未返回运费（API 不可用、凭据或邮政编码错误、服务不可用、没有 CAD 汇率），顾客不会看到错误。使用固定价格；如果没有固定价格，则隐藏承运商。原因会写入日志。
如果承运商在已有订单后于 Shipping > Carriers 中被编辑，PrestaShop 会将其保存为新的承运商版本。模块会自动跟随新版本。
模块只计算运费。它不会创建 Purolator 运单、打印面单、预约取件、处理退货或追踪包裹。它不使用 Full Estimate（尺寸、多件、签收或危险品等选项），不显示配送日期，不将多个服务显示为独立承运商，也不自动获取汇率。
订单
使用 Purolator 实时运费下单时，服务会与订单一同保存。之后对购物车的重新计算不会更改它。在后台的订单页面（Orders > Orders，打开订单）中，Purolator 区块会显示 Purolator service（名称和代码）以及 Live rate (excl. tax)。使用固定价格或免运费下的订单没有此区块。
许可证密钥
本模块使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Purolator 位于 Modules > Module Manager > VibeFox Purolator > Configure 页面顶部、设置上方。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证的有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入另一个密钥）和 Remove key（从本店铺移除密钥）。其下方是一行 Product: presta-shipping-purolator，以及打开您 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 账户中释放该名额。
没有有效密钥时，Purolator 承运商不会在结账时显示给顾客，也不会请求或计算任何运费。PrestaShop 前台无法得知您已登录后台，因此承运商对您也会隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 中的 Alerts 选项卡会显示提醒。现有订单不受影响。
许可证过期后，模块仍会继续工作，但更新和支持需要续期。您在后台工作时会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块始终会删除许可证密钥和许可证状态。
故障排除
Purolator 未出现在结账页面：检查许可证是否有效，以及 Enable Purolator 是否已开启。在 Shipping > Carriers 中，检查承运商是否覆盖顾客所在国家的区域和顾客群组（或 Ignore shipping zones 已开启且该国家已允许）。检查重量限制和 Minimum order amount。如果 Purolator 未返回运费，则只有在存在国家价格、* 行或 Fallback price 时才会显示承运商。也可以在商品页面中将商品限制为特定承运商。
实时运费未出现：查看模块页面上的 Log 字段。API 错误始终显示在此处。开启 Debug log 并重新加载结账页面以查看详细信息。使用 API 密钥时，地址必须有有效的邮政编码（加拿大）或 ZIP 代码（美国）。同时检查设置上方的警告。
日志中出现 HTTP 401：API 密钥或密码与所选环境不匹配。开发密钥仅在 Development environment 开启时有效，生产密钥仅在其关闭时有效。
运费与 Purolator 网站不一致：Quick Estimate 使用您结算账户的费率，并将总重量向上取整到整磅，不含体积重量。对于加拿大地址，总价包含销售税；如果承运商设有税务规则，请使用 Canadian sales taxes。价格会按您的 CAD → (shop currency) rate 换算。
保存后某个值消失了：请阅读点击 Save 后显示的警告。该值不是 0 或更大的数字，因此未被保存。请以普通数字的形式重新输入。
修改后运费看起来过时：在模块页面点击 Save。这会清除缓存的 Purolator 运费。
页面提示未找到 Purolator 承运商：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块以重新创建它。
卸载
进入 Modules > Module Manager，打开 VibeFox Purolator 旁边的菜单，选择 Uninstall。许可证密钥和许可证状态始终会被删除。缓存的运费总会被删除。如果 Remove data on uninstall 已开启，承运商将被删除（订单保留历史记录），并删除设置、订单中保存的 Purolator 服务以及日志。如果已关闭，承运商仅会被禁用，所有设置都会保留；已下的订单保留其 Purolator 服务。重新安装模块或执行 Reset，会使承运商恢复到之前的状态。
Purolator 是其各自所有者的商标。本模块与 Purolator 无关联，也未获得 Purolator 的认可。