VibeFox NZ Post for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝在较旧的 PHP 版本上安装。
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. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure，或稍后在模块列表中找到 VibeFox NZ Post 并点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，于 License key 处输入您的 VibeFox 许可证密钥，然后点击 Activate（见许可证密钥）。
4. 若要使用实时运费，请填写 NZ Post API (live rates) 部分。您也可以填写固定价格，它在没有实时运费时使用，并作为备用（参见“配置”）。点击 Save。
安装时，模块会创建 NZ Post 承运商，配送时间文本为 NZ Post parcel delivery。该承运商会分配给所有区域和所有客户组。您可以在 Shipping > Carriers 中更改区域、客户组、配送时间、徽标和尺寸限制。请不要在那里设置价格：价格始终来自模块。
配置
所有设置都位于模块页面：Modules > Module Manager > VibeFox NZ Post > Configure。这些设置适用于承运商的每个区域。每个部分都有自己的 Save 按钮，它会保存整个页面。每次保存还会清除缓存的 NZ Post 运费和访问令牌。
当实时运费无法使用已保存的值正常工作时，设置上方会显示警告：Client ID 和 Client Secret 只填了其中一个、没有 NZD 换算汇率，或国内运费的数据不完整。如果模块无法识别商店的重量或尺寸单位，也会显示警告（此时重量按公斤、尺寸按厘米处理）。请在 International > Localization（Local units）中设置单位。数字字段必须包含 0 或正数；否则页面会显示错误，且不会保存任何内容。
General
Enable NZ Post：启用或停用该承运商。这与 Shipping > Carriers 中的承运商状态是同一个开关。
Method title：在购物车和结账时显示的承运商名称。默认：NZ Post。必填，最多 64 个字符。
Tax：承运商的税务规则，或 No tax（运费不征税）。如果商店对运费加收 GST，请将下方的 API prices 设为 Excluding GST，以避免重复征收 GST。
NZ Post API (live rates)（如只使用固定价格，请将 Client ID 留空）
Environment：Production (api.nzpost.co.nz)（默认）或 Testing / UAT (api.uat.nzpost.co.nz)。请使用颁发您 Client ID 时对应的环境。
Client ID：您的 NZ Post API 应用的 OAuth2 client ID。清空它也会清除已保存的 Client Secret。
Client Secret：OAuth2 client secret。它会被换取为访问令牌，该令牌会缓存到过期为止。保存后，该字段保持为空并显示 Saved — leave empty to keep it。只有在需要更改时才输入新值。
Account number：您的 NZ Post 商务（结算）账户号。新西兰境内的运费必填。国际运费为可选项；填写后，NZ Post 会返回您的合同运费。清空它也会清除已保存的 auth code。
Auth code：用于国内运费的账户授权码。如果您填写了 site code，则无需此项。与 Client Secret 一样，保存后不会再次显示。
Site code：auth code 的替代项：您的 NZ Post 揽收网点代码。
Ship-from suburb：包裹寄出地址所在的郊区（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），请选择 Excluding GST，以避免重复征收 GST。
NZD → (shop currency) rate：NZ Post 的价格以 NZD 计。如果您的商店默认货币不是 NZD，请填写一个 NZD 等于多少个您的货币单位，例如 0.55。不填写则不使用实时运费。同一汇率也会换算国际请求中发送的订单金额。汇率必须大于 0。如果您的商店货币是 NZD，请留空。
Parcel for live rates
购物车以一个包裹的形式发送给 NZ Post。商品的重量和尺寸会从商店单位换算为公斤和厘米。包裹取商品中最大的长度和宽度，高度则不断增加，直到能容纳所有商品的体积。以下数值用于没有重量或尺寸的商品。
Default product weight (kg)：用于每个没有重量的商品。默认：0.5。
Default parcel length (cm)：当购物车中没有任何商品有尺寸时使用。默认：30。
Default parcel width (cm)：当购物车中没有任何商品有尺寸时使用。默认：20。
Default parcel height (cm)：当购物车中没有任何商品有尺寸时使用。默认：10。
Fixed prices（在未设置实时运费或 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) 则按购物车中的商品数量相乘。这仅适用于固定价格和备用运费。实时运费始终按整个包裹计算。
Conditions
Min cart weight (kg)：当购物车重量低于此值时隐藏该承运商。0 表示不限制。
Max cart weight (kg)：当购物车重量高于此值时隐藏该承运商。默认：25（NZ Post 快递包裹最重可达 25 公斤）；空白也表示 25。0 表示不限制。启用 Ignore shipping zones 时，空白表示在承运商自身区域之外不设限制。如果 Min cart weight 大于 Max cart weight，页面会显示错误，且不会保存任何内容，因为该承运商将永远不会显示。
Minimum order amount：仅当购物车小计（需要配送的商品，折扣之后、税费之前）达到此金额时才显示该承运商。留空则始终显示。
Free shipping from：购物车小计（折扣之后、税费之前）达到此金额时，NZ Post 配送免费。此时不会向 NZ Post 发送请求。留空则从不提供免运费。
对于这些条件，购物车重量会将没有重量的商品计为 0。
Availability without shipping zones
通常，该承运商会显示在 Shipping > Carriers 中为其分配的区域。
Ignore shipping zones：无论匹配哪个区域，都为下方列出的国家提供 NZ Post。保存时，该承运商会添加到所有区域（包括之后创建的区域）。关闭此选项会再次移除添加的区域。
Countries：该模式下的目的国。留空则使用商店所有启用的国家。仅当 Ignore shipping zones 启用时才使用此字段。
Advanced
Debug log：将运费计算记录到模块文件夹中的 logs/vfd_nzpt_debug.log.php。该文件无法通过网页打开。即使调试日志关闭，API 错误也始终会被记录。凭据、令牌和客户地址不会被记录。使用完毕后请关闭日志。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Remove data on uninstall：启用后，卸载模块将删除设置、承运商、缓存的运费、保存的订单详情和日志。关闭时，所有内容都会保留，以便重新安装。
结账时的工作方式
在配送步骤中，PrestaShop 会向模块询问 NZ Post 的价格。只有实物商品计入：虚拟商品不增加重量，也不计入订单金额。模块首先检查条件：允许的国家（使用 Ignore shipping zones 时）、购物车重量和最低订单金额。如果适用免运费，价格为 0，且不会向 NZ Post 发送请求。否则，它会查找价格：先是 NZ Post 实时运费，然后是国家表，最后是备用运费。如果没有价格，则隐藏该承运商。
设置了实时运费后，模块会使用您的 Client ID 和 Client Secret 获取访问令牌，并向 NZ Post 请求价格。对于新西兰的地址，它会发送您的账户信息、寄件地址、客户的郊区、城市和邮政编码，以及包裹的重量和尺寸。PrestaShop 没有郊区字段：当 Address line 2 包含郊区名称（不含数字）时，模块会使用它；否则使用城市。只有在客户输入城市和 4 位邮政编码之后，才会请求国内运费。对于其他国家，它会发送目的国、包裹重量和尺寸，以及以 NZD 计的订单金额。
将使用价格最低、且允许的服务，并包含附加费和强制附加服务。价格会从 NZD 换算为商店默认货币，然后以客户的购物车货币显示。每个响应缓存 1 小时。失败的请求缓存 10 分钟，以免结账在每次刷新时都等待 NZ Post。API 超时时间为 10 秒。过期的访问令牌会自动更新。
如果 NZ Post 没有返回运费（API 未设置、出错、地址不完整、服务不可用、没有 NZD 汇率），客户不会看到任何错误。系统会使用国家表中的价格，然后是备用运费。如果没有固定价格，则隐藏该承运商。原因会写入日志。
如果您在承运商已有订单后，在 Shipping > Carriers 中编辑该承运商，PrestaShop 会将其保存为新版本的承运商。模块会自动跟随新版本。
模块只计算运费。它不会生成运单、预约取件、制作交接清单、跟踪包裹、验证地址，也不支持顾客选择取件点、邮政信箱（PO Box）或包裹储物柜（parcel locker）。购物车按一个包裹计价，顾客看到的是一个 NZ Post 运费，而不是服务列表。
订单
下单使用 NZ Post 承运商时，模块会保存运费计算所依据的信息。后台订单页面会显示一个 NZ Post 区块，其中包含 NZ Post service（实时运费计价所用的 NZ Post 服务）和 Price source：Live rate (NZ Post ShippingOptions API)、Fixed price 或 Free shipping。该区块显示下单时的值，即使之后运费或设置发生变化也不受影响。
许可证密钥
模块需要一个在 vibefox.net 获取的 VibeFox 许可证密钥。许可证区块 License — VibeFox NZ Post 是 Modules > Module Manager > VibeFox NZ Post > Configure 页面中位于设置上方的第一个区块。将密钥输入 License key，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now 用于重新检查状态，Change key 用于输入其他密钥，Remove key 用于从此店铺中移除密钥。其下方是 Product: presta-shipping-nz-post 一行，以及打开您 vibefox.net 账户的 Manage licenses and domains in your account 链接。只有拥有该模块 Configure 权限的员工才能更改密钥。该区块的文字遵循后台语言（包括英文和俄文）。
如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或带有日期的 License expired on。更改店铺地址后，或在账户中释放域名名额后，请点击 Check now。如果无法连接许可证服务器，模块将继续按最后已知的状态运行。
一个密钥只能用于一个域名：主店铺的域名，多店铺设置中同样适用。从店铺中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。
没有有效的密钥，结账时不会向顾客显示 NZ Post 承运商，也不会计算任何运费。PrestaShop 前台无法得知您已登录后台，因此承运商对您也是隐藏的：您可以在购买密钥之前设置模块，但无法在结账时进行测试。Modules > Module Manager 的 Alerts 选项卡中会显示提醒。现有订单不受影响。
许可证过期后，模块仍会继续运行，但更新和支持需要续订。在后台工作时，状态会自动重新检查：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时没有显示 NZ Post：请检查许可证是否有效，以及 Enable NZ Post 是否已开启。在 Shipping > Carriers 中，检查该承运商是否覆盖了顾客所在国家的区域和顾客所属的客户组（或者已开启 Ignore shipping zones 且该国家被允许）。检查重量限制和 Minimum order amount。如果 NZ Post 没有返回运费，则只有在设置了国家价格或 Fallback cost 时才会显示该承运商。商品页面上也可以将商品限制为特定承运商。
实时运费没有显示：请查看模块页面顶部的警告。然后开启 Debug log，重新加载结账页面，并查看 Log 字段。API 错误始终会显示在那里。日志会说明原因：缺少 Client ID 或 Client Secret、令牌被拒绝、缺少账户或寄件数据、尚未获得顾客的城市或邮政编码、没有 NZD 汇率，或没有可计价的服务。在您解决问题期间，将使用固定价格。
令牌请求失败：请检查 Client ID、Client Secret 和 Environment。UAT 凭据无法用于生产环境，反之亦然。
国内运费缺失，国际运费正常：新西兰境内的运费需要 Account number、Auth code 或 Site code，以及包含 4 位邮政编码的完整寄件地址。顾客必须输入城市和 4 位邮政编码。开发人员可以使用 actionVfdNzptDeliverySuburb 钩子更改为收货地址发送的郊区。
我的商店不使用 NZD：请填写 NZD → (shop currency) rate。固定价格始终以商店默认货币计。
运费被重复征收 GST：NZ Post 的国内运费包含 15% GST。如果承运商在 Tax 中设有税务规则，请将 API prices 设为 Excluding GST。
更改后运费看起来过时：请在模块页面点击 Save。这会清除缓存的 NZ Post 运费和令牌。
页面提示找不到 NZ Post 承运商：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置该模块，以重新创建它。
卸载
进入 Modules > Module Manager，打开 VibeFox NZ Post 旁边的菜单，然后选择 Uninstall。许可证密钥和许可证状态始终会被删除。缓存的运费和令牌始终会被删除。如果 Remove data on uninstall 已开启，承运商会被删除（订单保留其历史记录），同时删除设置、保存的订单详情和日志。如果已关闭，承运商仅会被停用，所有设置都会保留。重新安装模块或执行 Reset，都会将已保存的承运商恢复为其之前的状态（启用或停用）。
NZ Post 是其各自所有者的商标。本模块与 NZ Post 没有关联，也未获得 NZ Post 的认可。