VibeFox Aramex for WooCommerce — 帮助
系统要求
WordPress：5.8 或更高版本。
WooCommerce：5.0 或更高版本，已安装并启用。未安装时插件无法激活。
PHP：8.0 或更高版本。
Aramex 账户（仅用于实时运费）：实时运费使用 Aramex Rate Calculator API。Aramex 向其账户持有人开放 API 访问权限。请咨询您的 Aramex 客户经理，或参见 Aramex 官网上的 Aramex Developers Solution Center。您需要六个参数：API 用户名（通常为电子邮件地址）、密码、账号、账户 PIN 码、账户所属机构（例如 DXB）和账户国家代码（例如 AE）。如果您仅按国家使用固定价格，则无需 Aramex 账户。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥仅适用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 vfd_aramex 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Shipping > VibeFox Aramex，或在插件页面中点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 选择运费的计算方式，并填写相应的设置区块（参见「配置」）。
6. 在 WooCommerce > Settings > Shipping > Shipping zones 中将 VibeFox Aramex 添加到某个配送区域，或开启 Ignore shipping zones 并选择国家。
配置
所有设置都在同一页面：WooCommerce > Settings > Shipping > VibeFox Aramex。这些设置适用于所有配送区域。将此方式添加到某个区域时，区域窗口中只有一个字段：
Title (zone): 顾客在此区域看到的名称。留空则使用全局的 Method title。
每次保存设置时，已缓存的 Aramex 运费都会被清除。
常规
Enable/Disable: 一次性在所有区域开启或关闭此方式。
Method title: 购物车和结账页面中显示的配送方式名称。默认：Aramex。
Shipping cost: 价格的计算方式。
实时运费缺失的原因会写入调试日志，且绝不会显示给顾客。
Aramex API 账户（仅实时运费需要；六个字段均为必填）
Username: 您的 Aramex API 用户名，通常为电子邮件地址。
Password: 您的 Aramex API 密码。
Account number: 您的 Aramex 客户账号。
Account PIN: 您 Aramex 账户的 PIN 码。
Account entity: 您账户所属的 Aramex 机构（办事处）代码，例如 DXB、AMM 或 RUH。
Account country code: 您 Aramex 账户的 2 位国家代码，例如 AE。
Aramex 服务（用于实时运费）
若收货地址位于发货国，则按国内（Domestic）报价。其他所有运单均按国际特快（International express）报价。
International service: 寄往国外的 Aramex 产品：PPX Priority Parcel Express（默认）、PDX Priority Document Express、PLX Priority Letter Express、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 公斤及以上）。
Payment type: 由谁向 Aramex 支付运费：Prepaid（发件人付款）、Collect（收件人付款）或 Third party（第三方付款）。通常选择 Prepaid。
API weight unit: 发送给 Aramex 的重量单位，KG 或 LB。商品重量会从您店铺的重量单位换算。计费重量为实际重量与体积重量（长 × 宽 × 高，单位为厘米，除以 5000）中的较大者。最低为 0.5 公斤，该下限也适用于未设置重量的商品。
Currency conversion rate: 系统要求 Aramex 以您店铺的货币报价。若其仍以其他货币报价，则将运费乘以此数值（Aramex 货币 1 单位 = 您店铺货币 X 单位）。留空则拒绝此类报价，以确保顾客绝不会以错误的货币被收费。小数分隔符可使用句点或逗号。
发货地址（始发地址）（用于实时运费）
Origin country: 您发货的国家。默认为您的店铺所在国家。
Origin city: 您发货的城市。Aramex 要求填写。
Origin state / emirate: 可选。
Origin postcode: 可选。
若发货国家为您的店铺所在国家，空白字段将取自 WooCommerce > Settings > General 中的店铺地址。
固定价格（用于固定价格模式，以及作为实时运费的备用价格）
Price per country: 由 2 位国家代码和价格（以店铺货币计）组成的表格。点击 Add row 添加国家，点击叉号删除。使用 * 作为国家代码，代表所有其他国家。没有价格的国家（表中没有 * 行时）不会获得固定运费，因此对这些国家隐藏此配送方式。
Fixed price applies: Per order 只收取一次价格。Per item 按购物车中的商品数量乘以价格。实时 Aramex 运费始终按每个运单计算。
条件
Minimum weight (kg): 购物车重量低于此值时隐藏此配送方式。0 表示不限制。
Maximum weight (kg): 购物车重量高于此值时隐藏此配送方式。默认：100。0 表示不限制。
Minimum order amount: 仅当购物车小计（折扣后、税前）达到此金额时才显示此配送方式。留空则始终显示。
Excluded shipping classes: 购物车中包含属于这些 WooCommerce 配送类别的任何商品时，隐藏此配送方式。
Free shipping: 开启后，从下方金额起提供 Aramex 免运费配送。
Free shipping from: 购物车小计（折扣后、税前）达到此金额时免运费。仅在 Free shipping 开启时使用。
Tax status: Taxable 会在运费上加收 WooCommerce 税费，None 则不加收。Aramex 实时运费可能已包含增值税（VAT）。在这种情况下，请选择 None，以免重复征税。
无配送区域时的可用性
Ignore shipping zones: 即使此配送方式未添加到任何配送区域，也为下方指定的国家提供 Aramex 配送。
Countries: 该模式下的目的国家。留空则使用您配送到的所有国家。仅在 Ignore shipping zones 开启时使用此字段。
高级
Debug log: 将运费计算和 API 错误写入插件文件夹中的 logs/vfd_armx_debug.log.php。该文件无法通过网页打开。密码、PIN 码、账号和顾客地址会被隐藏。完成后请关闭日志。
Remove data on uninstall: 开启时，删除插件会移除其所有设置、区域配送方式、缓存的运费和日志。停用插件绝不会删除任何数据。
结账时的工作方式
顾客输入收货地址时，WooCommerce 会向插件请求运费。插件首先检查条件：收货国家、购物车重量、最低订单金额和排除的配送类别。若适用免运费，顾客将看到 Aramex (free) 方式，且不会向 Aramex 发送请求。
固定价格模式下，价格取自表格。实时模式下，插件会向 Aramex 发送发货地址和收货地址、计费重量、服务以及您店铺的货币，并显示返回的总价。只有在顾客输入城市或邮政编码后才会请求实时运费。每个结果缓存 1 小时，因此同一购物车不会触发新的请求。失败的请求缓存 10 分钟，因此结账页面每次刷新时都不必等待 Aramex 响应。API 超时时间为 10 秒。
若 Aramex 返回错误、零金额，或返回未设置汇率的其他货币报价，顾客不会看到任何错误提示。该配送方式将被隐藏；若为备用模式，则改用固定价格。原因会写入调试日志。
此方式支持经典结账，以及购物车和结账区块。兼容 WooCommerce 高性能订单存储（HPOS）。
插件仅计算运费。它不会创建 Aramex 运单、打印面单、预约取件、跟踪包裹，也不允许顾客选择 Aramex 网点。包裹始终作为一件货物发送至 Aramex。
许可证密钥
本插件需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Shipping > VibeFox Aramex 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期截止日期以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从本站点移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。
一个密钥仅适用于一个域名。从站点移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效的密钥时，结账时不会向顾客显示 Aramex。已登录的店铺管理员仍可看到它，并标注 (unlicensed — visible to admins only)，以便您在购买密钥前设置和测试插件。插件页面和 WooCommerce 页面上会显示提醒。现有订单不受影响。
许可证到期后，插件仍可继续使用，但更新和支持需要续费。系统会在后台自动重新检查状态。
故障排除
结账时未显示 Aramex：请检查许可证是否有效、Enable/Disable 是否开启，以及该方式是否已添加到顾客所在国家的配送区域（或已开启 Ignore shipping zones 且该国家已被允许）。检查重量限制、Minimum order amount 和 Excluded shipping classes。在固定价格模式下，请检查该国家或 * 是否设有价格。
未显示实时运费：开启 Debug log，重新加载结账页面，然后打开插件文件夹中的 logs/vfd_armx_debug.log.php。日志会显示原因：缺少 API 凭据、Aramex 错误代码、缺少发货城市、尚未填写收货城市或邮政编码、重量或金额限制，或其他货币报价。使用 Aramex live rates, fixed prices if the API fails 时，在您解决问题期间，顾客仍会看到固定价格。
日志中的错误 ERR75：Aramex 拒绝了登录。请与您的 Aramex 客户经理核对用户名、密码、账号、PIN 码、机构代码和国家代码。
其他货币的报价被拒绝：Aramex 以非店铺货币的其他货币报价。请填写 Currency conversion rate，或要求 Aramex 以您的货币报价。
运费被重复征税：Aramex 的总价可能已包含增值税。请将 Tax status 设为 None。
修改后运费显示过期：保存设置页面。这将清除已缓存的 Aramex 运费。
Aramex 沙盒：插件使用正式环境的 Aramex Rate Calculator。开发者可以通过 vfd_armx_api_url 过滤器更改端点。过滤器 vfd_armx_rate_request、vfd_armx_number_of_pieces 和 vfd_armx_volumetric_divisor 用于调整请求、件数和体积重量除数。
许可证区块显示错误：请按照区块中的提示操作。例如，若该密钥已在其他域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。若站点地址已更改，请点击 Check now，为新域名激活密钥。若无法连接许可证服务器，插件将继续使用最后已知的状态。
卸载
停用插件会保留所有数据。要移除插件，请先停用，然后在 Plugins 页面将其删除。本插件的许可证密钥和许可证状态始终会被移除。设置、区域配送方式、缓存的运费和日志仅在开启了 Remove data on uninstall 时才会被移除。否则它们将保留，以便日后重新安装时使用。现有订单保留其配送明细。
Aramex 是其各自所有者的商标。本插件与 Aramex 无关联，也未获得 Aramex 认可。