VibeFox Australia Post for OpenCart — 帮助

系统要求

OpenCart: 3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。

PHP: 8.0 或更高版本。

Australia Post PAC API 密钥（仅用于实时运费）：实时运费使用 Australia Post 的邮资评估计算器（PAC）API。该密钥免费：请在 Australia Post Developer Centre（developers.auspost.com.au）注册以获取 PAC API 密钥。设置页面会链接到注册页面。您还需要发货所在地的 4 位澳大利亚邮政编码。如果您只使用按国家的固定价格，则无需 API 密钥。

VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。

安装

下载包是一个 zip 文件，内含两个 OpenCart 版本的安装包。请解压到您的电脑上。其中包含 README.txt、OpenCart 3 安装包 vfd_australia_post-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 vfd_australia_post.ocmod.zip。请只安装与您的 OpenCart 版本对应的安装包。两个版本的许可证密钥相同。

OpenCart 3

1. 在后台依次进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_australia_post-oc3-(version).ocmod.zip。本扩展不添加任何 OCMOD 修改，因此您无需刷新 Extensions > Modifications。您也可以不使用 Installer，而是将本安装包中 upload 文件夹的内容复制到店铺的根目录。

2. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Australia Post，点击 Install（绿色的 + 按钮）。

3. 点击 Edit（铅笔按钮）打开设置页面。

4. 将您的 VibeFox 许可证密钥粘贴到 Edit 页面顶部许可证区块中的 License key，然后点击 Activate（参见许可证密钥）。

5. 选择 Rate source（运费来源）。固定价格请在 Country prices 中添加行。实时运费请输入 PAC API 密钥、发货邮政编码，以及若店铺默认货币不是 AUD，则输入 AUD 汇率（参见配置）。启用 Enable Australia Post 并点击 Save。

OpenCart 4

1. 在后台依次进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_australia_post.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包将无法使用。

2. 安装包会出现在同一页面已安装扩展的列表中。点击其旁边的 Install（绿色的 + 按钮）。

3. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Australia Post，点击 Install（绿色的 + 按钮），然后点击 Edit（铅笔按钮）。

4. 按照 OpenCart 3 的步骤 4 和 5 输入许可证密钥和设置。设置页面及其字段在两个版本中相同。

安装后，在您启用 Enable Australia Post 并保存之前，该配送方式处于关闭状态。如果您在卸载后重新安装扩展，之前保留的 Australia Post 设置将再次生效。

配置

所有设置都在扩展页面中：Extensions > Extensions > Shipping > VibeFox Australia Post > Edit。各分区列在左侧。一个 Save 按钮可保存整个页面，无需重新加载。每次保存也会清除缓存的 Australia Post 运费。只有拥有本扩展修改权限的管理员用户才能保存设置。

有些错误会阻止保存，此时不会保存任何内容：Method title 超过 64 个字符，Sort order 不是整数，或税类、地理区域不存在。其他问题会以警告形式显示在面板上方，其余设置仍会保存。无效或为负数的数字字段会保留其之前的值，警告会指出该字段。数字字段接受小数点或逗号作为小数分隔符。

如果选择了实时运费来源，但缺少 API 密钥、4 位发货邮政编码或 AUD 汇率，保存后会显示警告。警告还会说明在修正之前会发生什么：结账时隐藏该配送方式，或在备用模式下使用按国家的固定价格。如果您的店铺没有单位为 kg 的重量类别，或没有单位为 cm 的长度类别，页面也会发出警告。此时，商品的重量和尺寸将按其类别的单位进行转换（kg、g、lb、oz；cm、mm、m、in），其他单位则按 kg 和 cm 读取。

General

这些设置适用于所有地理区域。您可以在 Conditions 中将该配送方式限制在某个地理区域，或在 Availability without shipping zones 中将其限制在一组国家。

Enable Australia Post: 在结账时显示或隐藏 Australia Post。默认：关闭。

Method title: 顾客在购物车和结账时看到的配送方式名称。默认：Australia Post。最多 64 个字符：超过长度的标题会被拒绝，且不保存任何内容。如果该字段为空，会显示警告，并使用 Australia Post。

Rate source: 价格的计算方式。

错误详情会写入日志，绝不会显示给顾客。

Sort order: Australia Post 在结账时配送方式中的位置。一个整数。

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。当 OpenCart 自行对运费加税（已选择 Tax class）时开启此项，以避免重复征收 GST。国际邮费免征 GST，且绝不会被修改。

