VibeFox iMile for WooCommerce — 帮助
系统要求
WordPress：5.8 或更高版本。
WooCommerce：5.0 或更高版本，已安装并启用。未安装时插件无法激活。
PHP：8.0 或更高版本。
iMile 运费表：您与 iMile 销售团队约定的价格。请以店铺货币将其录入价格表。
iMile API 账户（仅用于实时估价）：实时估价使用 iMile OpenAPI 的「Estimated order delivery costs」接口。您需要 Customer ID 和 Secret key（iMile 随 Customer ID 一同签发的 API 密钥）。如需测试客户端，请在 iMile 开发者门户（developer.imile.com）注册。正式密钥由您的 iMile 客户经理提供。如果您只使用价格表，则无需 API 密钥。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 vfd_imile 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Shipping > VibeFox iMile，或在插件页面中点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 在 Price table 中填写您的 iMile 价格。可选择填写 Live rates (API) 部分，并开启 Live estimate（参见「配置」）。
6. 在 WooCommerce > Settings > Shipping > Shipping zones 中，将 VibeFox iMile 添加到某个配送区域（例如「United Arab Emirates」），或开启 Ignore shipping zones 并选择国家。
配置
所有设置都位于同一页面：WooCommerce > Settings > Shipping > VibeFox iMile。这些设置适用于所有配送区域。将该方式添加到某个区域时，区域窗口中只有一个字段：
Title (zone)：顾客在该区域看到的名称。留空则使用全局的 Method title。
每次保存设置时，已缓存的 iMile 估价和访问令牌都会被清除。如果实时估价已开启但无法正常工作（没有密钥、没有发货城市或国家、没有汇率、价格表为空），设置页面上方会显示警告。
常规
Enable/Disable：一次性在所有区域中启用或禁用该方式。
Method title：购物车和结账页面中显示的配送方式名称。区域可以覆盖此名称。默认：iMile。
实时运费（API）（可选）
如果 iMile 未返回估价（没有密钥、尚未输入城市、出错、超时、没有汇率），则使用价格表。
Live estimate：开启后可从 iMile 获取配送费用。默认：关闭。关闭实时估价时，结账期间不会向 iMile 发送任何数据。
Environment：Production (openapi.imile.com)（默认）或 Test (test-openapi.52imile.cn)。测试密钥仅适用于测试服务器，且只会返回测试价格。
Customer ID：iMile 签发的客户代码（customerId），例如 C2102192601。
Secret key：iMile 随 Customer ID 一同签发的密钥（API 密钥）。用于对请求进行签名。
Signature：请求的签名方式。
Ship-from country：您发货所在的国家。默认为您店铺所在的国家。列表中包含插件已具备 iMile 国家代码的国家。
Ship-from city：包裹的发货城市，拼写需与 iMile 城市列表一致（例如 Dubai、Riyadh）。留空则使用 WooCommerce > Settings > General 中设置的店铺城市。
Ship-from province：可选，例如 Dubai 或 Riyadh Province。
iMile service：发送给 iMile 的订单类型：Delivery order (100)（默认）或 Express order (1100)。Express 需要您的账户和国家已开通。
Goods category：发送给 iMile 的货物类型：Normal goods（默认）、Sensitive (cosmetics, liquids...)、With battery、Batteries / power banks、Documents 或 Parcel。
Exchange rates：iMile 以目的国家的货币给出估价。每种货币填写一行，写明 1 个单位对应的店铺货币价格，例如「AED = 0.25」或「SAR = 0.24」。小数点和逗号均可作为小数分隔符。店铺货币本身无需汇率。没有汇率时，该货币的估价不会被使用，而改用价格表。同一汇率也用于将购物车价值换算后申报给 iMile。保存时会删除无效的行。
价格（实时估价关闭时使用，以及在 iMile 未返回估价时作为备用）
请以店铺货币输入您的 iMile 运费。如果运费以 AED、SAR 或其他货币计价，请先换算。
Price table：每个目的国家一行。点击 + Add country 添加一行，点击叉号删除。选择 * All other countries 可设置一行，覆盖所有没有单独设置行的国家。每行包含一个 Base price 以及可选的重量列：XS ≤1 kg、S ≤2 kg、M ≤3 kg、L ≤5 kg 和 XL >5 kg。重量列为空（或为 0）时使用基础价格。基础价格为 0 表示向该国家免运费。「9.99」和「9,99」均可接受。保存时，没有价格的行、无效的国家代码和负价格会被删除。每个国家只保留一行。
Price for countries not in the table：以店铺货币表示的价格。当表格中没有目的国家的行（也没有 * 行），或该行对此重量没有价格时使用。留空则在这种情况下隐藏该方式。
Price applies：表格价格的计费方式。
实时估价也采用相同的选择：按订单会将整个购物车作为一个包裹发送；按商品则会针对每个不同的包裹分别查询，并乘以件数。如果购物车中包含超过 5 个不同的包裹，则使用价格表。
商品重量会从店铺的重量单位换算为千克。
条件
Minimum weight (kg)：购物车重量小于此值时隐藏该方式。0 表示不设限制。
Maximum weight (kg)：购物车重量大于此值时隐藏该方式。默认：30。0 表示不设限制。
Minimum order amount：仅当购物车小计（折扣后、税前）达到此金额时才显示该方式。留空则始终显示。
Free shipping from：购物车小计（折扣后、税前）达到此金额时，iMile 配送免运费。留空则从不提供免运费。
Excluded shipping classes：购物车中包含这些 WooCommerce 配送类别中任一类别的商品时，隐藏该方式。
Tax status：Taxable 会将 WooCommerce 税费加到配送费用上；None 则不加。如果价格表中的价格和 iMile 估价已包含增值税，请选择 None。
不使用配送区域时的可用性
Ignore shipping zones：即使该方式未添加到任何配送区域，也为下方列出的国家提供 iMile。
Countries：该模式下的目的国家。留空则使用您配送的所有国家。此字段仅在开启 Ignore shipping zones 时使用。
高级
Debug log：将运费计算记录到 WooCommerce > Status > Logs（来源为「vfd_imile」）。不记录密钥和顾客地址。即使关闭调试日志，失败的 iMile 请求也始终会被记录。完成后请关闭日志。
Remove data on uninstall：开启后，删除插件将移除所有 iMile 设置、区域方式和已缓存的估价。停用插件则不会删除任何内容。
结账时的工作方式
当顾客输入配送地址时，WooCommerce 会向插件请求运费。插件首先检查各项条件：配送国家、购物车重量、最低订单金额和排除的配送类别。如果适用免运费，顾客将免费看到该方式，并且不会向 iMile 发送任何请求。
开启实时估价后，插件会向 iMile 发送发货国家、省份和城市，目的国家、州/省、城市和邮编，购物车重量（千克），尺寸（立方厘米，根据商品尺寸计算），购物车价值，iMile 服务和货物类别。估价始终以预付款方式请求，因此不包含货到付款费用。只有在顾客输入城市且每个包裹都有重量后，才会请求实时估价。每个结果缓存 1 小时。失败的请求缓存 5 分钟。超时或服务器错误后 2 分钟内不再请求 iMile，密钥被拒绝后 5 分钟内不再请求，从而确保结账时不会在每次刷新时都等待 iMile。API 超时时间为 12 秒。过期的访问令牌会自动续期。
估价会根据您设置的汇率换算为店铺货币。如果 iMile 无法给出可用的估价（未设置密钥、尚未输入城市、城市未知、出错、超时、没有汇率），顾客不会看到错误，而是使用价格表中的价格。如果价格表中也没有价格，则隐藏该方式。原因会写入日志。
该方式适用于经典结账以及购物车和结账区块。兼容 WooCommerce 高性能订单存储（HPOS）。
插件仅计算运费。它不会创建 iMile 运单，不打印 AWB 标签，不预约取件，不追踪包裹，不核对货到付款款项，也不提供自提点或智能柜。发货请使用 iMile 门户。
许可证密钥
插件需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Shipping > VibeFox iMile 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。区块会显示状态，例如许可证有效期截止日期以及您的域名。使用 Check now 重新检查状态，Change key 输入其他密钥，Remove key 将其从本站点移除。Manage licenses and domains in your account 链接会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。将密钥从站点移除并不会释放域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，iMile 不会在结账时向顾客显示。已登录的店铺管理员仍可看到，并标注为 (unlicensed — visible to admins only)，因此您可以在购买密钥前完成设置和测试。插件页面和 WooCommerce 页面上会显示提醒。现有订单不受影响。
许可证到期后，插件仍可继续运行，但更新和技术支持需要续费。系统会在后台自动重新检查状态。
故障排除
结账时不显示 iMile：请检查许可证是否有效、Enable/Disable 是否已开启、该方式是否已添加到顾客所在国家的区域中（或 Ignore shipping zones 已开启且该国家被允许）。检查重量限制、Minimum order amount 和 Excluded shipping classes。检查该国家或 * 在 Price table 中是否有一行，或 Price for countries not in the table 是否已设置。
显示的是价格表价格而非 iMile 估价：打开 WooCommerce > Status > Logs，选择来源「vfd_imile」，并开启 Debug log 查看详细信息。常见原因包括：Live estimate 已关闭、缺少密钥、顾客尚未输入城市、iMile 无法识别城市拼写、商品没有重量、目的货币没有汇率，或出现 API 错误。另请查看设置上方的警告。
日志中出现「sign is invalid」：请检查 Secret key，然后尝试将 Signature 设为 SimpleKey。
密钥被拒绝：请检查 Customer ID、Secret key 和 Environment。测试密钥仅适用于测试服务器。
城市名称不匹配：城市名称必须与 iMile 城市列表一致。开发者可以使用 vfd_imile_live_request 过滤器进行映射，使用 vfd_imile_live_country_code 过滤器映射国家代码。
价格货币错误：价格表以店铺货币（WooCommerce > Settings > General）计价。录入 AED、SAR 或 MXN 运费时请先换算。实时估价通过 Exchange rates 进行换算。
配送费被重复征收税费：如果您的价格已包含增值税，请将 Tax status 设为 None。
修改后估价似乎过时：保存设置页面即可清除已缓存的 iMile 估价。
许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在另一个域名上使用，请在您的 vibefox.net 账户中释放名额，然后点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活密钥。如果无法连接许可证服务器，插件将沿用最后已知的状态继续运行。
卸载
停用插件会保留所有数据。如需移除，请先停用，然后在 Plugins 页面中删除。本插件的许可证密钥和许可证状态始终会被移除。只有在启用了 Remove data on uninstall 的情况下，设置、区域方式和已缓存的估价才会被移除；否则将保留，以便日后重新安装时使用。现有订单会保留其配送行。
iMile 是其各自所有者的商标。本插件与 iMile 无关联，也未获得 iMile 认可。