VibeFox NZ Post for WooCommerce — 帮助
系统要求
WordPress：5.8 或更高版本。
WooCommerce：5.0 或更高版本，已安装并启用。未安装 WooCommerce 时插件无法启用。
PHP：8.0 或更高版本。
NZ Post API 访问权限（仅实时运费需要）：实时运费使用 NZ Post ShippingOptions API。请在 NZ Post 网站的 Developer Resource Centre 申请 API 访问权限。NZ Post 会先为测试环境（UAT）颁发 Client ID 和 Client Secret，通过其上线检查清单后再为正式环境颁发。对于新西兰境内的运费，您还需要 NZ Post 商务账户：账户号及其 auth code（或 site code）。如果您只使用固定价格，则无需 API 访问权限。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 vfd_nz_post 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置页面：WooCommerce > Settings > Shipping > VibeFox NZ Post，或在插件列表页点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 若要使用实时运费，请填写 NZ Post API (live rates) 部分。您也可以填写固定价格，它们在没有实时运费时使用，并作为备用（参见配置）。
6. 在 WooCommerce > Settings > Shipping > Shipping zones 中将 VibeFox NZ Post 添加到某个配送区域，或开启 Ignore shipping zones 并选择国家。
配置
所有设置都位于同一页面：WooCommerce > Settings > Shipping > VibeFox NZ Post。这些设置适用于所有配送区域。将该方式添加到某个区域时，区域窗口中只有一个字段：
Title (zone)：顾客在该区域看到的名称。留空则使用全局的 Method title。
每次保存设置时，缓存的 NZ Post 运费和访问令牌都会被清除。如果实时运费无法使用已保存的值（Client ID 和 Client Secret 只填了一个、没有 NZD 换算汇率、国内运费信息不完整），设置页面上方会显示警告。
General
Enable/Disable：一次性在所有区域启用或禁用该方式。
Method title：购物车和结账页面上显示的配送方式名称。配送区域可以覆盖此名称。默认值：NZ Post。
Tax status：Taxable 会将 WooCommerce 税费加到运费上，None 则不加。另请参阅下方的 API prices。
NZ Post API (实时运费)（若只使用固定价格，请将 Client ID 留空）
Environment：Production (api.nzpost.co.nz)（默认）或 Testing / UAT (api.uat.nzpost.co.nz)。请使用为您的 Client ID 颁发时所对应的环境。
Client ID：您的 NZ Post API 应用的 OAuth2 客户端 ID。
Client Secret：OAuth2 客户端密钥。它会被换取为访问令牌，该令牌会缓存至过期。
Account number：您的 NZ Post 商务（结算）账户号。新西兰境内运费必填。国际运费可选；填写后，NZ Post 将返回您的合同运费。
Auth code：用于国内运费的账户 auth code。如果您填写了 site code，则无需此项。
Site code：auth code 的替代项：您的 NZ Post 取件点代码。
Ship-from suburb：包裹发出地址所在的郊区，例如 Petone。国内运费需要此项。
Ship-from city：包裹发出的城镇或城市，例如 Lower Hutt。国内运费需要此项。
Ship-from postcode：包裹发出地的 4 位新西兰邮政编码，例如 5012。国内运费需要此项。
Services：可选的 NZ Post 服务代码，用逗号分隔，例如 CPOLP, ICOU。仅对这些服务计价。留空则使用 NZ Post 为该包裹返回的最便宜服务。
API prices：Including GST（默认）或 Excluding GST。NZ Post 国内价格包含 15% GST；国际邮费适用零税率。当 Tax status 为 Taxable 时，请选择 Excluding GST，以免重复收取 GST。
NZD → (store currency) rate：NZ Post 价格以 NZD 计。如果您的商店货币不是 NZD，请填写 1 NZD 等于多少您的货币单位，例如 0.55。不填写则不使用实时运费。同一汇率也会换算国际请求中发送的订单金额。如果商店货币就是 NZD，请留空。
实时运费的包裹
购物车会作为一个包裹发送给 NZ Post。商品的重量和尺寸会从商店单位换算为公斤和厘米。包裹取所有商品中最大的长度和宽度，高度则不断增加，直到能容纳所有商品的体积。以下数值用于没有重量或尺寸的商品。
Default product weight (kg)：用于每个没有重量的商品。默认值：0.5。
Default parcel length (cm)：购物车中没有任何商品有尺寸时使用。默认值：30。
Default parcel width (cm)：购物车中没有任何商品有尺寸时使用。默认值：20。
Default parcel height (cm)：购物车中没有任何商品有尺寸时使用。默认值：10。
固定价格（在未设置实时运费或 NZ Post 未返回运费时使用）
价格以商店货币计。
Country prices：每个目的国家一行。点击 + Add country 添加一行，点击叉号删除。选择 * Default 可设置一行覆盖所有其他国家。每行都有一个 Any weight 价格，以及可选的重量分段列：≤ 1 kg、1–2 kg、2–3 kg、3–5 kg 和 > 5 kg（购物车重量）。已填写的重量列会覆盖 Any weight；空白或为 0 的列则使用 Any weight。Any weight 价格为 0 表示该国免运费。"9.99" 和 "9,99" 均可接受。保存时，没有任何价格的行、无效的国家代码和负数价格会被删除。每个国家只保留一行。
Fallback cost：当 API 和国家价格表都没有给出价格时使用。留空则在这种情况下隐藏该方式。
Fixed price per：Order 按订单收取一次价格。Item (price × quantity) 则将价格乘以购物车中的商品数量。这仅适用于固定价格和备用运费。实时运费始终按整个包裹计算。
条件
Min cart weight (kg)：购物车重量低于此值时隐藏该方式。0 表示不设限制。
Max cart weight (kg)：购物车重量高于此值时隐藏该方式。默认值：25（NZ Post 快递包裹最重可达 25 kg）。0 表示不设限制。
Minimum order amount：仅当购物车小计达到此金额时才显示该方式。留空则始终显示。
Excluded shipping classes：购物车中包含这些 WooCommerce 配送类别中任一类别的商品时，隐藏该方式。
Free shipping from：购物车小计达到此金额后，NZ Post 配送免运费。仅当该方式有价格时适用：国家价格或备用运费（此时不会向 NZ Post 发送请求），或实时运费。留空则从不提供免运费。
计算这些条件中的购物车重量时，没有重量的商品按 0 计。
无配送区域时的可用性
Ignore shipping zones：即使该方式未添加到任何配送区域，也为下方指定的国家提供 NZ Post。
Countries：该模式下的目的国家。留空则使用您所有可配送的国家。此字段仅在开启 Ignore shipping zones 时使用。
高级
Debug log：将运费计算过程写入 WooCommerce > Status > Logs（来源 "vfd-nz-post"）。即使关闭调试日志，API 错误也始终会被记录。凭据、令牌和顾客地址不会被记录。完成后请关闭日志。
Remove data on uninstall：开启后，删除插件时将移除其设置、区域方式和缓存的运费。停用插件从不会删除任何数据。
结账时的工作原理
顾客输入配送地址时，WooCommerce 会向插件请求运费。插件先检查条件：配送国家、购物车重量、最低订单金额和排除的配送类别。然后查找价格：先是 NZ Post 实时运费，其次是国家价格表，最后是备用运费。如果没有价格，该方式会被隐藏。如果适用免运费，顾客会看到该方式且不收费。
设置了实时运费时，插件会使用您的 Client ID 和 Client Secret 获取访问令牌，并向 NZ Post 请求价格。对于新西兰的地址，插件会发送您的账户信息、发货地址、顾客的郊区、城市和邮政编码，以及包裹的重量和尺寸。WooCommerce 没有郊区字段：如果 Address line 2 中包含郊区名称，插件就使用它；否则使用城镇或城市。只有在顾客输入了城市和 4 位邮政编码后，才会请求国内运费。对于其他国家，插件会发送目的国家、包裹的重量和尺寸，以及以 NZD 计的订单金额。
使用允许的、带有价格的最便宜服务，包括附加费和强制附加服务。价格会从 NZD 换算为您的商店货币。计价的服务会以 NZ Post service 的名义随订单保存，并显示在订单页面上。每个响应缓存 1 小时。失败的请求缓存 10 分钟，以免结账页面每次刷新都等待 NZ Post。API 超时时间为 10 秒。过期的访问令牌会自动更新。
如果 NZ Post 没有返回运费（API 未设置、出错、地址不完整、服务不可用、没有 NZD 汇率），顾客不会看到错误。系统会使用国家价格表中的价格，然后是备用运费。如果没有固定价格，该方式会被隐藏。原因会写入日志。
该方式适用于经典结账以及购物车和结账区块。它兼容 WooCommerce 高性能订单存储（HPOS）。
插件只计算运费。它不会生成运单、预约取件、制作交接清单、跟踪包裹、验证地址，也不支持顾客选择取件点、邮政信箱（PO Box）或包裹储物柜（parcel locker）。购物车会作为一个包裹计价，顾客看到的是一个 NZ Post 运费，而不是服务列表。
许可证密钥
插件需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Shipping > VibeFox NZ Post 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期截止日期以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从本站移除。Manage licenses and domains in your account 链接会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥不会释放域名名额。请在您的 vibefox.net 账户中释放名额。
没有有效密钥时，NZ Post 不会在结账时向顾客显示。已登录的商店管理员仍可看到该方式，并带有标记 (unlicensed — visible to admins only)，以便您在购买密钥前完成设置和测试。插件列表页和 WooCommerce 页面上会显示提醒。现有订单不受影响。
许可证过期后，插件仍可继续运行，但更新和支持需要续费。系统会在后台自动重新检查状态。
故障排除
结账时没有显示 NZ Post：请检查许可证是否有效、Enable/Disable 是否开启、该方式是否已添加到顾客所在国家的配送区域（或已开启 Ignore shipping zones 且该国家被允许）。检查重量限制、Minimum order amount 和 Excluded shipping classes。如果 NZ Post 没有返回运费，则该方式只有在设置了国家价格或 Fallback cost 时才会显示。
实时运费不显示：打开 WooCommerce > Status > Logs，来源为 "vfd-nz-post"。API 错误始终会记录在那里。如需详细信息，请开启 Debug log。日志会显示原因：缺少 Client ID 或 Client Secret、令牌被拒绝、缺少账户或发货地址数据、顾客尚未填写城市或邮政编码、没有 NZD 汇率，或没有带价格的服务。解决问题期间，将使用固定价格。
令牌请求失败：请检查 Client ID、Client Secret 和 Environment。UAT 凭据无法用于正式环境，反之亦然。
国内运费缺失，国际运费正常：新西兰境内运费需要 Account number、Auth code 或 Site code，以及包含 4 位邮政编码的完整发货地址。顾客必须输入城市和 4 位邮政编码。开发者可以使用 vfd_nzpt_delivery_suburb 过滤器修改为配送地址发送的郊区。
我的商店不使用 NZD：请填写 NZD → (store currency) rate。固定价格始终以商店货币计。
配送时 GST 被重复收取：NZ Post 国内价格包含 15% GST。如果 Tax status 为 Taxable，请将 API prices 设为 Excluding GST。
修改后运费看起来过时：请保存设置页面。这会清除缓存的 NZ Post 运费和令牌。
许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在另一个域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now 为新域名激活密钥。如果无法连接许可证服务器，插件将按照最后已知的状态继续运行。
卸载
停用插件会保留所有数据。若要删除插件，请先停用，然后在 Plugins 页面将其删除。该插件的许可证密钥和许可证状态始终会被删除。只有在开启 Remove data on uninstall 时，设置、区域方式、缓存的运费和访问令牌才会被删除。否则它们会保留，以便日后重新安装时使用。现有订单会保留其配送明细。
NZ Post 是其各自所有者的商标。本插件与 NZ Post 无关联，也未获得 NZ Post 的认可。