VibeFox Aramex for OpenCart — 帮助
系统要求
OpenCart: 3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP: 8.0 或更高版本。
Aramex 账户（仅用于实时运费）：实时运费使用 Aramex Rate Calculator API。Aramex 向其账户持有人提供 API 访问权限。请咨询您的 Aramex 客户经理，或参阅 Aramex 网站上的 Aramex Developers Solution Center。您需要六个值：API 用户名（通常是电子邮件地址）、密码、账户号码、账户 PIN 码、账户实体（例如 DXB）和账户国家代码（例如 AE）。如果您只使用按国家的固定价格，则无需 Aramex 账户。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
下载包是一个 zip 文件，包含两个 OpenCart 版本的安装包。请先解压到您的电脑上。其中包含 README.txt、OpenCart 3 安装包 vfd_aramex-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 vfd_aramex.ocmod.zip。只需安装与您的 OpenCart 版本对应的安装包。两个版本的许可证密钥相同。
OpenCart 3
1. 在后台依次进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_aramex-oc3-(version).ocmod.zip。本扩展不添加任何 OCMOD 修改，因此您无需刷新 Extensions > Modifications。您也可以不使用 Installer，而是将本安装包中 upload 文件夹的内容复制到店铺的根目录。
2. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Aramex，点击 Install（绿色的 + 按钮）。
3. 点击 Edit（铅笔按钮）打开设置页面。
4. 将您的 VibeFox 许可证密钥输入到 Edit 页面顶部许可证块中的 License key 字段，然后点击 Activate（参见许可证密钥）。
5. 选择运费的计算方式，填写相应的分区（参见配置），启用 Enable Aramex，然后点击 Save。
OpenCart 4
1. 在后台依次进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_aramex.ocmod.zip。请勿重命名该文件：OpenCart 4 会从文件名获取扩展代码，重命名后的安装包将无法使用。
2. 安装包会出现在同一页面已安装扩展的列表中。点击其旁边的 Install（绿色的 + 按钮）。
3. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Aramex，点击 Install（绿色的 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按照 OpenCart 3 的步骤 4 和 5 输入许可证密钥和设置。两个版本的设置页面及其字段相同。
安装后，在您启用 Enable Aramex 并保存之前，该配送方式处于关闭状态。如果您在卸载后重新安装扩展，之前保留的 Aramex 设置将再次生效。
配置
所有设置都在扩展页面中：Extensions > Extensions > Shipping > VibeFox Aramex > Edit。各分区列在左侧。页面底部的一个 Save 按钮可保存整个页面，无需重新加载。每次保存也会清除缓存的 Aramex 运费。如果某个值有误，则不会保存任何内容，页面会显示原因，例如 Enter a method title (1 to 64 characters).、提示某个字段必须为数字的消息，或 The account country code must have 2 letters, e.g. AE. 只有拥有本扩展修改权限的管理员用户才能保存设置。
General
这些设置适用于所有地理区域。您可以在 Conditions 中将该方式限制在某个地理区域和特定国家。
Enable Aramex: 在结账时显示或隐藏 Aramex。默认：关闭。
Method title: 顾客在购物车和结账时看到的配送方式名称。默认：Aramex。必填。
Shipping cost: 价格的计算方式。
缺少实时运费的原因会写入调试日志。它绝不会显示给顾客。
Sort order: Aramex 在结账时配送方式中的位置。一个整数。
Aramex API 账户（仅实时运费需要；六个字段均为必填）
Username: 您的 Aramex API 用户名，通常是电子邮件地址。清空此项也会清除已保存的密码。
Password: 您的 Aramex API 密码。保存后，该字段保持为空，并显示 Saved — leave empty to keep it. 仅在需要更改时才输入新值。
Account number: 您的 Aramex 客户账户号码。清空此项也会清除已保存的 PIN 码。
Account PIN: 您的 Aramex 账户 PIN 码。与密码一样，保存后不会再次显示。
Account entity: 您账户的 Aramex 实体（办事处）代码，例如 DXB、AMM 或 RUH。
Account country code: 您的 Aramex 账户的两位字母国家代码，例如 AE。
Aramex 服务（用于实时运费）
如果收货地址位于发货国，则该运单按 Domestic 报价。所有其他运单按 International express 报价。
International service: 寄往国外的 Aramex 产品：PPX Priority Parcel Express（默认）、PDX Priority Document Express、PLX Priority Letter Express（0.5 kg 以下的文件）、DPX Value Express Parcels、EPX Economy Parcel Express、EDX Economy Document Express、GPX Ground Parcel Express 或 GDX Ground Document Express。
Domestic service: 在发货国境内寄送的 Aramex 产品：ONP Overnight (Parcel)（默认）、OND Overnight (Document)、SMP Same Day (Parcel)、SMD Same Day (Document)、SDD Same Day Delivery、EMD Early Morning Delivery、PEC Economy Delivery、PEX Road Express 或 HVY Heavy（20 kg 及以上）。
Payment type: 由谁向 Aramex 支付运费：Prepaid (shipper pays)（默认）、Collect (receiver pays) 或 Third party。通常为 Prepaid。
API weight unit: 发送给 Aramex 的重量单位：Kilograms (KG)（默认）或 Pounds (LB)。商品重量按其重量单位转换，尺寸按其长度单位转换。计费重量为实际重量与体积重量（长 × 宽 × 高（厘米）/ 5000）中的较大者。最低为 0.5 kg，对于没有重量的商品也同样适用。
Currency conversion rate: 系统会要求 Aramex 以您店铺的默认货币报价。如果它仍以其他货币回复，则运费将乘以此数字（Aramex 货币的 1 个单位 = 您店铺默认货币的 X 个单位）。留空则拒绝此类报价，从而确保顾客绝不会以错误的货币被收费。
发货地址（用于实时运费）
Origin country: 您发货所在的国家。第一个选项 Store country 使用您店铺所在的国家。
Origin city: 您发货所在的城市。Aramex 要求填写。OpenCart 中的店铺地址是自由文本，因此城市不会从那里获取：请在此处填写。
Origin state / emirate: 可选。
Origin postcode: 可选。
如果发货国是您店铺所在的国家，则留空的省/州将取自 System > Settings > Store > Local 中店铺所在的地区。
固定价格（当 Shipping cost 为 Fixed prices 时使用，并作为实时运费的备用方案）
Price per country: 以您店铺默认货币计价（不含税）的国家与价格列表。点击 Add country 添加一行，点击 × 按钮删除一行。选择 * All other countries 可为没有自己专属行的所有国家设置一个通用价格。没有价格的国家（当不存在 * 行时）不会获得固定运费，因此该配送方式对它们隐藏。
Fixed price applies: Per order（默认）按订单收取一次价格。Per item (price × quantity) 则按购物车中的商品件数相乘。Aramex 实时运费始终按运单计算。
Conditions
Minimum weight (kg): 购物车重量低于此值时隐藏该配送方式。0 表示无限制（默认）。
Maximum weight (kg): 购物车重量高于此值时隐藏该配送方式。默认：100。0 表示无限制。如果此字段留空，则使用 100 kg。
Minimum order amount: 仅当需要配送的商品小计（优惠券折扣之后、税前）达到此金额时才显示该配送方式。留空则始终显示。
Free shipping: 从下方金额起开启 Aramex 免运费。
Free shipping from: 需要配送的商品小计（优惠券折扣之后、税前），达到此金额即免运费。仅在 Free shipping 开启时使用。
Tax class: 运费的税类，或 No tax（默认）。Aramex 实时运费可能已包含增值税。在这种情况下，请选择 No tax，以免对运费重复征税。
Geo zone: 仅对此地理区域内的地址提供 Aramex。All zones（默认）表示无限制。地理区域在 System > Localisation > Geo Zones 中管理。
Countries: 仅对这些目的国家提供 Aramex。留空则允许所有国家。此限制与 Geo zone 共同生效。
高级
Debug log: 将运费计算和 API 错误写入 storage/logs/vfd_armx_debug.log.php。该文件无法通过网页读取。密码、PIN 码和顾客地址绝不会写入日志。完成后请关闭日志。当文件达到 5 MB 时，它会被移至 vfd_armx_debug.old.log.php，并开始新的日志。
Log: 显示调试日志的大小和最新条目。点击 Clear log 可将其清空。
Remove data on uninstall: 开启时，卸载扩展会删除 Aramex 设置、缓存的运费和日志。关闭时（默认），这些数据会被保留，以便重新安装。
导入 / 导出
导出：点击 Download JSON，将设置保存为 JSON 文件。密码和 PIN 码不会被导出。
导入：粘贴之前导出的 JSON，然后点击 Import 以恢复设置，例如在另一家店铺中使用。这些值会像正常保存时一样进行检查。已保存的密码和 PIN 码会被保留。
结账时的工作方式
OpenCart 显示配送方式时，会向扩展请求 Aramex 的价格。如果设置了 Geo zone，且地址不在该区域内，则不提供 Aramex。只有 Requires Shipping 设为 Yes 的商品才会计入：其他商品不增加重量，也不计入订单金额。然后扩展检查各项条件：允许的国家、购物车重量和最低订单金额。订单金额是需要配送的商品的价格，在扣除优惠券折扣之后、税前计算。礼品卡、奖励积分和店铺余额不计在内。如果适用免运费，则价格为 0，并且不会向 Aramex 发送请求。
在固定价格模式下，价格从表格中获取。在实时运费模式下，扩展会向 Aramex 发送发货地址和收货地址、计费重量、服务以及您的默认货币，并使用返回的总价。只有当收货地址包含城市或邮政编码时，才会请求实时运费。价格以您的默认货币计算，按其小数位数取整，并以顾客的货币显示，同时包含所选 Tax class 的税费。
每个响应缓存 1 小时，因此同一购物车不会触发新的请求。失败的请求缓存 10 分钟，这样结账页面就不必在每次刷新时都等待 Aramex。API 超时时间为 10 秒。
如果 Aramex 返回错误、零金额，或在没有汇率的情况下返回其他货币的报价，顾客不会看到任何错误。该配送方式会被隐藏，或在备用模式下使用固定价格。原因会写入调试日志。
本扩展仅计算运费。它不会创建 Aramex 运单、打印面单、预约取件、追踪包裹，也不允许顾客选择 Aramex 网点。它不会向订单添加任何内容：订单显示配送方式名称和运费，与任何其他 OpenCart 配送方式一样。包裹始终作为一件发送给 Aramex。
在 OpenCart 4 上，顾客在结账页面的配送方式块中点击 Choose，并在 Shipping method options 窗口中选择 Aramex。该配送方式的工作方式与 OpenCart 3 相同。
许可证密钥
本扩展需要一个来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox Aramex 许可证块是 Extensions > Extensions > Shipping > VibeFox Aramex > Edit 页面中位于设置上方的第一个块。将密钥粘贴到 License key 中并点击 Activate。之后，该块会以隐藏形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now 用于再次检查状态，Change key 用于输入其他密钥，Remove key 用于从本店铺移除密钥。其下方是 Product: opencart-shipping-aramex 一行和 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 账户中释放名额。
没有有效的密钥，Aramex 配送方式不会在结账时显示给顾客，也不计算运费。在同一浏览器中已登录后台的管理员用户仍可在商店中看到该方式，并标记为 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试扩展。在 OpenCart 4 上此预览不可用：商店看不到后台登录状态，因此没有有效密钥时，该方式对所有人隐藏。您打开过一次 Edit 页面后，后台 Dashboard 上会出现提醒。点击 × 可将其关闭 7 天。现有订单不受影响。
许可证过期后，扩展仍会继续运行，但更新和支持需要续费。打开后台 Dashboard 或 Edit 页面时会自动再次检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展时，许可证密钥和许可证状态始终会被删除。
故障排除
Aramex 未在结账时出现：请检查许可证是否有效，以及 Enable Aramex 是否开启。检查 Geo zone、Countries、重量限制和 Minimum order amount。在固定价格模式下，检查该国家或 * All other countries 是否设置了价格。检查商品的 Requires Shipping 是否设为 Yes。
实时运费未出现：开启 Debug log，重新加载结账页面，并查看扩展页面上的 Log 字段。它会显示原因：缺少 API 凭据、Aramex 错误代码、没有发货城市、没有收货城市或邮政编码、重量或金额限制，或以其他货币报价。使用 Aramex live rates, fixed prices if the API fails，在您解决问题期间，顾客仍会获得固定价格。
日志中的错误 ERR75：Aramex 拒绝了登录。请与您的 Aramex 客户经理核对用户名、密码、账户号码、PIN 码、实体和国家代码。
其他货币的报价被拒绝：Aramex 以不同于您默认货币的货币回复。请输入 Currency conversion rate，或要求 Aramex 以您的货币报价。
运费被重复征税：Aramex 的总额可能已包含增值税。请将 Tax class 设为 No tax。
更改后运费看起来过时：在扩展页面点击 Save。这会清除缓存的 Aramex 运费。
页面提示 "Warning: You do not have permission to modify VibeFox Aramex!"：您的管理员用户组可能只有查看设置的权限。请在 System > Users > User Groups 中为该组授予对 extension/shipping/vfd_aramex（OpenCart 3）或 extension/vfd_aramex/shipping/vfd_aramex（OpenCart 4）的修改权限。
面向开发人员：可以使用设置 vfd_armx_api_url（用于测试）替换 Aramex API 地址；设置页面上没有该项的输入框。
卸载
进入 Extensions > Extensions，选择类型 Shipping，然后点击 VibeFox Aramex 旁边的 Uninstall（红色 − 按钮）。OpenCart 始终会重置 Enable Aramex、Sort order、Tax class 和 Geo zone。缓存的运费始终会被删除。如果 Remove data on uninstall 开启，Aramex 设置和调试日志也会被删除。如果关闭，其他设置会被保留，并在您重新安装扩展时再次使用。现有订单保留其配送方式和费用。
在 OpenCart 4 上，如果还要删除扩展的文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox Aramex 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。
Aramex 是其各自所有者的商标。本扩展与 Aramex 无关联，也未获得 Aramex 的认可。