VibeFox NZ Post for OpenCart — 帮助
要求
OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
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 购买。一个密钥只能用于一个域名。
安装
下载文件是一个 zip 文件，内含两个 OpenCart 版本的安装包。请在您的电脑上解压。其中包含 README.txt、OpenCart 3 安装包 vfd_nz_post-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 vfd_nz_post.ocmod.zip。请只安装与您的 OpenCart 版本对应的安装包。两个版本的许可证密钥相同。
OpenCart 3
1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_nz_post-oc3-(version).ocmod.zip。本扩展不添加任何 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装器，而是将安装包中 upload 文件夹的内容复制到商店的根目录。
2. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox NZ Post，点击 Install（绿色的 + 按钮）。
3. 点击 Edit（铅笔按钮）打开设置页面。
4. 在 Edit 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入 License key 字段，然后点击 Activate（参见许可证密钥）。
5. 如需实时运费，请填写 NZ Post API (live rates) 部分。也可以选择输入固定价格，它在没有实时运费时使用，并作为备用（参见配置）。打开 Enable NZ Post，然后点击 Save。
OpenCart 4
1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_nz_post.ocmod.zip。请不要重命名该文件：OpenCart 4 会从文件名获取扩展代码，重命名后的安装包无法使用。
2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色的 + 按钮）。
3. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox NZ Post，点击 Install（绿色的 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按照 OpenCart 3 步骤 4 和 5 的方式输入许可证密钥和设置。两个版本的设置页面及其字段相同。
安装后，该配送方式处于关闭状态，直到您打开 Enable NZ Post 并保存。如果您在卸载后重新安装扩展，之前保留的 NZ Post 设置将再次使用。
配置
所有设置都位于扩展页面：Extensions > Extensions > Shipping > VibeFox NZ Post > Edit。各分区列在左侧。页面底部的一个 Save 按钮会在不重新加载页面的情况下保存整个页面。每次保存还会清除缓存的 NZ Post 运费和访问令牌。只有拥有本扩展修改权限的管理员用户才能保存设置。
当 Method title 为空、超过 64 个字符或包含 < > ; = # { }，数字字段包含文本或负数，新西兰元汇率为 0，Min cart weight (kg) 大于 Max cart weight (kg)，或 Sort order 不是整数时，不会保存任何内容，并会显示错误。当保存的值使实时运费无法工作时，设置上方会显示警告：Client ID 和 Client Secret 只填写了一个，没有新西兰元换算汇率，或国内运费的数据不完整。如果商店没有单位为 kg 的重量等级，或没有单位为 cm 的长度等级，也会显示警告：此时重量和尺寸将按其等级的单位名称换算（kg、g、lb、oz；cm、mm、m、in），其他单位则按公斤和厘米读取。
常规
这些设置适用于所有地理区域。您可以在 Availability 中将该配送方式限制到某个地理区域或某些国家。
Enable NZ Post：在结账时开启或关闭该配送方式。默认：关闭。
Method title：客户在购物车和结账时看到的配送方式名称。默认：NZ Post。必填，最多 64 个字符。
Tax class：运费的税类，或 No tax（默认；运费不征税）。如果商店对运费加收 GST，请将下方的 API prices 设为 Excluding GST，以免重复征收 GST。
Sort order：NZ Post 在结账时配送方式中的排列位置。整数。
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。
Client Secret：OAuth2 客户端密钥。它会被换取为访问令牌，该令牌会被缓存直到过期。保存后，此字段保持为空并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。
Account number：您的 NZ Post 商业（计费）账户号。新西兰境内的运费需要此项。国际运费中此项是可选的；填写后，NZ Post 会返回您的合同费率。清空它也会清除已保存的 auth code。
Auth code：用于国内运费的账户 auth code。如果您填写了 site code，则无需此项。与 Client Secret 一样，保存后不会再次显示。
Site code：auth code 的替代项：您的 NZ Post 取件站点代码（pickup site code）。
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；国际邮费为零税率。当该配送方式有税类（General）时，请选择 Excluding GST，以免重复征收 GST。
NZD → （店铺货币）汇率：NZ Post 的价格以新西兰元计。如果您的店铺默认货币不是新西兰元，请输入一个新西兰元等于多少您的货币单位，例如 0.55。不填写则不使用实时运费。同一汇率也用于换算国际请求中发送的订单金额。汇率必须大于 0。如果您的店铺货币是新西兰元，请留空。
实时运费使用的包裹
购物车会作为一个包裹发送给 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 公斤）；留空也表示 25。0 表示无限制。开启 Ignore shipping zones 时，留空表示对于 Geo zone 之外的地址没有限制。
Minimum order amount：仅当需要配送的商品小计（使用优惠券后、税前）达到此金额时才显示该配送方式。留空则始终显示。
Free shipping from：小计（使用优惠券后、税前）达到此金额后，NZ Post 配送免运费。届时不会向 NZ Post 发送请求。留空则从不提供免运费。
对于这些条件，购物车重量将没有重量的商品计为 0。
可用性
通常，该配送方式会在下方选定的地理区域内提供；如果未选择任何区域，则在所有地区提供。
Geo zone：仅对该地理区域内的地址提供 NZ Post。All zones（默认）表示无限制。地理区域在 System > Localisation > Geo Zones 中管理。
Ignore shipping zones：对于下面列出的国家，即使在地理区域之外也提供 NZ Post。开启后，只有这些国家会获得该配送方式，包括在地理区域之内。默认：关闭。
Countries：该模式下的目的国家。留空则使用店铺中启用的所有国家。此字段仅在 Ignore shipping zones 开启时使用。
高级
Debug log：将运费计算写入 storage/logs/vfd_nzpt_debug.log.php（在 OpenCart 4 中为 system/storage/logs/vfd_nzpt_debug.log.php）。该文件无法通过网页读取。即使调试日志关闭，API 错误也始终会被记录。凭据、令牌、账户号和客户地址不会被记录。使用完毕后请关闭日志。当文件达到 5 MB 时，它会被移动到 vfd_nzpt_debug.old.log.php，并开始新的日志。
Log：显示日志的大小和最新条目。点击 Clear log 可清空。
Remove data on uninstall：开启时，卸载扩展会删除设置和日志。关闭时（默认），这些数据会保留，以便重新安装。缓存的运费始终会被删除。订单中的 NZ Post 详情始终保留。
导入 / 导出
Export：点击 Download JSON 将设置保存为 JSON 文件。Client Secret 和 auth code 不会被导出。
Import：粘贴之前导出的 JSON，然后点击 Import 以恢复设置，例如在另一个商店中。这些值会像正常保存时一样进行检查。只要 Client ID 和账户号仍然填写，已保存的 Client Secret 和 auth code 就会保留。
结账时的工作方式
OpenCart 显示配送方式时，会向扩展请求 NZ Post 价格。如果设置了 Geo zone 且地址位于其之外，则只有在 Ignore shipping zones 开启且该国家被允许时才会提供 NZ Post。只有 Requires Shipping 设为 Yes 的商品才会计入：其他商品不增加重量，也不计入订单金额。然后扩展检查条件：允许的国家（配合 Ignore shipping zones）、购物车重量和最低订单金额。订单金额是需要配送的商品的价格，在扣除优惠券折扣之后、税前计算。礼品卡、奖励积分和商店余额不计入。如果适用免运费，价格为 0，并且不会向 NZ Post 发送请求。否则，它会寻找价格：先是 NZ Post 实时运费，其次是国家表，最后是备用费用。如果没有价格，则隐藏该配送方式。
设置了实时运费后，扩展会使用您的 Client ID 和 Client Secret 获取访问令牌，并向 NZ Post 请求价格。对于新西兰的地址，它会发送您的账户信息、发货地址、客户的郊区、城市和邮政编码，以及包裹的重量和尺寸。OpenCart 没有郊区字段：当 Address 2 中包含郊区名称（不含数字）时，扩展会使用它，否则使用城市。只有在客户输入了城市和 4 位邮政编码之后，才会请求国内运费。对于其他国家，它会发送目的国家、包裹的重量和尺寸，以及以新西兰元计的订单金额。
使用允许的、有价格的最便宜服务，包括附加费和强制性附加服务。价格从新西兰元换算为店铺默认货币，按其小数位数取整，并以客户的货币显示，同时加上所选 Tax class 的税费。每个响应缓存 1 小时。失败的请求缓存 10 分钟，这样结账时不会在每次刷新时都等待 NZ Post。API 超时时间为 10 秒。访问令牌会一直保留到过期，被拒绝的令牌会自动更新。
如果 NZ Post 没有返回运费（API 未设置、出错、地址不完整、服务不可用、没有新西兰元汇率），客户不会看到任何错误。将使用国家表中的价格，然后是备用费用。如果没有固定价格，则隐藏该配送方式。原因会记录在日志中。
在 OpenCart 4 中，顾客在结账页的配送方式区块中点击 Choose，并在 Shipping method options 窗口中选择一个 NZ Post 选项。运费与 OpenCart 3 相同。
扩展只计算运费。它不会创建运单、生成清单、预约取件、跟踪包裹、验证地址，也不允许客户选择自提点、邮政信箱（PO Box）或包裹柜。购物车按一个包裹计价，客户看到的是一个 NZ Post 运费，而不是服务列表。
订单
下订单使用 NZ Post 时，扩展会保存运费所依据的信息。在 Sales > Orders 中打开订单：订单页面会显示一个 NZ Post 面板，包含 NZ Post service（实时运费已计价的 NZ Post 服务及其代码）和 Price source：Live rate (NZ Post ShippingOptions API)、Fixed price 或 Free shipping。即使运费或设置之后有变化，面板也会显示下单时的数值，并且在该配送方式关闭时同样显示。客户看不到服务名称。
在 OpenCart 4 中，NZ Post 面板显示在 History 上方。OpenCart 4 为结账保留一个订单，并在顾客每次重新确认时更新它，已保存的服务和价格来源也会随之更新。如果顾客将该订单切换到其他配送方式，订单中的 NZ Post 数据将被移除。
许可证密钥
本扩展需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox NZ Post 是扩展 Extensions > Extensions > Shipping > VibeFox NZ Post > Edit 页面中位于设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以隐藏方式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now 用于再次检查状态，Change key 用于输入其他密钥，Remove key 用于从本店移除密钥。其下方有一行 Product: opencart-shipping-nz-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 账户中释放该名额。
如果没有有效的密钥，NZ Post 配送方式不会在结账时显示给顾客，也不会计算费率。在后台同一浏览器中登录的管理员用户仍能在店铺中看到该方式，并标记为 (unlicensed — visible to admins only)，因此您可以在购买密钥之前完成设置和测试。在 OpenCart 4 中没有此预览功能：店铺无法识别后台登录状态，因此没有有效密钥时，该方式对所有人都隐藏。打开一次 Edit 页面后，后台 Dashboard 会出现提醒。点击 × 关闭，可隐藏 7 天。现有订单不受影响。
许可证到期后，扩展仍会继续运行，但更新和支持需要续费。当您打开后台 Dashboard 或 Edit 页面时会自动再次检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展总会删除许可证密钥和许可证状态。
故障排除
结账时未显示 NZ Post：请检查许可证是否有效，以及 Enable NZ Post 是否已开启。检查 Geo zone（或 Ignore shipping zones 和 Countries）、重量限制和 Minimum order amount。如果 NZ Post 没有返回运费，则只有在有国家价格或 Fallback cost 时才会显示该配送方式。检查商品的 Requires Shipping 是否设为 Yes。
实时运费未显示：请查看扩展页面顶部的警告。然后开启 Debug log，重新加载结账页面，并查看 Log 字段。API 错误始终会显示在那里。日志会说明原因：缺少 Client ID 或 Client Secret，令牌被拒绝，缺少账户或发货数据，客户尚未填写城市或邮政编码，没有新西兰元汇率，或没有可计价的服务。在您解决问题期间，将使用固定价格。
令牌请求失败：请检查 Client ID、Client Secret 和 Environment。UAT 凭据无法用于生产环境，反之亦然。
国内运费缺失，国际运费正常：新西兰境内的运费需要 Account number、Auth code 或 Site code，以及包含 4 位邮政编码的完整发货地址。客户必须输入城市和 4 位邮政编码。
我的店铺不使用新西兰元：请输入新西兰元汇率（NZD → (您的货币) rate 字段）。固定价格始终以店铺默认货币计。
运费被重复征收 GST：NZ Post 的国内运费包含 15% 的 GST。如果该配送方式设有 Tax class，请将 API prices 设为 Excluding GST。
修改后运费看起来过时：请在扩展页面上点击 Save。这会清除缓存的 NZ Post 运费和令牌。
页面显示“Warning: You do not have permission to modify VibeFox NZ Post!”：您的管理员用户组可能只能查看设置。请在 System > Users > User Groups 中为该组授予 extension/shipping/vfd_nz_post（OpenCart 3）或 extension/vfd_nz_post/shipping/vfd_nz_post（OpenCart 4） 的修改权限。
面向开发人员：发往新西兰送货地址的郊区可以通过 OpenCart 事件 vfd_nz_post/delivery_suburb（触发器 catalog/vfd_nz_post/delivery_suburb）修改。NZ Post API 地址可以通过设置 vfd_nzpt_api_url（用于测试）替换；设置页面上没有对应字段。
卸载
进入 Extensions > Extensions，选择类型 Shipping，然后点击 VibeFox NZ Post 旁边的 Uninstall（红色 − 按钮）。此扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会重置 Enable NZ Post、Sort order、Tax class 和 Geo zone。缓存的运费和令牌始终会被删除，订单页面也不再显示 NZ Post 面板。如果 Remove data on uninstall 已开启，NZ Post 设置和调试日志也会被删除。如果已关闭，其他设置会保留，并在您重新安装扩展时再次使用。订单中已保存的 NZ Post 详情从不会被删除，重新安装后会再次显示。现有订单会保留其配送方式和费用。
在 OpenCart 4 中，如需同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox NZ Post 旁边的 Uninstall（橙色的 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。
NZ Post 是其各自所有者的商标。本扩展与 NZ Post 没有关联，也未获得 NZ Post 的认可。