VibeFox iMile for OpenCart — 帮助

系统要求

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

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 购买。一个密钥仅适用于一个域名。

安装

下载内容是一个 zip 压缩包，包含两个 OpenCart 版本的安装包。请先解压到您的电脑上。其中包含 README.txt、OpenCart 3 安装包 vfd_imile-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 vfd_imile.ocmod.zip。只安装适合您 OpenCart 版本的安装包。两个版本使用相同的许可证密钥。

OpenCart 3

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

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

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

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

5. 在 Price table 中输入您的 iMile 价格。如需要，可填写 Live rates (API) 部分并开启 Live estimate（参见配置）。开启 Enable iMile 并点击 Save。

OpenCart 4

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

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

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

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

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

配置

所有设置都在扩展页面中：Extensions > Extensions > Shipping > VibeFox iMile > Edit。各部分列在左侧。点击一个 Save 按钮可保存整个页面，无需重新加载。每次保存还会清除缓存的 iMile 估价和访问令牌。只有拥有本扩展修改权限的管理员用户才能保存设置。

保存时，扩展会检查：Method title 是否有效（最多 64 个字符，且不含 < > ; = # { } 字符）；价格、金额和重量字段是否为 0 或更大的数字；Minimum weight (kg) 是否不大于 Maximum weight (kg)；Sort order 是否为整数；税类和地理区域是否存在。否则会显示错误且不保存任何内容。

当 Live estimate 已开启但无法工作时，设置上方会出现警告（保存后也会再次出现）：Customer ID 或 Secret key 为空；发货城市或国家/地区缺失（或该国家/地区不是 iMile 市场）；没有汇率；或价格表为空且没有其他国家/地区的价格。如果店铺没有以 kg 为单位的重量等级，并且默认重量等级的单位不被扩展识别，也会出现警告：此时商品重量按千克计算，因此请在 System > Localisation > Weight Classes 中添加一个 kg 重量等级。

常规

这些设置适用于所有地理区域。您可以在 Conditions 中将该方式限制在某个地理区域内，或在 Countries 中开启 Ignore shipping zones，以将其限制为一组国家/地区。

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

Method title：在购物车和结账时向顾客显示的配送方式名称。默认：iMile。必填。

Sort order：iMile 在结账时各配送方式中的位置。整数。

实时费率 (API)（可选）

如果 iMile 未返回估价（没有密钥、尚未输入城市、出错、超时、没有汇率），则使用价格表。

Live estimate：开启后，可从 iMile 获取运费。默认：关闭。关闭实时估价时，结账期间不会向 iMile 发送任何内容。

Environment：Production (openapi.imile.com)（默认）或 Test (test-openapi.52imile.cn)。测试密钥仅适用于测试服务器，并给出测试价格。

Customer ID：iMile 颁发的客户代码（customerId），例如 C2102192601。清空该字段也会清除已保存的 Secret key。

Secret key：iMile 与 Customer ID 一并颁发的密钥（API 密钥）。它为请求签名。保存后，该字段保持为空并显示 Saved — leave empty to keep it. 仅在需要更改时才输入新值。

Signature：请求的签名方式。

Ship-from country：您发货所在的国家/地区。第一个选项 Store country 使用您店铺所在的国家/地区。列表中仅包含扩展已有 iMile 国家代码的国家/地区。

Ship-from city：包裹发出的城市，拼写须与 iMile 城市列表一致（例如 Dubai、Riyadh）。实时估价必须填写：OpenCart 没有店铺城市，因此如果不填此字段，将只使用价格表。

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 个不同的包裹，则使用价格表。

商品重量会从 OpenCart 的重量等级换算为千克，尺寸会从其长度等级换算为厘米。

条件

Minimum weight (kg)：购物车重量低于此值时隐藏该方式。0 表示无限制（默认）。

Maximum weight (kg)：购物车重量高于此值时隐藏该方式。默认：30。0 表示无限制。如果留空，则使用 30 kg。

Minimum order amount：仅当需要配送的商品小计（使用优惠券后、税前）达到此金额时才显示该方式。留空则始终显示。

Free shipping from：需要配送的商品小计（使用优惠券后、税前）达到此金额时，iMile 配送免费。留空则从不提供免运费。

Tax class：运费的税类，或 No tax（默认）。如果价格表中的价格和 iMile 估价已包含增值税，请选择 No tax。

Geo zone：仅对该地理区域内的地址提供 iMile。All zones（默认）表示无限制。开启 Ignore shipping zones 时不检查地理区域。地理区域在 System > Localisation > Geo Zones 中管理。

国家/地区

Ignore shipping zones：开启时，不检查 Geo zone，并为下方的国家/地区提供 iMile。关闭时（默认），仅应用 Geo zone。

Countries：允许的目的国家/地区。留空则允许店铺中启用的所有国家/地区。仅当 Ignore shipping zones 开启时使用此字段。

高级

