VibeFox Ninja Van for OpenCart — 帮助

要求

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

PHP：8.0 或更高版本。

Ninja Van 费率表：您的 Ninja Van 发货商账户中的价格，或 Ninja Van 销售团队提供的价格，录入价格表中。无需 API 密钥。印度尼西亚境内可选的实时价格使用 Ninja Van Tariff API，该 API 为公开接口，无需身份验证。

VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。

安装

下载文件是一个 zip 文件，内含两个 OpenCart 版本的安装包。请在您的电脑上解压。其中包含 README.txt、OpenCart 3 安装包 vfd_ninja_van-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 vfd_ninja_van.ocmod.zip。请只安装与您的 OpenCart 版本对应的安装包。两个版本的许可证密钥相同。

OpenCart 3

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

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

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

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

5. 在价格表中输入您的 Ninja Van 价格。如需针对印度尼西亚开启实时运费，可选择打开 Live rates（参见配置）。打开 Enable Ninja Van，然后点击 Save。

OpenCart 4

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

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

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

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

安装后，该配送方式处于关闭状态，直到您打开 Enable Ninja Van 并保存。如果您在卸载后重新安装扩展，之前保留的 Ninja Van 设置将再次使用。

配置

所有设置都位于扩展页面：Extensions > Extensions > Shipping > VibeFox Ninja Van > Edit。各分区列在左侧。页面底部的一个 Save 按钮会在不重新加载页面的情况下保存整个页面。当 Method title 为空、超过 64 个字符或包含 < > ; = # { }，数字字段包含文本或负数，IDR conversion rate 为 0，Minimum weight (kg) 大于 Maximum weight (kg)，或 Sort order 不是整数时，不会保存任何内容，并会显示错误。如果您的商店没有单位为 kg 的重量等级，并且默认重量等级的单位无法被扩展识别，则会出现警告，说明商品重量将按公斤计算：请在 System > Localisation > Weight Classes 中添加一个 kg 重量等级。只有拥有本扩展修改权限的管理员用户才能保存设置。

常规

这些设置适用于所有地理区域。您可以在 Conditions 中将该配送方式限制到某个地理区域，或使用 Ignore shipping zones。

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

Method title：客户在购物车和结账时看到的配送方式名称。默认：Ninja Van。必填，最多 64 个字符。

Tax class：运费的税类，或 No tax（默认）。如果费率表中的价格已包含税费（GST、SST、VAT），请选择 No tax。

Sort order：Ninja Van 在结账时配送方式中的排列位置。整数。

价格（以您商店的默认货币计，不含税）

请以您商店的默认货币输入 Ninja Van 费率表中的价格。如果您的费率表使用 SGD、MYR、IDR 或其他货币，请先进行换算。该表适用于印度尼西亚以外的所有目的地，以及实时价格不可用时。

Price table：每个目的国家一行。点击 Add country 添加一行，点击 × 按钮删除一行。对于没有单独行的所有其他国家，请选择 * All other countries。每行都有一个 Base 价格和重量列：XS 为 1 公斤及以下，S 为 2 公斤及以下，M 为 3 公斤及以下，L 为 5 公斤及以下，XL 为 5 公斤以上。空白（或为 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），其地址显示在字段下方。请两个都输入：OpenCart 的商店地址没有单独的城市或街道，因此无法从中识别发货区域。代码会转换为大写字母。格式错误的代码会被清除并给出警告。如果只输入了一个代码，警告会要求您输入两个，状态行会显示未请求实时价格。如果两个代码在区域代码对应表中不成对，状态行也会给出警告。

IDR conversion rate：Tariff API 以印度尼西亚盾（IDR）返回费用。如果您商店的默认货币是 IDR，请留空。否则，请输入 1 IDR 等于您商店货币的多少，例如 0.000058。该值必须大于 0。如果没有该值，则不使用实时价格，而使用价格表。

条件

Minimum weight (kg)：购物车重量低于此值时隐藏该配送方式。商品重量会从其 OpenCart 重量等级换算为公斤。0 表示无限制（默认）。

Maximum weight (kg)：购物车重量高于此值时隐藏该配送方式。默认：30。0 或留空表示无限制。不能低于 Minimum weight (kg)。

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

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

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

无配送区域时的可用性

Ignore shipping zones：无论 Geo zone 为何，都为下面列出的国家提供 Ninja Van。关闭时（默认），由地理区域决定，不使用国家列表。

Countries：该模式下的目的国家。留空则允许所有国家。该字段仅在 Ignore shipping zones 开启时使用。

高级

Debug log：将运费计算写入 storage/logs/vfd_njvn_debug.log.php（在 OpenCart 4 中为 system/storage/logs/vfd_njvn_debug.log.php）。该文件无法通过网页读取。客户地址和区域代码不会被记录。即使此选项关闭，失败的 Tariff API 请求也会被记录。使用完毕后请关闭。当文件达到 5 MB 时，它会被移动到 vfd_njvn_debug.old.log.php，并开始新的日志。

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

