VibeFox Ninja Van for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝在较旧的 PHP 版本上安装。
Ninja Van 运费表：您的 Ninja Van 发件人账户中的运费，或来自 Ninja Van 销售团队的运费，录入到价格表中。无需 API 密钥。印度尼西亚境内可选的实时运费使用 Ninja Van Tariff API，该接口公开，无需身份验证。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 进入后台，前往 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox Ninja Van，然后点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，于 License key 处输入您的 VibeFox 许可证密钥，然后点击 Activate（见许可证密钥）。
4. 在价格表中输入您的 Ninja Van 运费。对于印度尼西亚，可以选择开启 Live rates（见配置）。点击 Save。
安装时，模块会创建 Ninja Van 承运商，其配送时效文本为 Courier delivery。该承运商默认启用，已分配给所有区域和所有客户组，且没有税务规则。您可以在 Shipping > Carriers 中修改区域、客户组、配送时效、logo 和尺寸限制。请不要在那里设置价格：价格始终来自模块。
配置
所有设置都位于模块页面：Modules > Module Manager > VibeFox Ninja Van > Configure。这些设置适用于承运商的所有区域。每个部分都有各自的 Save 按钮，它会保存整个页面。当数字字段包含文本或负数、IDR conversion rate 为 0、Minimum weight (kg) 大于 Maximum weight (kg)，或 Method title 超过 64 个字符时，将不会保存任何内容，并显示错误。如果您的店铺重量单位不是模块支持的单位，保存后会出现警告，提示商品重量将按千克计算。
常规
Enable Ninja Van：开启或关闭承运商。这与 Shipping > Carriers 中的承运商状态是同一个开关。
Method title：购物车和结账时向客户显示的承运商名称。默认：Ninja Van。必填，最多 64 个字符。
Tax：承运商的税务规则，或 No tax（默认）。如果表中的运费已包含税款（GST、SST、VAT），请选择 No tax。
运费（以店铺默认货币计，不含税）
请以店铺默认货币输入您的 Ninja Van 运费表中的运费。如果您的运费表使用 SGD、MYR、IDR 或其他货币，请先换算。此表适用于印度尼西亚以外的所有目的地，以及任何实时运费不可用的情况。
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：当表中没有目的国家的行（也没有 * 行），或该行对此重量没有运费时使用。若在这种情况下希望隐藏承运商，请留空。0 表示免运费。
Price applies：运费的计算方式。这也适用于实时运费。
实时运费（API）— 印度尼西亚
Ninja Van Tariff API 会返回在印度尼西亚境内发送的包裹的标准配送费，不含附加费和折扣。Ninja Van 仅在印度尼西亚提供此服务。开启 Live rates 后，区块标题下方的状态行会显示发货地区域、缺失的换算汇率，以及最近一次 Tariff API 的响应（环境、时间和结果）。
Live rates：获取印度尼西亚境内配送的 Ninja Van 实时运费。默认：关闭。未开启此选项时，结账期间不会向 Ninja Van 发送任何请求。
Environment：Production (api.ninjavan.co)（默认）或 Sandbox — testing only (api-sandbox.ninjavan.co)。
Service level：请求运费所针对的服务：Standard（默认）、Express、Same day 或 Next day。如果 Ninja Van 对该路线和服务没有运费，则使用运费表。
Ship-from zone code L1 和 Ship-from zone code L2：您发货所在区的 L1 和 L2 层级代码，例如 ID_A00007_01 和 ID_B00069_01，取自 Ninja Van 区域代码映射（CSV），其地址显示在该字段下方。请同时输入两者，或两者都留空，以便从 Shop Parameters > Contact > Stores 中的店铺地址自动检测：印度尼西亚、省（state）、城市，以及如果城市有多个区域，则为地址行中的区（Kecamatan）。格式错误的代码会被清除并给出警告。如果只输入了一个代码，警告会要求您输入两个，并且状态行会显示未请求实时运费。
IDR conversion rate：Tariff API 返回的运费以印度尼西亚卢比（IDR）计价。如果您的店铺默认货币是 IDR，请留空。否则，请输入 1 IDR 等于店铺货币的多少，例如 0.000058。该值必须大于 0。未设置时，不使用实时运费，而是使用运费表。
条件
Minimum weight (kg)：购物车重量低于此值时隐藏承运商。商品重量会从店铺的重量单位换算为千克。0 表示不限制。
Maximum weight (kg)：购物车重量高于此值时隐藏承运商。默认：30。0 表示不限制。不能低于 Minimum weight (kg)。
Minimum order amount：仅当购物车小计（需要配送的商品，折扣后，税前）达到此金额时才显示承运商。留空则始终显示。
Free shipping from：购物车小计（需要配送的商品，折扣后，税前）达到此金额时，Ninja Van 配送免运费。留空表示不提供免运费。
不使用配送区域时的可用性
Ignore shipping zones：即使承运商未关联到某国家所在的区域，也为下列国家提供 Ninja Van。开启后，承运商会关联到所有启用的区域，包括您之后创建的区域。关闭时，承运商会恢复为之前所关联的区域。
Countries：此模式下的目的国家。留空则使用您配送的所有国家。此字段仅在 Ignore shipping zones 开启时使用。
高级
Debug log：将运费计算记录到模块文件夹中的 logs/vfd_njvn_debug.log.php。该文件无法通过网页打开。日志中不记录客户地址。即使此选项关闭，失败的 Tariff API 请求仍会被记录。完成后请关闭。
Log：显示调试日志的大小及最新条目。点击 Clear log 可清空日志。
Remove data on uninstall：开启时，卸载模块会删除模块设置、承运商、缓存的运费和日志。关闭时，所有内容都会保留，以便重新安装。
结账时的工作方式
在配送步骤中，PrestaShop 会向模块请求 Ninja Van 运费。只计算实体商品：虚拟商品不增加重量，也不计入订单金额。模块首先检查条件：Ignore shipping zones 的国家列表（如果开启）、购物车重量和最低订单金额。如果适用免运费，运费为 0，并且不会向 Ninja Van 发送请求。
运费来自国家所在的行（或 * 行）：重量列；若无，则为基础运费；若仍无，则为 Price for countries not in the table。如果没有运费，则在该购物车中隐藏承运商。运费以店铺默认货币计算，然后以客户的购物车货币显示。
开启 Live rates 时，印度尼西亚境内的配送会优先由 Ninja Van 计价。模块会将发货地址和收货地址转换为 Ninja Van 区域代码：省（state）、城市或摄政区（regency），以及对于有多个区域的城市，地址行中写明的区（Kecamatan）。它会发送代码、重量和服务等级，并将 IDR 运费换算为店铺货币。使用 Per item 时，每个不同的商品重量发送一次请求，每个购物车最多 5 次。如果不同重量超过此数量，则使用运费表。
Tariff API 每分钟允许 20 次请求，因此响应会缓存 6 小时，失败结果缓存 5 分钟，“该路线无运费”缓存 1 小时。模块每分钟发送的请求绝不超过 18 次；收到 HTTP 429 响应后，会暂停一小时。API 超时时间为 12 秒。如果 Ninja Van 没有响应、返回错误、没有该路线的运费，或无法匹配地址，则使用运费表。错误会记录到日志中，绝不会显示给客户。
如果您在 Shipping > Carriers 中编辑已有订单的承运商，PrestaShop 会将其保存为承运商的新版本。模块会自动跟随新版本。
模块仅计算运费。它不会在 Ninja Van 创建订单、打印空运单（AWB）、预约取件、追踪包裹或处理货到付款（COD）。请使用 Ninja Van Dashboard 完成这些操作。没有取件点（Ninja Points）选择器：承运商为上门配送。印度尼西亚以外地区不提供实时运费。
许可证密钥
本模块需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Ninja Van 是 Modules > Module Manager > VibeFox Ninja Van > Configure 页面中位于设置上方的第一个区块。将密钥输入 License key，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now 用于重新检查状态，Change key 用于输入其他密钥，Remove key 用于从此店铺中移除密钥。其下方是 Product: presta-shipping-ninja-van 一行，以及打开您 vibefox.net 账户的 Manage licenses and domains in your account 链接。只有拥有该模块 Configure 权限的员工才能更改密钥。该区块的文字遵循后台语言（包括英文和俄文）。
如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或带有日期的 License expired on。更改店铺地址后，或在账户中释放域名名额后，请点击 Check now。如果无法连接许可证服务器，模块将继续按最后已知的状态运行。
一个密钥只能用于一个域名：主店铺的域名，多店铺设置中同样适用。从店铺中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。
没有有效的密钥时，结账时不会向客户显示 Ninja Van 承运商，也不会计算任何运费。PrestaShop 前台无法得知您已登录后台，因此承运商对您也是隐藏的：您可以在购买密钥之前设置模块，但无法在结账时进行测试。Modules > Module Manager 的 Alerts 选项卡中会显示提醒。现有订单不受影响。
许可证过期后，模块仍会继续运行，但更新和支持需要续订。在后台工作时，状态会自动重新检查：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时没有显示 Ninja Van：请检查许可证是否有效，以及 Enable Ninja Van 是否已开启。在 Shipping > Carriers 中，检查承运商是否覆盖客户所在国家的区域和客户组（或开启 Ignore shipping zones 并检查 Countries）。检查重量限制和 Minimum order amount，并确认国家、* 行或 Price for countries not in the table 中有运费。在商品页面中，商品也可能被限制只能使用特定承运商。
某些地址未使用实时运费：目的地必须匹配到 Ninja Van 区域：印度尼西亚、省（state）、城市或摄政区，以及对于有多个区域的城市，地址行中的区（Kecamatan）。否则将使用运费表。开启 Debug log，刷新结账页面，并查看模块页面上的 Log 字段。
完全未请求实时运费：实时运费（API）— 印度尼西亚 下方的状态行会显示原因：店铺地址不在印度尼西亚，或无法检测发货地区域（请输入两个区域代码）；只输入了两个代码中的一个；输入的代码在区域代码映射中不成对；或缺少 IDR conversion rate。
已达到请求限制（HTTP 429）：实时请求将暂停一小时，期间使用运费表。
运费使用哪种货币：运费表和条件以店铺默认货币计。实时运费以卢比（IDR）计价，除非店铺货币为 IDR，否则会使用 IDR conversion rate 换算。
页面提示未找到 Ninja Van 承运商：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块以重新创建。
开发人员：如果店铺有自己的区（Kecamatan）字段，可以通过钩子 actionVfdNjvnTariffZone 提供区域代码。
卸载
前往 Modules > Module Manager，打开 VibeFox Ninja Van 旁边的菜单，选择 Uninstall。许可证密钥和许可证状态始终会被删除。缓存的运费始终会被删除。如果 Remove data on uninstall 已开启，承运商会被删除（订单保留历史记录），设置、最近一次 Tariff API 状态和日志也会被删除。如果已关闭，承运商仅会被停用，所有设置都会保留。重新安装模块后，已保存的承运商会恢复卸载前的状态。
Ninja Van 是其各自所有者的商标。本模块与 Ninja Van 没有关联，也未获得 Ninja Van 的认可。