VibeFox Canada Post for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝安装在更早的 PHP 版本上。
Canada Post Developer Program（仅用于实时运费）：实时运费使用 Canada Post Rating API。请在 Canada Post 网站上加入 Canada Post Developer Program，并复制您的 API 密钥和客户编号。API 密钥的格式为 username:password，Canada Post 为开发（沙盒）环境和生产环境分别提供密钥。您还需要填写发货所在的加拿大邮政编码。如果只使用固定价格，则无需 API 密钥。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或之后在模块列表中找到 VibeFox Canada Post，然后点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，将 VibeFox 许可证密钥输入 License key 字段，然后点击 Activate（见“许可证密钥”）。
4. 如需实时运费，请输入 API 用户名和密码、您的客户编号和发货邮政编码。如果店铺默认货币不是 CAD，请输入 CAD 汇率。如需固定价格或备用价格，请填写 Country prices（见“配置”）。点击 Save。
安装时，模块会创建 Canada Post 承运商，运输时效文本为 Canada Post parcel delivery。该承运商会分配给所有区域和所有客户组。您可以在 Shipping > Carriers 中更改区域、客户组、运输时效、Logo 和尺寸限制。请不要在那里设置价格：价格始终来自模块。
配置
所有设置都在模块页面中：Modules > Module Manager > VibeFox Canada Post > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。每次保存也会清除缓存的 Canada Post 运费。保存需要模块的配置权限。
如果某个值有误，页面会显示错误，且不会保存任何内容：数字字段或 Country prices 中不是 0 或更大数字的价格（例如 -1 或 12abc）、CAD 汇率为 0、Min cart weight (kg) 大于 Max cart weight (kg)，或 Method title 超过 64 个字符。如果您店铺的重量或尺寸单位是模块不认识的单位，页面会警告重量将按 kg 读取（尺寸按 cm）。请在 International > Localization 的 Local units 部分中设置 kg、g、lb 或 oz（cm、mm、m 或 in）。
保存后，如果设置无法按预期工作，页面会显示警告：API 用户名和 API 密码只填写了一项，发货邮政编码不是加拿大邮政编码（格式为 A1A 1A1），店铺使用其他货币但缺少 CAD 汇率，或者既没有 API 凭据也没有固定价格。警告还会说明在此期间会发生什么：使用各国的固定价格，或者当 Country prices 表格为空时，结账时隐藏承运商。
常规
Enable Canada Post：开启或关闭承运商。这与 Shipping > Carriers 中承运商的状态是同一个开关。
Method title：结账时显示给顾客的承运商名称。默认值为 Canada Post，即使该字段留空也是如此。最多 64 个字符，且不能包含 PrestaShop 不允许用于承运商名称的字符。
Tax：PrestaShop 在运费上添加的税务规则，或 No tax（不征税）。
Canada Post API（实时运费）
填写 API 用户名和密码后，价格来自 Canada Post Rating API。如果 API 未返回运费（API 故障、邮政编码错误、服务不可用），则使用 Country prices 中的固定价格；如果没有固定价格，则隐藏承运商。本部分链接到 Canada Post Developer Program，您可以在那里找到 API 密钥和客户编号。错误详情会写入日志，绝不会显示给顾客。
API username：API 密钥中冒号之前的部分。开发密钥用于 Sandbox，生产密钥用于正式店铺。
API password：API 密钥中冒号之后的部分。保存后，该字段保持为空，并显示 A password is saved. Leave empty to keep it; clear the username and save to remove both. 只有在需要更改时才输入新值。密码将按输入原样保存，且绝不会写入日志。
Customer number：填写客户编号后，Canada Post 将返回您账户的商业（折扣）运费。留空则返回零售（柜台）运费。空格会被删除。
Contract number：可选，适用于签约客户。仅与客户编号一起使用。
Sandbox：使用 Canada Post 开发环境，用开发 API 密钥进行测试。价格为测试数据。在正式店铺上请关闭。
Ship-from postal code：包裹寄出的加拿大邮政编码，例如 K1A 0B1。实时运费需要此项。
Service in Canada：加拿大地址的服务：Cheapest available、Regular Parcel（DOM.RP，默认）、Expedited Parcel（DOM.EP）、Xpresspost（DOM.XP）或 Priority（DOM.PC）。
Service to the USA：Cheapest available（默认）、Expedited Parcel USA（USA.EP）、Tracked Packet USA（USA.TP）、Small Packet USA Air（USA.SP.AIR）、Xpresspost USA（USA.XP）或 Priority Worldwide parcel USA（USA.PW.PARCEL）。
International service：Cheapest available（默认）、International Parcel Surface（INT.IP.SURF）、International Parcel Air（INT.IP.AIR）、Tracked Packet International（INT.TP）、Small Packet International Surface（INT.SP.SURF）、Small Packet International Air（INT.SP.AIR）、Xpresspost International（INT.XP）或 Priority Worldwide parcel International（INT.PW.PARCEL）。
如果所选服务不适用于该地址或包裹，则使用最便宜的可用服务。
Use Canada Post prices without GST/HST/PST：对于加拿大地址，Canada Post 的价格包含这些税费。当 PrestaShop 自身对运费征税（即上方的 Tax）时请开启，以免重复征税。
CAD to … rate：字段名称显示您店铺的默认货币，例如 CAD to USD rate。Canada Post 价格以 CAD 计价。如果您的默认货币不是 CAD，请输入 1 加元等于多少单位您的货币，例如 0.68。未填写时不使用实时运费。如果您的默认货币是 CAD，请留空。汇率必须大于 0。小数点和逗号都可以作为小数分隔符。
Default product weight (kg)：为没有重量的每个商品发送给 Canada Post 的重量。默认值：0.5。商品重量（以您店铺的重量单位计）和尺寸会被换算，购物车按一个包裹计算运费。
固定价格（在没有 API 凭据时使用，也用作 API 未返回运费时的备用价格）
Country prices：一个国家表格，包含 Base 价格，以及按购物车重量划分的价格（以您店铺的默认货币计，不含税）：XS 最高 1 kg，S 1–2 kg，M 2–3 kg，L 3–5 kg，XL 超过 5 kg。尺寸价格为空或为零时，使用 Base 价格。点击 Add country 添加一行，点击叉号删除一行。* Default (all other countries) 行为所有没有自有行的国家设置价格。没有行（且没有 *）的国家不设置固定价格。基础价格为 0 表示该国家免运费。没有任何价格的行不会被保存。
Fixed price per：Order 按订单收取一次价格。Item (price x quantity) 则按购物车中的商品数量相乘。这仅适用于固定价格。实时运费始终按整个包裹计算。
条件
Min cart weight (kg)：购物车重量低于此值时隐藏承运商。0 表示无限制。
Max cart weight (kg)：购物车重量高于此值时隐藏承运商。默认值：25，即使该字段为空也是如此。0 表示无限制。Canada Post 包裹最重可达 30 kg。该值不能小于 Min cart weight (kg)。
Minimum order amount：仅当购物车小计（扣除折扣后的商品金额，不含税）达到此金额时才显示承运商。留空则始终显示。
Free shipping：开启后，达到下方金额即可享受免费配送。
Free shipping from：购物车小计达到此金额即免运费。在这种情况下不会向 API 发送请求。仅在 Free shipping 开启时使用。
不使用配送区域时的可用性
通常，承运商只会显示在 Shipping > Carriers 中分配给它的区域内。
Ignore shipping zones：无论匹配哪个区域，都为下方的国家提供承运商。保存时，承运商会被添加到所有区域，以及您之后创建的区域。关闭该选项并保存后，模块添加的区域会被再次移除，承运商保留其自身的区域。
Countries：该模式下的目的地国家。按住 Ctrl（Cmd）可多选。留空则允许所有启用的国家。仅在 Ignore shipping zones 开启时使用此字段。
高级
Debug log：将运费计算记录到 var/logs/vfd_canada_post.log.php。该文件无法通过网页打开，并在达到 5 MB 时轮换。即使此选项关闭，API 错误也始终会被记录。API 密钥、客户编号和顾客邮政编码不会被记录。
Remove data on uninstall：开启后，卸载模块会删除设置、已保存的订单服务、缓存的运费和日志。卸载时，承运商始终会从结账中移除。订单永远不会被改动。
Log：设置下方的面板会显示文件名和最新的 50 条记录。点击 Clear log 可删除日志。
结账时的工作方式
在配送步骤，PrestaShop 会向模块请求 Canada Post 价格。只计算实物商品：虚拟商品不增加重量，也不计入订单金额。模块首先检查条件：允许的国家（配合 Ignore shipping zones）、购物车重量和最低订单金额。如果适用免运费，价格为 0，且不会向 Canada Post 发送任何请求。
在有 API 凭据的情况下，模块会向 Canada Post 发送发货邮政编码、目的地、包裹重量，以及当每个商品都有尺寸时的估算包裹尺寸。对于加拿大，目的地为邮政编码；对于美国，为 ZIP 码；对于其他所有国家，仅为国家。只有当加拿大或美国地址具有有效的邮政编码或 ZIP 码时，才会请求实时运费。Canada Post 会返回该包裹的所有服务。模块会选择目的地组中所选的服务，或最便宜的服务；如果开启了 Use Canada Post prices without GST/HST/PST，则去除加拿大销售税（GST/HST/PST）；然后按您的汇率把 CAD 价格换算过来。价格先以您店铺的默认货币计算，然后再以顾客购物车的货币显示。
每个响应缓存 1 小时，因此相同的购物车和地址不会触发新的请求。失败的请求缓存 10 分钟，因此 Canada Post 的故障不会拖慢每次结账页面刷新。API 超时时间为 10 秒。超过 30 kg 的包裹不会发送给 API。
如果 API 未返回运费，则使用固定价格；如果没有固定价格，则隐藏承运商。顾客永远看不到 API 错误详情，它们会被写入日志。
如果您在 Shipping > Carriers 中编辑承运商，PrestaShop 会将其保存为新的承运商版本。模块会自动跟随新版本。
模块只计算运费。它不会创建发货单、打印面单、生成交接清单或退货单，也不会追踪包裹。顾客无法选择邮局或取件点。它只显示一种 Canada Post 运费，不含配送日期、保险或签收选项。购物车始终按一个包裹计算，货币汇率也不会自动更新。
订单
当订单使用 Canada Post 承运商下单时，模块会保存其价格的计算方式。在后台订单页面（Orders > Orders，打开某个订单）中，Canada Post 区块会显示：
Canada Post service：实时运费的服务名称和代码，例如 Regular Parcel（DOM.RP）。
Price source：Live rate (Canada Post Rating API)、Fixed price 或 Free shipping。
许可证密钥
本模块需要 vibefox.net 提供的 VibeFox 许可证密钥。许可证区块 License — VibeFox Canada Post 是 Modules > Module Manager > VibeFox Canada Post > Configure 页面中的第一个区块，位于设置上方。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），并提供以下按钮：Check now 用于重新检查状态，Change key 用于输入其他密钥，Remove key 用于从此店铺中移除密钥。它们下方是 Product: presta-shipping-canada-post 一行，以及打开您 vibefox.net 账户的链接 Manage licenses and domains in your account。只有拥有该模块配置权限的员工才能更改密钥。该区块的文字跟随后台语言显示（包含英语和俄语）。
如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或 License expired on 加上日期。店铺地址更改后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，模块将继续使用最后已知的状态运行。
一个密钥只能用于一个域名：即主店铺的域名，多店铺设置中也是如此。从店铺中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 Canada Post 承运商，也不会计算任何运费。PrestaShop 前台无法得知您已登录后台，因此承运商对您也会隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 的 Alerts 选项卡中会出现提醒。现有订单不受影响。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。在您使用后台期间，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时没有显示 Canada Post：请检查许可证是否有效，以及 Enable Canada Post 是否开启。在 Shipping > Carriers 中，请检查承运商是否覆盖顾客所在国家的区域和顾客所在的客户组（或者 Ignore shipping zones 已开启且该国家被允许）。请检查重量限制和 Minimum order amount。必须有运费：使用 API 凭据时，地址需要有效的邮政编码（加拿大）或 ZIP 码（美国）；否则，必须存在该国家或 * 的固定价格。此外，商品页面上还可能将商品限制为特定承运商。
实时运费未显示：请开启 Debug log，刷新结账页面，并查看模块页面上的 Log 面板。它会显示原因：缺少 API 用户名或密码、发货或目的地邮政编码无效、缺少 CAD 汇率、包裹超过 30 kg，或 Canada Post 的错误信息。在此期间，如果存在固定价格，顾客将获得该固定价格。
运费与 Canada Post 网站不同：填写客户编号时，您将获得账户的商业（折扣）运费；未填写时，则为零售（柜台）运费。对于加拿大地址，Canada Post 的价格包含 GST/HST/PST。价格会按您的 CAD 汇率换算。
运费被重复征税：请开启 Use Canada Post prices without GST/HST/PST，或将 Tax 设置为 No tax。
在正式店铺上测试价格：请关闭 Sandbox，并使用生产 API 密钥。
更改后运费似乎过时：请在模块页面上点击 Save。这会清除缓存的 Canada Post 运费。
页面提示 Canada Post 承运商缺失：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块，以重新创建它。
您没有配置此模块的权限：您的员工档案可以打开模块页面，但无法保存。请让管理员为您的档案授予该模块的配置权限。
卸载
进入 Modules > Module Manager，打开 VibeFox Canada Post 旁边的菜单，然后选择 Uninstall。许可证密钥和许可证状态总会被删除。承运商总会从结账中移除（订单会保留其承运商和历史记录）。如果 Remove data on uninstall 开启，则会删除设置、已保存的订单服务、缓存的运费和日志。如果关闭，则只删除缓存的运费，所有设置都会保留。再次安装模块（或点击 Reset）会以之前的状态恢复之前的承运商：您曾停用的承运商将保持停用。
Canada Post 是其各自所有者的商标。本模块与 Canada Post 无关联，也未获得 Canada Post 的认可。