Remove data on uninstall：开启时，卸载扩展会删除 Ninja Van 设置和日志。关闭时（默认），这些数据会保留，以便重新安装。缓存的价格始终会被删除。

导入 / 导出

Export：点击 Download JSON 将设置保存为 JSON 文件。本扩展没有私密密钥，因此会导出全部内容。

Import：粘贴之前导出的 JSON，然后点击 Import 以恢复设置，例如在另一个商店中。这些值会像正常保存时一样进行检查。

结账时的工作方式

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

价格来自国家所在的行（或 * 行）：先看重量列，其次是基础价格，再次是 Price for countries not in the table。如果没有价格，则对该购物车隐藏该配送方式。价格按您商店的默认货币计算，四舍五入到其小数位，并以客户的货币显示，同时加上所选 Tax class 的税费。

开启 Live rates 后，印度尼西亚境内的配送会先由 Ninja Van 计价。扩展会将配送地址转换为 Ninja Van 区域代码：地址所在的地区（省）、City 字段（城市或县）以及对于拥有多个区域的城市，在 Address 1 或 Address 2 中填写的区（Kecamatan）。它会发送您的发货区域代码、配送区域代码、重量和服务等级，并将费用从 IDR 换算为您商店的货币。使用 Per item 时，每种不同的商品重量发送一次请求，每个购物车最多 5 次。如果不同重量超过此数，则使用价格表。

Tariff API 每分钟允许 20 次请求，因此响应会缓存在扩展的一张表中：价格缓存 6 小时，“此路线无价格”缓存 1 小时，失败结果缓存 5 分钟。保存设置不会清除此缓存。扩展每分钟发送的请求绝不超过 18 次，并且在收到 HTTP 429 响应后暂停一小时。API 超时时间为 12 秒。如果 Ninja Van 没有响应、返回错误、该路线没有价格或地址无法匹配，则使用价格表。错误会写入日志，绝不会显示给客户。

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

扩展仅计算价格。它不会创建 Ninja Van 订单、打印航空运单（AWB）、预约取件、跟踪包裹或处理货到付款（COD）。请为此使用 Ninja Van Dashboard。没有取件点（Ninja Points）选择器：该方式为送货上门。它不会向订单添加任何内容：订单与其他 OpenCart 配送方式一样，显示配送方式名称和运费。实时价格在印度尼西亚以外不可用。

许可证密钥

本扩展需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Ninja Van 是 Extensions > Extensions > Shipping > VibeFox Ninja Van > Edit 页面的第一个区块，位于设置上方。请将密钥输入 License key，然后点击 Activate。之后，该区块会以隐藏方式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及按钮 Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店移除密钥）。其下方是 Product: opencart-shipping-ninja-van 一行，以及打开您 vibefox.net 账户的链接 Manage licenses and domains in your account。只有拥有本扩展修改权限的管理员用户才能更改密钥。该区块的文字跟随后台语言（包含英文和俄文）。

如果密钥未被接受，该区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或带有日期的 License expired on。在店铺地址更改后，或在您的账户中释放了域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展将继续使用最后已知的状态运行。

一个密钥只能用于一个域名：即 OpenCart 配置中的商店地址。从商店移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。

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

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

故障排除

结账时未显示 Ninja Van：请检查许可证是否有效，以及 Enable Ninja Van 是否已开启。检查 Geo zone（或 Ignore shipping zones 和 Countries）、重量限制和 Minimum order amount，并确认该国家、* 行或 Price for countries not in the table 有价格。检查商品的 Requires Shipping 是否设为 Yes。

某些地址未使用实时价格：目的地必须与 Ninja Van 区域匹配：印度尼西亚、地区（省）、City 中的城市或县，以及对于拥有多个区域的城市，地址行中的区（Kecamatan）。否则将使用价格表。请开启 Debug log，重新加载结账页面，并查看扩展页面上的 Log 字段。

完全未请求实时价格：Live rates (API) — Indonesia 下方的状态行会显示原因：缺少发货区域代码、只输入了两个代码中的一个、输入的代码在区域代码对应表中不成对，或缺少 IDR conversion rate。

已达到请求上限（HTTP 429）：实时请求暂停一小时，在此期间使用价格表。保存设置不会结束暂停。

价格使用哪种货币：价格表和条件以您商店的默认货币计。实时价格以印度尼西亚盾（IDR）计，并使用 IDR conversion rate 换算，除非您的商店货币就是 IDR。

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

面向开发人员：拥有自有区（Kecamatan）字段的商店可以通过 OpenCart 事件 vfd_ninja_van/tariff_zone（触发器 catalog/vfd_ninja_van/tariff_zone）提供区域代码，发货区域也适用。Tariff API 地址可以通过设置 vfd_njvn_api_url 替换（用于测试）；设置页面上没有对应字段。

卸载

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

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

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