VibeFox Canada Post for OpenCart — 帮助
系统要求
OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP：8.0 或更高版本。
Canada Post Developer Program（仅用于实时运费）：实时运费使用 Canada Post Rating API。请在 Canada Post 网站上加入 Canada Post Developer Program，并复制您的 API 密钥和客户编号。API 密钥格式为 username:password，Canada Post 为开发（沙盒）环境和正式环境分别提供不同的密钥。您还需要寄出包裹所在地的加拿大邮政编码。如果只使用固定价格，则不需要 API 密钥。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
下载文件是一个 zip 压缩包，内含适用于两个 OpenCart 版本的安装包。请解压到您的电脑上。其中包含 README.txt、OpenCart 3 安装包 vfd_canada_post-oc3-(version).ocmod.zip 以及 OpenCart 4 安装包 vfd_canada_post.ocmod.zip。请只安装与您的 OpenCart 版本对应的安装包。两个版本的许可证密钥相同。
OpenCart 3
1. 在后台进入 Extensions > Installer，点击 Upload，选择文件 vfd_canada_post-oc3-(version).ocmod.zip。本扩展不添加 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用 Installer，而是将安装包中 upload 文件夹的内容复制到商店的根目录中。
2. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Canada Post，点击 Install（绿色的 + 按钮）。
3. 点击 Edit（铅笔按钮）打开设置页面。
4. 在 Edit 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入到 License key 字段，然后点击 Activate（参见 License key）。
5. 如需实时运费，请输入 API 用户名和密码、您的客户编号以及发货邮政编码。如果商店的默认货币不是 CAD，请输入 CAD 汇率。如果需要固定价格或备用价格，请填写 Country prices（参见配置）。开启 Enable Canada Post 并点击 Save。
OpenCart 4
1. 在后台进入 Extensions > Installer，点击 Upload，选择文件 vfd_canada_post.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名读取扩展代码，重命名后的安装包将无法使用。
2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。
3. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Canada Post，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按照 OpenCart 3 的第 4 步和第 5 步输入许可证密钥和设置。两个版本的设置页面及其字段相同。
安装后，在您开启 Enable Canada Post 并保存之前，该配送方式处于关闭状态。如果您在卸载后重新安装扩展，之前保留的设置将再次生效。
配置
所有设置都位于扩展页面：Extensions > Extensions > Shipping > VibeFox Canada Post > Edit。各部分列在左侧。点击一个 Save 按钮即可保存整个页面，无需重新加载。每次保存也会清除已缓存的 Canada Post 费率。只有拥有本扩展修改权限的管理员用户才能保存设置。
当某个值有误时，页面会显示错误且不保存任何内容：数字字段或 Country prices 中的价格不是 0 或更大的数字（例如 -1 或 12abc），CAD 汇率为 0，Min cart weight (kg) 大于 Max cart weight (kg)，Method title 超过 64 个字符或包含字符 < > ; = # { }，Sort order 不是整数，或者税类或地理区域未知。如果商店没有单位为 "kg" 的重量类别，或没有单位为 "cm" 的长度类别，页面会提示：重量和尺寸将按其类别的单位名称（kg、g、lb、oz；cm、mm、m、in）换算，其他单位则按 kg 或 cm 读取。
保存后，如果设置无法按预期工作，页面会显示警告：API 用户名和密码只填写了一个，发货邮政编码不是加拿大邮政编码（格式 A1A 1A1），商店使用其他货币但缺少 CAD 汇率，或者既没有 API 凭据也没有固定价格。警告还会说明在此期间会发生什么：使用按国家的固定价格，或者当 Country prices 表格为空时，结账时隐藏该方式。
常规
这些设置适用于所有地理区域。价格始终来自本扩展：Canada Post 实时运费或按国家的固定价格。
Enable Canada Post：在结账时显示或隐藏 Canada Post。默认：关闭。
Method title：结账时向顾客显示的配送方式名称。默认：Canada Post，即使该字段留空也如此。最多 64 个字符。
Tax class：OpenCart 添加到运费上的税类，或 No tax（免税）。
Sort order：Canada Post 在结账时配送方式中的排列位置。
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 API 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：加拿大地址的服务：最便宜的可用服务、Regular Parcel（DOM.RP，默认）、Expedited Parcel（DOM.EP）、Xpresspost（DOM.XP）或 Priority（DOM.PC）。
Service to the USA：最便宜的可用服务（默认）、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：最便宜的可用服务（默认）、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 价格包含这些税费。当 OpenCart 自行对运费征税（即上方的 Tax class）时开启此项，以免重复征税。
CAD to … rate：字段名称显示您商店的默认货币，例如 CAD to USD rate。Canada Post 价格以 CAD 计价。如果默认货币不是 CAD，请输入 1 CAD 等于多少单位您的货币，例如 0.68。未填写时不会使用实时运费。如果默认货币为 CAD，请留空。汇率必须大于 0。
Default product weight (kg)：对于没有重量的每件商品，发送给 Canada Post 的重量。默认：0.5。商品的重量和尺寸根据商品的重量和长度类别换算，购物车按一个包裹计算（最多 30 kg）。
固定价格（在没有 API 凭据时使用，并在 API 未返回运费时作为备用）
Country prices：国家表格，包含 Base 基础价格，以及按购物车重量划分的价格（以商店默认货币计，不含税）：XS 至 1 kg，S 1–2 kg，M 2–3 kg，L 3–5 kg，XL 超过 5 kg。尺寸价格为空或为 0 时使用 Base 价格。点击 Add country 添加一行。* All other countries 行为所有没有自己行的国家设置价格。没有行（且没有 *）的国家没有固定价格。基础价格为 0 表示该国家免运费。
Fixed price per：Order（默认）只收取一次价格。Item (price × quantity) 则按购物车中商品数量相乘。这仅适用于固定价格。实时运费始终按整个包裹计算。
条件
Min cart weight (kg)：购物车重量低于此值时隐藏该方式。0 表示无限制（默认）。
Max cart weight (kg)：购物车重量高于此值时隐藏该方式。默认：25，即使该字段为空也如此。0 表示无限制。Canada Post 包裹最重可达 30 kg。
Minimum order amount：仅当需要配送的商品小计（使用优惠券之后，不含税）达到此金额时才显示该方式。留空则始终显示。
Free shipping：开启后，超过下方金额即免运费。
Free shipping from：需要配送的商品小计（使用优惠券之后，不含税）达到此金额时免运费。在这种情况下不会向 API 发送请求。仅在 Free shipping 开启时使用。
Geo zone：仅向此地理区域内的地址提供 Canada Post。All zones（默认）表示所有地区。当 Ignore shipping zones 开启时不使用。地理区域在 System > Localisation > Geo Zones 中管理。
不使用配送区域时的可用性
通常，该方式会在 Conditions 中选择的地理区域内提供。
Ignore shipping zones：无论地理区域如何，都为下方列出的国家提供该方式。
Countries：该模式的目的地国家。留空则允许商店中所有已启用的国家。仅在 Ignore shipping zones 开启时使用。
高级
Debug log：将运费计算记录到 storage/logs/vfd_canada_post.log.php。该文件无法通过网页读取。当文件达到 5 MB 时，它会被移动到 vfd_canada_post.old.log.php，并开始新的日志。即使此选项关闭，API 错误也始终会被记录。API 密钥、客户编号和顾客邮政编码不会被记录。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Remove data on uninstall：开启后，卸载扩展会删除设置、已保存的订单服务、缓存的运费和日志。关闭（默认）时，它们会保留，以便重新安装。订单永远不会被修改。
导入 / 导出
Export：点击 Download JSON，将设置保存为 JSON 文件。API 密码不会被导出。
Import：粘贴之前导出的 JSON，并点击 Import 以恢复设置，例如在另一家店铺中。这些值会像正常保存时一样进行检查。已保存的 API 密码在 API 用户名保持填写的情况下会被保留。
结账时的工作方式
当 OpenCart 显示配送方式时，它会向扩展请求 Canada Post 价格。如果设置了 Geo zone（且 Ignore shipping zones 关闭），而地址在该区域之外，则不会提供 Canada Post。只有 Requires Shipping 设为 Yes 的商品才会计算在内：其他商品不增加重量，也不计入订单金额。扩展首先检查条件：允许的国家（在 Ignore shipping zones 下）、购物车重量和最低订单金额。订单金额是需要配送的商品的价格，在扣除优惠券折扣之后、税费之前。礼品卡、奖励积分和商店余额不计入在内。如果适用免运费，价格为 0，并且不会向 Canada Post 发送请求。
在使用 API 凭据的情况下，扩展会向 Canada Post 发送发货邮政编码、目的地、包裹重量，以及在每件商品都有尺寸时的估计包裹尺寸。对于加拿大，目的地是邮政编码；对于美国，是 ZIP 码；对于所有其他国家，仅为国家。只有当加拿大或美国地址具有有效的邮政编码或 ZIP 码时，才会请求实时运费。Canada Post 会返回该包裹的所有服务。扩展会选取目的地组中所选的服务或最便宜的服务，如果开启了 Use Canada Post prices without GST/HST/PST，则去除加拿大销售税，并使用您的汇率将 CAD 价格换算。价格以您的默认货币计算，按其小数位数取整，并以顾客的货币显示，并含有所选 Tax class 的税费。
每个响应缓存 1 小时，因此相同的购物车和地址不会触发新的请求。失败的请求缓存 10 分钟，因此 Canada Post 故障不会减慢每次结账页面刷新。API 超时时间为 10 秒。超过 30 kg 的包裹不会发送到 API。
如果 API 未返回运费，则使用固定价格；如果没有固定价格，则隐藏该方式。顾客永远看不到 API 错误详情；这些错误会记录到日志中。
扩展仅计算运费。它不创建运单、不打印面单、不创建清单或退货，也不跟踪包裹。顾客无法选择邮局或取件点。它仅显示一个 Canada Post 运费，不包括配送日期、保险或签收选项。购物车始终按一个包裹计算，并且汇率不会自动更新。
在 OpenCart 4 中，顾客点击结账页面配送方式区块中的 Choose，并在 Shipping method options 窗口中选择 Canada Post，例如 Canada Post - $12.50。该方式的工作方式与 OpenCart 3 相同。
订单
当顾客使用 Canada Post 下单时，扩展会保存其价格的计算方式。在后台订单页面（Sales > Orders，打开一个订单）中，Canada Post 区块会显示：
Canada Post service：实时运费的服务名称和代码，例如 Regular Parcel（DOM.RP）。
Price source：Live rate (Canada Post Rating API)、Fixed price 或 Free shipping。
在 OpenCart 4 中，该区块显示在 History 上方。结账只保留一个订单：当顾客再次确认订单时，已保存的服务和价格来源会被替换；如果顾客选择了其他配送方式，它们会被删除。
服务信息不会添加到订单电子邮件或顾客的订单页面中；它们与 OpenCart 的其他配送方式一样，仅显示配送方式名称和运费。
许可证密钥
本扩展需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Canada Post 位于 Extensions > Extensions > Shipping > VibeFox Canada Post > Edit 页面的设置上方，是第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本商店移除密钥）。其下方是 Product: opencart-shipping-canada-post 一行和 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 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 Canada Post，也不会计算任何运费。以同一浏览器登录后台的管理员用户仍会在商店中看到该方式，并标有 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试扩展。在 OpenCart 4 中此预览不可用：商店无法看到后台登录状态，因此没有有效密钥时，该方式对所有人都会隐藏。打开一次 Edit 页面后，后台 Dashboard 上会出现提醒。点击 × 关闭它，可隐藏 7 天。现有订单不受影响。
许可证到期后，扩展仍会继续运行，但更新和支持需要续费。当您打开后台 Dashboard 或 Edit 页面时，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展总会删除许可证密钥和许可证状态。
故障排除
Canada Post 未出现在结账页面：请检查许可证是否有效，以及 Enable Canada Post 是否已开启。检查 Geo zone，或确认 Ignore shipping zones 已开启且该国家已允许。检查重量限制和 Minimum order amount，并确认商品的 Requires Shipping 设为 Yes。必须存在运费：使用 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 class 设为 No tax。
在正式店铺中测试价格：关闭 Sandbox 并使用正式 API 密钥。
修改后费率看起来过时：在扩展页面点击 Save。这将清除已缓存的 Canada Post 费率。
页面显示 "Warning: You do not have permission to modify VibeFox Canada Post!"：您的管理员用户组可能只能查看设置。请在 System > Users > User Groups 中为该组授予 extension/shipping/vfd_canada_post（OpenCart 3）或 extension/vfd_canada_post/shipping/vfd_canada_post（OpenCart 4）的修改权限。
面向开发人员：Canada Post API 地址可以通过设置 vfd_cp_api_url（用于测试）进行替换；设置页面上没有该项的字段。
卸载
进入 Extensions > Extensions，选择类型 Shipping，然后点击 VibeFox Canada Post 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 总会重置 Enable Canada Post、Sort order、Tax class 和 Geo zone。缓存的运费始终会被删除。如果 Remove data on uninstall 已开启，则设置、已保存的订单服务和日志也会被删除。如果关闭，其他设置将保留，并在您重新安装扩展时再次使用。现有订单保留其配送方式和费用。
在 OpenCart 4 中，如需同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox Canada Post 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。
Canada Post 是其各自所有者的商标。本扩展与 Canada Post 无关联，也未获得其认可。