VibeFox Australia Post for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块会拒绝在较旧的 PHP 版本上安装。
Australia Post PAC API 密钥（仅用于实时运费）：实时运费使用 Australia Post 包裹计价计算器（PAC）API。密钥免费：请在 Australia Post 开发者中心（developers.auspost.com.au）注册以获取 PAC API 密钥。模块页面提供注册页面的链接。您还需要发货地的 4 位澳大利亚邮政编码。如果只使用按国家设置的固定价格，则无需 API 密钥。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或之后在模块列表中找到 VibeFox Australia Post，点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入 License key 字段，然后点击 Activate（参见“许可证密钥”）。
4. 选择 Rate source。若使用实时运费，请输入 PAC API 密钥、发货邮政编码；如果店铺默认货币不是 AUD，还需输入 AUD 换算汇率（参见配置）。点击 Save。
安装时，模块会创建 Australia Post 承运商，配送时间文本为 Australia Post parcel delivery。该承运商会分配给所有区域和所有客户组。您可以在 Shipping > Carriers 中更改区域、客户组、配送时间、Logo、尺寸限制和税务规则。请勿在那里设置价格：价格始终来自模块。
配置
所有设置都在模块页面中：Modules > Module Manager > VibeFox Australia Post > Configure。它们适用于每个区域。页面顶部显示 Shipping > Carriers 中承运商的名称和 ID。每个部分都有自己的 Save 按钮，保存时会保存整个页面。每次保存也会清除缓存的 Australia Post 运费。
如果选择了实时运费来源，但缺少 API 密钥、4 位发货邮政编码或 AUD 换算汇率，保存后会显示警告。警告还会说明在修正之前会发生什么：承运商在结账时隐藏，或在回退模式下使用按国家设置的固定价格。
数字字段接受小数点或逗号作为小数分隔符。不是数字或为负数的值不会被保存：警告会指出该字段，并保留之前的值。如果店铺的重量或尺寸单位（International > Localization）是模块不认识的单位，页面也会发出警告。此时，商品重量按千克、尺寸按厘米读取。
常规
Enable Australia Post：一次性关闭所有区域中的承运商。这与 Shipping > Carriers 中承运商的状态是同一个开关。
Method title：结账时显示给顾客的承运商名称。它也是 Shipping > Carriers 中的承运商名称，在那里重命名承运商会同步更新此字段。默认值：Australia Post。最多 64 个字符：超过长度的标题会被拒绝，且不会保存任何内容。如果该字段为空，或包含 PrestaShop 不允许用于承运商名称的字符，会显示警告，并使用 Australia Post。
Tax status：税款如何应用于运费。
Rate source：价格如何计算。
错误详情会写入日志，绝不会显示给顾客。
Australia Post API（实时运费）（固定价格无需此项）
PAC API key：您免费获得的 Australia Post PAC API 密钥。它会在 AUTH-KEY 请求头中发送给 Australia Post。保存后，该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。
Remove the saved API key：开启并保存即可删除已保存的密钥。之后实时运费将停止工作。
Ship-from postcode：寄出包裹所在地的 4 位澳大利亚邮政编码，例如 2000。
Domestic service：用于澳大利亚境内的配送（最大 22 kg，每边最长 105 cm）：Parcel Post（默认）或 Express Post。
International service：用于澳大利亚境外的配送（最大 20 kg）：International Standard（默认）、International Express 或 International Courier。
Remove GST：将国内 API 价格除以 1.1。Australia Post 的国内价格包含 10% 的 GST。当 PrestaShop 自行对运费征税时（Tax status = Taxable，且承运商已设置税务规则）请开启此项，以免重复征收 GST。国际邮费免征 GST，且始终不会被修改。
AUD → (your currency) rate：标签显示您店铺的默认货币。Australia Post 的价格以 AUD 计。如果默认货币不是 AUD，请输入 1 AUD 等于多少您的货币单位，例如 0.61。汇率必须大于 0。没有汇率时，不会使用实时运费。如果默认货币是 AUD，页面会提示无需换算：请将该字段留空。小数分隔符可以使用句点或逗号。
实时运费的包裹设置
购物车将作为一个包裹发送。商品重量和尺寸会从店铺单位换算为千克和厘米。下列数值用于没有重量或尺寸的商品。
Default product weight (kg)：用于每个没有重量的商品，用于 Australia Post 请求以及 Min cart weight (kg) / Max cart weight (kg) 的检查。默认值：1。
Default parcel length (cm)：当购物车中没有任何商品有尺寸时使用。默认值：22。
Default parcel width (cm)：当购物车中没有任何商品有尺寸时使用。默认值：16。
Default parcel height (cm)：当购物车中没有任何商品有尺寸时使用。默认值：8。
当商品有尺寸时，包裹会采用其中最大的长度和宽度，高度则会增加，直到包裹能容纳所有商品的体积。
固定价格（用于固定价格，并作为实时运费的回退方案）
Country prices：一个表格，包含 2 位字母的国家代码（AU、NZ、US 等）以及以店铺默认货币计、不含税的价格。点击 Add row 可添加国家，点击 × 链接可删除。使用 * 表示所有其他国家。没有价格的国家（且没有 * 行）不会有固定运费，因此该国家会隐藏此承运商。保存时，国家代码无效或没有价格的行会被删除。在您添加价格之前，表格为空。
Fixed price per：Order 只收取一次价格。Item (price × quantity) 则按购物车中的商品数量相乘。这仅适用于固定价格。实时运费始终按整个包裹计算。
条件
Min cart weight (kg)：购物车重量低于此值时隐藏承运商。0 表示无限制。
Max cart weight (kg)：购物车重量高于此值时隐藏承运商。默认值：22。0 表示无限制，字段为空则表示 22 kg。Australia Post 包裹限制：国内 22 kg，国际 20 kg。如果 Min cart weight (kg) 大于最大值，承运商将永远不会显示：会出现警告，且两个重量都保留之前的值。
Minimum order amount：仅当商品小计（折扣后，不含税）达到此金额时才显示承运商，金额以店铺默认货币计。将其留空则始终显示。
Free shipping：开启从下方金额起免运费。
Free shipping from：商品小计（折扣后，不含税）达到此金额时运费免费。此时不会向 API 发出请求。仅在 Free shipping 开启时使用。
无配送区域时的可用性
通常，承运商会在 Shipping > Carriers 中为其选择的区域内提供。
Ignore shipping zones：无论哪个区域匹配，都为下方指定的国家提供承运商。保存时，承运商会关联到所有区域，之后创建的区域也会自动关联。关闭此选项会恢复承运商之前拥有的区域。
Countries：此模式下的目标国家。留空则允许所有启用的国家。按住 Ctrl（Mac 上为 Cmd）并点击可选择多个国家。仅与 Ignore shipping zones 一起使用。
高级
Debug log：将运费计算记录到 modules/vfd_australia_post/logs/vfd_ap.log.php。该文件无法通过网页打开。API 错误始终会被记录。API 密钥和顾客邮政编码不会被记录。使用完毕后请关闭日志。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Remove data on uninstall：开启后，卸载模块会删除设置、缓存的运费和日志。卸载时始终会删除承运商。如果保留了数据，重新安装时会恢复承运商。
结账时的工作方式
在配送步骤，PrestaShop 会向模块请求 Australia Post 的价格。只计算实体商品：虚拟商品不增加重量，也不计入订单金额。模块首先检查条件：Countries 列表（配合 Ignore shipping zones）、购物车重量以及 Minimum order amount。如果适用免运费，价格为 0，且不会向 Australia Post 发送请求。
在固定价格模式下，价格从表格中获取。在实时运费模式下，模块会向 Australia Post 发送包裹重量；对于澳大利亚境内的配送，还会发送发货和收货邮政编码以及包裹尺寸；对于国际配送，则发送目的国家。只有当收货地址包含 4 位邮政编码时，才会请求国内实时运费。如果包裹超出 Australia Post 的限制（国内 22 kg 或 105 cm，国际 20 kg），则不会发送请求。AUD 价格按您的汇率换算；如果开启了 Remove GST，则从国内价格中扣除 GST。价格以店铺默认货币计算，然后以顾客的购物车货币显示。
每个成功的响应都会缓存 1 小时，因此同一购物车不会触发新的请求。失败的请求会缓存 10 分钟，这样结账页面在每次刷新时都不必等待 Australia Post。API 超时时间为 10 秒。API 错误绝不会显示给顾客：承运商会被隐藏，或在回退模式下使用固定价格。原因会写入日志。
如果在承运商已有订单之后，您在 Shipping > Carriers 中编辑了该承运商，PrestaShop 会将其保存为新的承运商版本。模块会自动跟随新版本。
模块只计算运费。它不会创建配送标签、eParcel 或 MyPost Business 发货单或舱单，不跟踪包裹，也不允许顾客选择包裹储物柜或邮局。购物车始终按一个包裹计价。信件、信封包裹和合同（eParcel）费率不包括在内。
许可证密钥
模块需要使用 vibefox.net 提供的 VibeFox 许可证密钥。License — VibeFox Australia Post 许可证区块是 Modules > Module Manager > VibeFox Australia Post > Configure 中位于设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。此后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），并提供以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店移除密钥）。其下方是 Product: presta-shipping-australia-post 一行，以及 Manage licenses and domains in your account 链接，它会打开您的 vibefox.net 账户。只有拥有该模块 Configure 权限的员工才能更改密钥。区块中的文字跟随后台语言显示（包含英语和俄语）。
如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或带日期的 License expired on。更改店铺地址后，或在账户中释放域名名额后，请点击 Check now。如果无法连接许可证服务器，模块将继续按最后已知状态运行。
一个密钥只能用于一个域名：主店铺的域名，多店铺设置中也是如此。从店铺中移除密钥不会释放其域名名额。请在 vibefox.net 账户中释放名额。
没有有效密钥时，Australia Post 承运商不会在结账时显示给顾客，也不会计算任何运费。PrestaShop 前台无法得知您已登录后台，因此该承运商对您也是隐藏的：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 的 Alerts 选项卡中会出现提醒。现有订单不受影响。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。您在后台工作时会自动再次检查状态：输入密钥后的前 14 天内每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，总会删除许可证密钥和许可证状态。
故障排除
结账时未显示 Australia Post：请检查许可证是否有效，以及 Enable Australia Post 是否开启（承运商在 Shipping > Carriers 中处于启用状态）。在 Shipping > Carriers 中，检查承运商是否覆盖顾客所在国家的区域和顾客所在的客户组（或者 Ignore shipping zones 已开启，且该国家在 Countries 中被允许）。检查购物车重量限制和 Minimum order amount。在固定价格模式下，检查该国家或 * 是否有价格。此外，商品页面中也可能将商品限制为特定承运商。
实时运费未显示：开启 Debug log，重新加载结账页面，然后查看模块页面上的 Log 字段。它会显示原因：缺少 API 密钥或发货邮政编码，尚未填写 4 位收货邮政编码，包裹超出限制，缺少 AUD 换算汇率，或 Australia Post 的错误信息。使用 Live rates, fixed price if the API gives no rate 时，在您解决问题期间，顾客仍会看到固定价格。
我的店铺不使用 AUD：在 AUD → (your currency) rate 字段中输入换算汇率（1 AUD 等于多少您默认货币的单位）。固定价格始终以您的默认货币计。
运费被重复征收 GST：Australia Post 的国内价格包含 10% 的 GST。如果 Tax status 为 Taxable，且承运商设有税务规则，请开启 Remove GST，或将 Tax status 设为 None。
运费上没有添加税款：当 Tax status = Taxable 时，税款来自承运商的税务规则。请在 Shipping > Carriers 中选择该规则。在承运商没有税务规则期间，模块页面会显示警告。
价格过高或过低：请检查商品的重量和尺寸，以及 Parcel for live rates 中的默认值。使用 Item (price × quantity) 时，固定价格会乘以商品数量。
更改后运费看起来过时：在模块页面点击 Save。这会清除缓存的 Australia Post 运费。
页面提示 Australia Post 承运商已被删除：承运商已在 Shipping > Carriers 中被删除。在模块页面点击 Save 可重新创建，或在 Modules > Module Manager 中重置模块。
卸载
进入 Modules > Module Manager，打开 VibeFox Australia Post 旁边的菜单，然后选择 Uninstall。许可证密钥和许可证状态总会被删除。承运商始终会被删除（订单保留其历史记录），缓存的运费也会被清除。如果开启了 Remove data on uninstall，设置、运费缓存表和日志也会被删除。如果关闭，设置会保留，重新安装模块后，承运商会连同其区域、客户组和 Logo 一起恢复。
Australia Post 是其所有者的商标。本模块与 Australia Post 无关联，也未获得其认可。