Debug log：将费率计算写入 storage/logs/vfd_imile_debug.log.php（OpenCart 4 中为 system/storage/logs/vfd_imile_debug.log.php）。该文件无法通过网页读取。不会记录任何密钥和顾客地址。即使调试日志关闭，失败的 iMile 请求也始终会被记录。使用完毕后请关闭日志。当文件达到 5 MB 时，它会被移动到 vfd_imile_debug.old.log.php，并开始新的日志。

Log：显示调试日志的大小和最新条目。点击 Clear log 可清空日志。

Remove data on uninstall：开启时，卸载扩展会删除 iMile 设置和日志。关闭时（默认），设置会保留以便重新安装。缓存的估价和访问令牌始终会被删除。

导入 / 导出

Export：点击 Download JSON，将设置保存为 JSON 文件。Secret key 不会被导出。

Import：粘贴之前导出的 JSON，然后点击 Import 恢复设置，例如在另一家店铺中使用。这些值会按照正常保存时的规则进行检查。已保存的 Secret key 会被保留。

结账时的工作方式

OpenCart 显示配送方式时，会向扩展请求 iMile 价格。如果设置了 Geo zone，Ignore shipping zones 关闭，并且地址位于地理区域之外，则不提供 iMile。只有 Requires Shipping 设为 Yes 的商品才计入：其他商品不增加重量，也不计入订单金额。随后扩展检查各项条件：允许的国家/地区（当 Ignore shipping zones 开启时）、购物车重量和最低订单金额。订单金额是需要配送的商品在优惠券折扣之后、税前的价格。礼品卡、积分和店铺余额不计入其中。如果适用免运费，则价格为 0，并且不会向 iMile 发送请求。

实时估价开启时，扩展会向 iMile 发送发货国家/地区、省/州和城市，目的国家/地区、地区、城市和邮编，以千克计的购物车重量，以立方厘米计的尺寸（根据商品尺寸计算），购物车价值，iMile 服务以及货物类别。估价总是按预付款方式请求，因此不包括货到付款的费用。只有在顾客输入了带城市的收货地址，并且购物车中每件商品都有重量之后，才会请求实时估价。

每个响应缓存 1 小时。失败的请求缓存 5 分钟。发生超时或服务器错误后，2 分钟内不再向 iMile 请求；密钥被拒绝后，5 分钟内不再请求，以免结账页面在每次刷新时都等待 iMile。API 超时时间为 12 秒。过期的访问令牌会自动续期。

估价会使用您设置的汇率换算为店铺默认货币。如果 iMile 未给出可用的估价（未设置密钥、尚未输入城市、城市未知、出错、超时、没有汇率），顾客不会看到错误，而是使用价格表中的价格。如果价格表中也没有价格，则隐藏该方式。原因会被记录到日志中。价格以您的默认货币计算，按其小数位数四舍五入，并以顾客的货币显示，税率为所选 Tax class 的税率。

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

本扩展仅计算费率。它不创建 iMile 运单，不打印 AWB 面单，不预约取件，不追踪包裹，不核对货到付款款项，也不提供自提点或智能柜。它不会向订单添加任何内容：订单会像其他任何 OpenCart 配送方式一样显示配送方式名称和运费。运单请使用 iMile 门户。

许可证密钥

本扩展使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox iMile 位于 Extensions > Extensions > Shipping > VibeFox iMile > Edit 页面中设置上方，是第一个区块。在 License key 中输入密钥并点击 Activate。之后，该区块会以隐藏方式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（再次检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺移除密钥）。其下方是 Product: opencart-shipping-imile 一行和 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 账户中释放名额。

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

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

故障排除

结账时未显示 iMile：请检查许可证是否有效，以及 Enable iMile 是否已开启。检查 Geo zone、Ignore shipping zones 和 Countries、重量限制以及 Minimum order amount。检查该国家/地区或 * All other countries 是否在 Price table 中有一行，或者是否已设置 Price for countries not in the table。检查商品的 Requires Shipping 是否设为 Yes。

显示的是价格表价格而不是 iMile 估价：开启 Debug log，重新加载结账页面，并查看扩展页面上的 Log 字段。常见原因：Live estimate 关闭、缺少密钥、Ship-from city 为空、顾客尚未输入城市、iMile 不识别城市拼写、商品没有重量、目的货币没有汇率，或出现 API 错误。另请检查设置上方的警告。

日志中出现 "sign is invalid"：请检查 Secret key，然后尝试将 Signature 设为 SimpleKey。

密钥被拒绝：请检查 Customer ID、Secret key 和 Environment。测试密钥仅适用于测试服务器。

城市名称不匹配：城市名称必须与 iMile 城市列表一致。开发人员可以通过 OpenCart 事件 vfd_imile/live_request 修改请求，并通过事件 vfd_imile/live_country_code 修改国家代码。

价格货币错误：价格表以店铺默认货币表示。输入 AED、SAR 或 MXN 的费率时请先换算。实时估价则通过 Exchange rates 进行换算。

运费被重复征税：如果您的价格已包含增值税，请将 Tax class 设为 No tax。

更改后估价似乎过时：在扩展页面点击 Save。这将清除缓存的 iMile 估价。

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

卸载

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

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

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