AUD → (your currency) rate: 标签显示店铺的默认货币。Australia Post 的价格以 AUD 计价。如果您的默认货币不是 AUD，请输入一个 AUD 可兑换多少单位您的货币，例如 0.61。汇率必须大于 0。没有汇率则不会使用实时运费。如果您的默认货币是 AUD，该字段会提示无需换算：请留空。

实时运费的包裹

购物车将作为一个包裹发送。商品的重量和尺寸从 OpenCart 的重量和长度类别转换为 kg 和 cm。下列数值用于没有重量或尺寸的商品。

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: 以您店铺默认货币计价（不含税）的国家与价格列表。点击 Add row 添加一行，点击 × 按钮删除一行。选择 * All other countries，可为没有自己专属行的所有国家设置一个通用价格。没有价格的国家（且没有 * 行）不会获得固定运费，因此该配送方式对其隐藏。保存时会删除没有价格的行。在您添加价格之前，表格为空。

Fixed price per: Order（默认）按订单收取一次价格。Item (price × quantity) 则按购物车中的商品件数相乘。这仅适用于固定价格。实时运费始终按整个包裹计算。

Conditions

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 开启时使用。

Tax class: 运费的税类，或 No tax（默认）。Australia Post 的国内价格包含 GST：若选择了税类，请开启 Remove GST。

Geo zone: 仅对此地理区域内的地址提供 Australia Post。All zones（默认）表示无限制。地理区域在 System > Localisation > Geo Zones 中管理。与 Ignore shipping zones 同时开启时不生效。

无配送区域时的可用性

通常，该配送方式会在 Conditions 中选定的地理区域内提供（All zones 表示所有地区）。

Ignore shipping zones: 无论地理区域如何，都对下面列出的国家提供该配送方式。

Countries: 该模式下的目的国家。输入即可搜索，并可选择多个。留空则允许店铺所有已启用的国家。仅在 Ignore shipping zones 开启时使用。

高级

Debug log: 将运费计算记录到 storage/logs/vfd_ap.log.php。该文件无法通过网页读取。API 错误始终会被记录。API 密钥和顾客邮政编码不会被记录。完成后请关闭日志。当文件达到 5 MB 时，它会被移至 vfd_ap.old.log.php，并开始新的日志。

Log: 显示日志的大小和最新条目。点击 Clear log 可将其清空。

Remove data on uninstall: 开启时，卸载扩展会删除设置、缓存的运费和日志。关闭时（默认），这些数据会被保留，以便重新安装。

导入 / 导出

导出：点击 Download JSON，将设置保存为 JSON 文件。API 密钥不会被导出。

导入：粘贴之前导出的 JSON，然后点击 Import 以恢复设置，例如在另一家店铺中使用。这些值会像正常保存时一样进行检查。已保存的 API 密钥会被保留。

结账时的工作方式

OpenCart 显示配送方式时，会向扩展请求 Australia Post 的价格。如果设置了 Geo zone（且 Ignore shipping zones 关闭），而地址不在该区域内，则不提供 Australia Post。开启 Ignore shipping zones 时，由 Countries 列表决定。只有 Requires Shipping 设为 Yes 的商品才会计入：其他商品不增加重量，也不计入订单金额。然后扩展检查购物车重量和 Minimum order amount。订单金额是需要配送的商品的价格，在扣除优惠券折扣之后、税前计算。礼品卡、奖励积分和店铺余额不计在内。如果适用免运费，则价格为 0，并且不会向 Australia Post 发送请求。

在固定价格模式下，价格从表格中获取。在实时运费模式下，扩展会向 Australia Post 发送包裹重量；对于澳大利亚境内的配送，还会发送发货和收货邮政编码以及包裹尺寸；对于国际配送，则发送目的国家。只有当收货地址包含 4 位邮政编码时，才会请求境内实时运费。如果包裹超出 Australia Post 的限制（境内 22 kg 或 105 cm，国际 20 kg），则不会发送请求。AUD 价格按您的汇率换算；如果开启了 Remove GST，则会从国内价格中移除 GST。价格以店铺默认货币计算，按其小数位数取整，并以顾客的货币显示，同时包含所选 Tax class 的税费。

每个成功的响应缓存 1 小时，因此同一购物车不会触发新的请求。失败的请求缓存 10 分钟，这样结账页面就不必在每次刷新时都等待 Australia Post。API 超时时间为 10 秒。API 错误绝不会显示给顾客：该配送方式会被隐藏，或在备用模式下使用固定价格。原因会写入日志。

本扩展仅计算运费。它不会创建快递标签、eParcel 或 MyPost Business 运单或清单，不追踪包裹，也不允许顾客选择包裹储物柜或邮局。它不会向订单添加任何内容：订单显示配送方式名称和运费，与任何其他 OpenCart 配送方式一样。购物车始终按一个包裹计价。信件、信封和合同价（eParcel）不包括在内。

