VibeFox Canada Post for WooCommerce — 帮助
系统要求
WordPress：5.8 或更高版本。
WooCommerce：5.0 或更高版本，已安装并启用。没有 WooCommerce 时插件无法激活。
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 购买。一个密钥只能用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件 ZIP 文件并点击 Install Now。您也可以通过 FTP 将 vfd_canada_post 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Shipping > VibeFox Canada Post，或在插件页面中点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 如需实时运费，请填写 API 用户名和密码、客户编号以及发货邮政编码。如果店铺货币不是 CAD，请填写 CAD 汇率。如需固定价格或备用价格，请填写 Country prices（参见配置）。
6. 在 WooCommerce > Settings > Shipping > Shipping zones 中将 VibeFox Canada Post 添加到您的配送区域，或开启 Ignore shipping zones 并选择国家。
配置
所有设置都位于同一页面：WooCommerce > Settings > Shipping > VibeFox Canada Post。它们适用于所有配送区域。将该方式添加到某个区域时，区域窗口只有一个字段：
Title (zone)：此区域向顾客显示的名称。留空则使用全局的 Method title。
每次保存设置时，已缓存的 Canada Post 运费都会被清除。当设置无法正常工作时，页面还会显示错误：API 用户名和密码只填写了其中一项、发货邮政编码不是加拿大邮政编码、非 CAD 货币的店铺缺少 CAD 汇率，或者既没有 API 密钥也没有固定价格。
常规
Enable/Disable：一次性在所有区域中启用或禁用此方式。
Method title：在购物车和结账页面向顾客显示的配送方式名称。默认：Canada Post。区域可以使用自己的标题覆盖它。
Tax status：Taxable 会在运费上加收 WooCommerce 税费，None 则不加收。
Canada Post API（实时运费）
填写 API 用户名和密码后，价格来自 Canada Post Rating API。如果 API 未返回运费（API 无法访问、邮政编码错误、服务不可用），则使用 Country prices 中的固定价格；如果没有固定价格，则隐藏该方式。
API username：API 密钥中冒号之前的部分。在 Sandbox 开启时使用开发密钥，正式店铺使用正式密钥。
API password：API 密钥中冒号之后的部分。它绝不会写入日志。
Customer number：填写客户编号后，Canada Post 将返回您账户的商业（折扣）运费。留空则返回零售（柜台）运费。
Contract number：可选，供签约客户使用。仅与客户编号一起使用。
Sandbox：使用 Canada Post 开发环境，配合开发 API 密钥进行测试。价格为测试数据。在正式店铺中请关闭。
Ship-from postal code：包裹寄出的加拿大邮政编码，例如 K1A 0B1。实时运费需要此项。
Service in Canada：加拿大地址使用的服务：Cheapest available、Regular Parcel（默认）、Expedited Parcel、Xpresspost 或 Priority。
Service to the USA：Cheapest available（默认）、Expedited Parcel USA、Tracked Packet USA、Small Packet USA Air、Xpresspost USA 或 Priority Worldwide parcel USA。
International service：Cheapest available（默认）、International Parcel Surface、International Parcel Air、Tracked Packet International、Small Packet International Surface、Small Packet International Air、Xpresspost International 或 Priority Worldwide parcel International。
如果所选服务不适用于该地址或包裹，则使用可用的最便宜服务。
Canadian sales taxes：使用不含 GST/HST/PST 的 Canada Post 价格。对于加拿大地址，Canada Post 价格包含这些税费。当 WooCommerce 自行对运费征税（Tax status = Taxable）时请开启此项，以免重复征税。
CAD → store currency rate：字段名称会显示您的店铺货币。Canada Post 价格以 CAD 计。如果店铺货币不是 CAD，请输入 1 加元等于多少您的货币单位，例如 0.68。未填写时不会使用实时运费。如果店铺货币是 CAD，请留空。小数点和逗号均可作为小数分隔符。
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 × quantity) 则按购物车中的商品数量相乘。这仅适用于固定价格。实时运费始终按整个包裹计算。
条件
Min cart weight (kg)：购物车重量低于此值时隐藏该方式。0 表示不限制。
Max cart weight (kg)：购物车重量高于此值时隐藏该方式。默认：25。0 表示不限制。Canada Post 包裹最重可达 30 kg。
Minimum order amount：仅当购物车小计达到此金额时才显示该方式。留空则始终显示。
Excluded shipping classes：如果购物车中有任何商品属于这些 WooCommerce 配送类别，则隐藏该方式。
Free shipping：开启后，达到下方金额即免运费。
Free shipping from：购物车小计达到此金额后免运费。在这种情况下不会向 API 发送请求。
不使用配送区域时的可用性
Ignore shipping zones：无论匹配哪个区域，都为下方所列国家提供该方式。
Countries：该模式下的目的地国家。留空则使用店铺可配送的所有国家。此字段仅在 Ignore shipping zones 开启时使用。
高级
Debug log：将运费计算记录到 WooCommerce > Status > Logs，来源为 vfd-canada-post。即使关闭此选项，API 错误仍会被记录。API 密钥、客户编号和顾客邮政编码不会被记录。
Remove data on uninstall：开启后，删除插件将移除其设置、区域方式和缓存的运费。停用插件不会删除任何内容。
结账时的工作方式
当顾客输入配送地址时，WooCommerce 会向插件请求运费。插件首先检查条件：购物车重量、最低订单金额和排除的配送类别。如果适用免运费，顾客将获得免费运费，且不会向 Canada Post 发送请求。
使用 API 密钥时，插件会向 Canada Post 发送发货邮政编码、目的地、包裹重量，以及在所有商品都有尺寸时的估算包裹尺寸。加拿大的目的地为邮政编码，美国为 ZIP 码，其他所有国家仅为国家。只有当加拿大或美国地址具有有效的邮政编码或 ZIP 码时，才会请求实时运费。Canada Post 会返回该包裹的所有服务；插件会选择目的地组所选的服务或最便宜的服务，若已开启 Canadian sales taxes 则移除加拿大销售税，并按您的汇率将 CAD 价格换算。服务名称随订单保存，并在管理员订单页面以 Canada Post service 显示。
每个响应缓存 1 小时，因此相同的购物车和地址不会触发新的请求。失败的请求缓存 10 分钟，因此 Canada Post 的故障不会拖慢每次结账刷新。API 超时时间为 10 秒。超过 30 kg 的包裹不会发送至 API。
如果 API 未返回运费，则使用固定价格；如果没有固定价格，则隐藏该方式。顾客永远看不到 API 错误详情；这些信息会记录到 WooCommerce 日志中。
该方式适用于经典结账以及购物车和结账区块。它兼容 WooCommerce 高性能订单存储（HPOS）。
插件仅计算运费。它不创建发货单、不打印面单、不创建装箱单或退货单，也不追踪包裹。顾客无法选择邮局或取件点。它仅显示一个 Canada Post 运费，不包括配送日期、保险或签收选项。购物车始终按一个包裹计算，货币汇率不会自动更新。
许可证密钥
本插件需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Shipping > VibeFox Canada Post 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期至何时以及您的域名。使用 Check now 重新检查状态，Change key 输入其他密钥，Remove key 将其从此站点移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥并不会释放域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，Canada Post 不会在结账时向顾客显示。已登录的店铺管理员仍可看到它，并标注 (unlicensed — visible to admins only)，以便您在购买密钥前设置和测试插件。插件页面和 WooCommerce 页面上会显示提醒。现有订单不受影响。
许可证到期后，插件仍可继续工作，但更新和支持需要续费。状态会在后台自动重新检查。
故障排除
Canada Post 未出现在结账页面：请检查许可证是否有效、Enable/Disable 是否已开启、该方式是否已添加到顾客所在国家的区域中（或已开启 Ignore shipping zones 且该国家被允许）。检查重量限制、Minimum order amount 和 Excluded shipping classes。必须有可用的运费：使用 API 密钥时，地址需要有效的邮政编码（加拿大）或 ZIP 码（美国）；否则必须为该国家或 * 设置固定价格。
实时运费未显示：开启 Debug log，重新加载结账页面，然后打开 WooCommerce > Status > Logs，来源 vfd-canada-post。日志会显示原因：缺少 API 用户名或密码、发货或目的地邮政编码无效、缺少 CAD 汇率、包裹超过 30 kg，或 Canada Post 的错误信息。在此期间，如果存在固定价格，顾客将看到该价格。
运费与 Canada Post 网站不同：填写客户编号后，您将获得账户的商业（折扣）运费；不填写则为零售（柜台）运费。对于加拿大地址，Canada Post 价格包含 GST/HST/PST。价格会按您的 CAD 汇率换算。
运费被重复征税：开启 Canadian sales taxes，或将 Tax status 设为 None。
在正式店铺中测试价格：关闭 Sandbox 并使用正式 API 密钥。
修改后运费看起来过时：保存设置页面，这会清除已缓存的 Canada Post 运费。
许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在另一个域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now 以为新域名激活密钥。如果无法连接许可证服务器，插件将继续使用最后已知的状态。
卸载
停用插件会保留所有数据。要移除插件，请先停用，然后在 Plugins 页面删除。本插件的许可证密钥和许可证状态始终会被移除。只有开启了 Remove data on uninstall 时，设置、区域方式和缓存的运费才会被移除；否则它们将保留，以便日后重新安装。订单永远不会被改动。
Canada Post 是其各自所有者的商标。本插件与 Canada Post 无关联，也未获得 Canada Post 的认可。