VibeFox iMile for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝安装在较旧的 PHP 版本上。
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. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或之后在模块列表中找到 VibeFox iMile 并点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥粘贴到 License key 中，然后点击 Activate（参见“许可证密钥”）。
4. 在 Price table 中输入您的 iMile 价格。可选择填写 Live rates (API) 部分，并开启 Live estimate（参见配置）。点击 Save。
安装时，模块会创建 iMile 承运商，配送时效文字为 Courier delivery。该承运商会分配给所有区域和所有客户组。您可以在 Shipping > Carriers 中修改区域、客户组、配送时效、标志和尺寸限制。请不要在那里设置价格：价格始终来自模块。
配置
所有设置都在模块页面中：Modules > Module Manager > VibeFox iMile > Configure。设置适用于承运商的每个区域。每个部分都有各自的 Save 按钮，点击后会保存整个页面。每次保存也会清除缓存的 iMile 估价和访问令牌。
当 Live estimate 已开启但无法工作时，设置上方会显示警告：Customer ID 或 Secret key 为空，缺少发货城市或国家（或该国家不是 iMile 市场），没有汇率，或价格表为空且没有其他国家的价格。当模块无法识别店铺的重量单位时也会显示警告：此时商品重量按千克计算，因此请在 International > Localization（Local units）中设置单位。保存时，模块会检查 Method title 是否有效（最多 64 个字符），金额和重量字段是否为 0 或更大的数字，Minimum weight 是否不大于 Maximum weight，以及税务规则是否存在。否则会显示错误，且不保存任何内容。
常规
Enable iMile: 开启或关闭该承运商。这与 Shipping > Carriers 中的承运商状态使用的是同一个开关。
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。
Secret key: iMile 随 Customer ID 一起签发的密钥（API 密钥）。它用于对请求签名。保存后，该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。
Signature: 请求的签名方式。
Ship-from country: 发货国家，即您寄出包裹所在的国家。默认为您的店铺所在国家（Shop country）。列表仅包含模块拥有 iMile 国家代码的国家。
Ship-from city: 发货城市，即包裹寄出的城市，拼写须与 iMile 城市列表一致（例如 Dubai、Riyadh）。留空则使用 Shop Parameters > Contact > Stores 中的店铺城市。
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 配送免运费。留空则从不提供免运费。
Tax: 承运商的税务规则，或 No tax。如果价格表中的价格和 iMile 估价已包含增值税，请选择 No tax。
无配送区域时的可用性
Ignore shipping zones: 无论匹配哪个区域，都为下列国家提供 iMile。保存时，承运商会被添加到所有区域，之后创建的区域也会自动获得该承运商。关闭此选项会移除这些新增的区域，使承运商恢复其之前拥有的区域。
Countries: 该模式下的目的国家。留空则使用所有启用的国家。仅在 Ignore shipping zones 开启时使用此字段。
高级
Debug log: 将运费计算记录到模块文件夹中的 logs/vfd_imle_debug.log.php。该文件无法通过网页打开。日志中不记录密钥和顾客地址。即使调试日志关闭，失败的 iMile 请求也始终会被记录。完成后请关闭日志。
Log: 显示调试日志的大小和最新记录。点击 Clear log 可清空。
Remove data on uninstall: 开启时，卸载模块会删除 iMile 设置、承运商、缓存的估价和日志。关闭时，所有内容都会保留，以便重新安装。
结账时的工作方式
在配送步骤中，PrestaShop 会向模块请求 iMile 价格。只有实物商品计入：虚拟商品不增加重量，也不计入订单金额。模块首先检查条件：允许的国家（当 Ignore shipping zones 开启时）、购物车重量和最低订单金额。如果适用免运费，价格为 0，且不会向 iMile 发送任何请求。
实时估价开启时，模块会向 iMile 发送：发货国家、省份和城市，目的国家、州/省、城市和邮编，以千克计的购物车重量，以立方厘米计的尺寸（根据商品尺寸计算），购物车价值，iMile 服务和货物类别。估价始终以预付款方式请求，因此不包括货到付款费用。只有在顾客输入了包含城市的配送地址后，并且购物车中每件商品都有重量时，才会请求实时估价。每个响应缓存 1 小时。失败的请求缓存 5 分钟。发生超时或服务器错误后，2 分钟内不再向 iMile 请求；密钥被拒绝后，5 分钟内不再请求，以免结账页面每次刷新都要等待 iMile。API 超时时间为 12 秒。过期的访问令牌会自动更新。
估价会根据您的汇率换算为店铺默认货币。如果 iMile 没有给出可用的估价（未设置密钥、尚未输入城市、城市未知、错误、超时、没有汇率），顾客不会看到错误，而是使用价格表中的价格。如果价格表中也没有价格，则隐藏承运商。原因会写入日志。价格以您的默认货币计算，然后以顾客购物车的货币显示。
如果您在订单产生后于 Shipping > Carriers 中编辑承运商，PrestaShop 会将其保存为新的承运商版本。模块会自动跟随新版本。
模块仅计算运费。它不会创建 iMile 运单，不打印 AWB 标签，不预约取件，不追踪包裹，不核对货到付款款项，也不提供自提点或自提柜。请使用 iMile 门户处理运单。
许可证密钥
模块需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox iMile 是 Modules > Module Manager > VibeFox iMile > Configure 页面中位于设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺中移除密钥）。其下方是一行 Product: presta-shipping-imile 以及链接 Manage licenses and domains in your account，点击后会打开您的 vibefox.net 账户。只有拥有该模块 Configure 权限的员工才能更改密钥。该区块的文字会跟随后台语言显示（包括英文和俄文）。
如果密钥未被接受，该区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或 License expired on 加某个日期。店铺地址更改后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，模块将继续使用最后已知的状态运行。
一个密钥只适用于一个域名：主店铺的域名，多店铺设置中也是如此。从店铺中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效的密钥时，iMile 承运商不会在结账时显示给顾客，也不会计算任何运费。PrestaShop 前台无法得知您已登录后台，因此该承运商对您也会被隐藏：您可以在购买密钥前设置模块，但无法在结账时测试。Modules > Module Manager 的 Alerts 选项卡中会出现提醒。现有订单不受影响。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。在您使用后台期间，状态会自动重新检查：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时没有显示 iMile：请检查许可证是否有效，Enable iMile 是否开启。在 Shipping > Carriers 中，检查承运商是否覆盖顾客所在国家的区域和顾客所属的客户组；或开启 Ignore shipping zones 并检查 Countries。检查重量限制和 Minimum order amount。检查该国家或 * 在 Price table 中是否有一行，或是否设置了 Price for countries not in the table。商品也可能在商品页面中被限定为特定承运商。
显示的是价格表价格，而不是 iMile 估价：请开启 Debug log，重新加载结账页面，然后查看模块页面上的 Log 字段。常见原因：Live estimate 关闭、缺少密钥、顾客尚未输入城市、iMile 不识别城市拼写、商品没有重量、目的货币没有汇率，或出现 API 错误。另外请查看设置上方的警告。
日志中出现 "sign is invalid"：请检查 Secret key，然后尝试将 Signature 设为 SimpleKey。
密钥被拒绝：请检查 Customer ID、Secret key 和 Environment。测试密钥仅适用于测试服务器。
城市名称不匹配：城市名称必须与 iMile 城市列表一致。开发者可以使用 actionVfdImileLiveRequest 钩子进行映射，使用 actionVfdImileLiveCountryCode 钩子映射国家代码。
价格货币错误：价格表使用店铺默认货币。录入 AED、SAR 或 MXN 运费时请先换算。实时估价会通过 Exchange rates 换算。
运费被重复征税：如果您的价格已包含增值税，请将 Tax 设为 No tax。
修改后估价看起来过时：请在模块页面点击 Save。这会清除缓存的 iMile 估价。
页面提示找不到 iMile 承运商：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块以重新创建。
卸载
进入 Modules > Module Manager，打开 VibeFox iMile 旁边的菜单，选择 Uninstall。许可证密钥和许可证状态始终会被删除。缓存的估价和访问令牌总会被删除。如果 Remove data on uninstall 已开启，承运商会被删除（订单保留其历史记录），设置和日志也会被删除。如果已关闭，承运商仅会被停用，所有设置都会保留。重新安装模块会恢复承运商之前的状态。
iMile 是其各自所有者的商标。本模块与 iMile 无关联，也未获得 iMile 的认可。