在 OpenCart 4 上，顾客在结账页面的配送方式区块中点击 Choose，然后在 Shipping method options 窗口中选择 Australia Post。该配送方式的工作方式与 OpenCart 3 相同。

许可证密钥

本扩展需要一个来自 vibefox.net 的 VibeFox 许可证密钥。扩展的 Extensions > Extensions > Shipping > VibeFox Australia Post > Edit 页面中，位于设置上方的第一个区块是许可证区块 License — VibeFox Australia Post。将密钥粘贴到 License key 中并点击 Activate。之后，该区块会以隐藏形式显示密钥、许可证状态（例如许可证有效期至何时以及您的域名），并提供以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺移除密钥）。其下方是 Product: opencart-shipping-australia-post 一行，以及 Manage licenses and domains in your account 链接，该链接会打开您的 vibefox.net 账户。只有拥有本扩展修改权限的管理员用户才能更改密钥。该区块的文字跟随后台语言显示（包含英语和俄语）。

如果密钥未被接受，该区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached 或 License expired on 加上日期。店铺地址变更后，或在账户中释放一个域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展将继续使用最后已知的状态运行。

一个密钥只能用于一个域名：即 OpenCart 配置中的店铺地址。从店铺中移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。

没有有效的密钥时，Australia Post 不会在结账时显示给顾客，也不会计算运费。在同一浏览器中登录后台的管理员用户仍能在店铺中看到该配送方式，并标记为 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试扩展。在 OpenCart 4 上此预览不可用：店铺无法看到后台登录状态，因此没有有效密钥时，该配送方式对所有人都隐藏。打开一次 Edit 页面后，后台 Dashboard 上会出现提醒。点击 × 关闭，可隐藏 7 天。现有订单不受影响。

许可证到期后，扩展仍会继续运行，但更新和支持需要续订。当您打开后台 Dashboard 或 Edit 页面时会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展时始终会删除许可证密钥和许可证状态。

故障排除

Australia Post 未在结账时出现：请检查许可证是否有效，以及 Enable Australia Post 是否开启。检查 Geo zone（或 Ignore shipping zones 和 Countries）、购物车重量限制和 Minimum order amount。在固定价格模式下，检查该国家或 * All other countries 是否设置了价格。检查商品的 Requires Shipping 是否设为 Yes。

实时运费未出现：开启 Debug log，重新加载结账页面，并查看扩展页面上的 Log 字段。它会显示原因：缺少 API 密钥或发货邮政编码、尚无 4 位收货邮政编码、包裹超出限制、没有 AUD 汇率，或 Australia Post 的错误信息。使用 Live rates, fixed price if the API gives no rate，在您解决问题期间，顾客仍会获得固定价格。

我的店铺不是 AUD：在 AUD → (your currency) rate 字段中输入汇率（您的默认货币中，一个 AUD 等于多少单位）。固定价格始终以您的默认货币计。

运费上的 GST 被重复征收：Australia Post 的国内价格包含 10% 的 GST。若选择了 Tax class，请开启 Remove GST，或将 Tax class 设为 No tax。

价格过高或过低：请检查商品的重量和尺寸、其重量和长度类别，以及 Parcel for live rates 中的默认值。使用 Item (price × quantity) 时，固定价格会乘以商品件数。

更改后运费看起来过时：在扩展页面点击 Save。这会清除缓存的 Australia Post 运费。

页面提示 "Warning: You do not have permission to modify VibeFox Australia Post!"：您的管理员用户组可能只有查看设置的权限。请在 System > Users > User Groups 中为该组授予对 extension/shipping/vfd_australia_post（OpenCart 3）或 extension/vfd_australia_post/shipping/vfd_australia_post（OpenCart 4）的修改权限。

面向开发人员：可以使用设置 vfd_ap_api_url（用于测试）替换 PAC API 地址；设置页面上没有该项的输入框。

卸载

进入 Extensions > Extensions，选择类型 Shipping，然后点击 VibeFox Australia Post 旁边的 Uninstall（红色 − 按钮）。本扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会重置 Enable Australia Post、Sort order、Tax class 和 Geo zone。缓存的运费始终会被删除。如果 Remove data on uninstall 开启，Australia Post 设置和日志也会被删除。如果关闭，其他设置会被保留，并在您重新安装扩展时再次使用。现有订单保留其配送方式和费用。

在 OpenCart 4 上，若还要删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox Australia Post 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。

Australia Post 是其各自所有者的商标。本扩展与 Australia Post 无关联，也未获得 Australia Post 的认可。