VibeFox Delhivery for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本。

Delhivery API 令牌（仅用于实时运费）：登录 Delhivery One 并打开 Settings > API setup。Delhivery 帮助文章 "API token generation" 说明了具体步骤。两个链接都位于扩展页面上。测试令牌可用于 staging 环境。您还需要提货地点的 6 位 pincode。如果只使用固定价格，则无需令牌。

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

安装

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

OpenCart 3

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

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

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

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

5. 输入 API 令牌和发货 pincode，选择 Express 或 Surface 以及 Pre-paid 或 COD。若商店默认货币不是 INR，请输入汇率。可选：输入固定价格（参见配置）。开启 Enable Delhivery，然后点击 Save。

OpenCart 4

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

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

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

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

安装后，在您开启 Enable Delhivery 并保存之前，该配送方式处于关闭状态。如果您卸载后重新安装扩展，则会重新使用您保留的 Delhivery 设置。

配置

所有设置都在扩展页面中：Extensions > Extensions > Shipping > VibeFox Delhivery > Edit。各分区列在左侧。一个 Save 按钮可保存整个页面，无需重新加载。每次保存还会清除缓存的 Delhivery 运费。金额可输入 "9.99" 或 "9,99"。如果某个值有误，则不会保存任何内容，页面会显示原因，例如 Enter a valid method title (without < > ; = # { }).、某个字段必须是非负数的提示，或 Sort order must be a whole number. 只有拥有该扩展修改权限的管理员用户才能保存设置。

如果商店默认货币不是 INR，已保存 API 令牌但未设置汇率，则页面顶部的警告会提醒您：在输入汇率之前，不会使用实时运费。如果商店没有以千克为单位的重量类别，并且其重量单位不是标准单位（kg、g、lb 或 oz），警告会说明商品重量将按千克读取。请在 System > Localisation > Weight Classes 中设置标准单位。

常规

这些设置适用于所有地理区域。您可以在 Availability 中限制该配送方式。

Enable Delhivery:在结账时提供 Delhivery。默认：关闭。

Method title:客户在购物车和结账时看到的配送方式名称。默认：Delhivery。必填，最多 64 个字符，且不得包含字符 < > ; = # { }。

Tax class:配送费用的税类，或 No tax（默认）。选择税类后，OpenCart 会在配送费用之上加收税费。

Sort order:Delhivery 在结账时配送方式中的排列位置。整数。

Delhivery API 账户（仅实时运费需要）

Environment:Production (track.delhivery.com)（默认）或 Staging / test account (staging-express.delhivery.com)。仅在使用 Delhivery 测试令牌时才使用 Staging。

API token:您的 Delhivery API 令牌。它仅在授权请求头中发送，绝不会写入日志。保存后，该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。

Remove saved token:开启并保存即可删除已保存的令牌。此后仅使用固定价格。

Origin pincode:您的提货地点或仓库的 6 位 pincode，例如 110001。如果不是 6 位，设置仍会保存，但会显示警告 The origin pincode must have 6 digits — live rates are not requested until it is fixed.

实时运费

对于印度目的地且 pincode 有效（6 位），将请求实时运费，适用于正向（已送达）运输。

Shipping mode:用于计算运费的 Delhivery 计费模式：Express（默认）或 Surface。

Payment type:发送给 Delhivery 的付款类型：Pre-paid（默认）或 COD (cash on delivery — Delhivery adds its COD charge)。扩展不会根据客户选择的付款方式切换该设置。

Rate amount:Delhivery 会返回含 GST 和不含 GST 的费用。

INR to (store currency) conversion rate:标签会显示您商店的默认货币。Delhivery 运费以印度卢比计。如果您的默认货币不是 INR，请输入 1 卢比等于多少个您的货币单位，例如 0.011。汇率必须大于 0。如果留空，则不使用实时运费，并采用固定价格。如果默认货币是 INR，则无需设置。

固定价格（在没有实时运费时使用）

当尚无令牌或 pincode、目的地在印度境外、pincode 不在服务范围内或 API 返回错误时，将使用固定价格。这些价格以商店默认货币计，不含税。

Prices per country:每行一个，格式为 国家代码:价格，例如 IN:120。在备用价格之前检查。格式不同的行在保存时会被删除，并会在警告中列出。

Fallback price:在实时运费和国家价格都不适用时使用。留空则隐藏该配送方式（默认）。0 表示免费。

Fixed price is charged:Per order（默认）只收取一次价格。Per item (price × quantity) 会按购物车中的商品数量相乘。Delhivery 实时运费始终针对整个包裹重量。

条件

Free shipping from:如果需要配送的商品小计（扣除优惠券后、税前）不低于此金额，则免运费。不会向 Delhivery 发出请求。留空则关闭此功能。

Show from subtotal:仅当该小计不低于此金额时才显示该配送方式。留空则始终显示。

Min weight (kg):显示该配送方式所需的最低购物车重量。0 表示不限制（默认）。

Max weight (kg):购物车超过此重量时隐藏该配送方式。默认：30。0 表示不限制，留空则表示 30 kg。Min weight 不能大于 Max weight：页面会显示错误，且不会保存任何内容。

商品重量会根据其 OpenCart 重量类别转换为千克。运费使用购物车的实际重量（商品重量之和），不计体积重量或包装箱。

可用性

Geo zone:仅向该地理区域内的地址提供 Delhivery。All zones（默认）表示不限制。地理区域在 System > Localisation > Geo Zones 中管理。开启 Ignore zones 时不进行检查。

Ignore zones:开启后，不检查地理区域，并为下方国家提供该配送方式（如果列表为空，则适用于所有国家）。

Countries:该模式下的目的国家。仅在开启 Ignore zones 时使用。

高级

Debug log:将运费计算记录到 storage/logs/vfd_dlv_debug.log.php（在 OpenCart 4 中为 system/storage/logs/vfd_dlv_debug.log.php）。该文件无法通过网页读取。即使此选项关闭，API 错误也始终会被记录。令牌和客户的完整 pincode 绝不会被记录。当文件达到 5 MB 时，会移至 vfd_dlv_debug.old.log.php，并开始新的日志。

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

Remove data on uninstall:开启后，卸载扩展会删除 Delhivery 设置、缓存的运费和日志。关闭时（默认），它们会保留，以便重新安装。订单数据（模式、价格来源、AWB 号码）永远不会被删除。

导入 / 导出

Export:点击 Download JSON 将设置保存为 JSON 文件。API 令牌不会被导出。

Import:粘贴之前导出的 JSON，然后点击 Import 恢复设置，例如在另一家商店中使用。系统会像正常保存一样检查这些值。已保存的 API 令牌不会被更改。

结账时的工作方式

当 OpenCart 显示配送方式时，会向扩展请求 Delhivery 价格。如果设置了 Geo zone（且 Ignore zones 关闭），并且地址不在该区域内，则不提供 Delhivery。只有 Requires Shipping 设为 Yes 的商品才会计算在内：其他商品不增加重量，也不计入小计。然后扩展会检查国家（当 Ignore zones 开启时）、购物车重量以及 Show from subtotal。小计是需要配送的商品的价格，在扣除优惠券折扣之后、税前计算。礼品卡、积分奖励和商店余额不计入。如果适用免运费，价格为 0，且不会向 Delhivery 发出请求。

对于具有有效 6 位 pincode（即地址的邮政编码）的印度地址，扩展会向 Delhivery 发送发货和收货 pincode、以克为单位的购物车重量、配送模式和付款类型。返回的金额会从 INR 换算为您商店的默认货币，按其小数位数取整，并以客户的货币显示，同时包含所选 Tax class 的税费。每个响应缓存 1 小时。失败的请求缓存 10 分钟，因此结账页面在每次刷新时都不必等待 Delhivery。API 超时时间为 10 秒。

如果没有实时运费，则使用该国的价格或备用价格。如果两者都未设置，则隐藏该配送方式。客户绝不会看到 API 错误。原因会写入日志。

该扩展负责计算运费，并为客户提供追踪链接。它不创建运单或托运单，不打印面单，不预约取件或生成舱单，不检查 pincode 的服务范围，不估算送达日期，不同步追踪状态，也不报价 Delhivery 的国际运费。在印度以外，仅使用固定价格。

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

订单与追踪

当使用 Delhivery 下单时，扩展会将配送模式和价格来源随订单一起保存。在 Sales > Orders 中打开订单：订单历史上方的 Delhivery 面板会显示 Mode:（Express 或 Surface）、Price:（Delhivery 实时运费、固定价格或免运费门槛），以及 Delhivery AWB / tracking number，若尚未输入则显示 Not entered yet.

在 OpenCart 4 中，结账流程只保留一个订单，并在客户每次重新确认时更新该订单。配送模式和价格来源会随之更新。如果客户在输入 AWB 之前切换到其他配送方式，则该订单的 Delhivery 面板将不再显示。

在 Delhivery One 中创建运输单，然后在面板中输入其 AWB 并点击 Save。页面不会重新加载。字母、数字和短横线会被保留（最多 64 个字符）。保存空字段即可删除 AWB。有 AWB 时，面板会显示 Track on delhivery.com 链接。保存 AWB 需要修改订单的权限。没有该权限时，面板为只读。

已注册的客户可在其账户的订单页面看到 Delhivery tracking:，其中 AWB 为指向 Delhivery 追踪页面的链接。当您添加订单历史记录并通知客户时，订单状态电子邮件中会包含同样的带链接内容。新订单电子邮件不包含追踪链接，因为 AWB 之后才会输入。即使扩展已关闭，面板和追踪链接对旧订单仍然有效。

许可证密钥

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

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

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

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

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

故障排除

Delhivery 未出现在结账页面中：请检查许可证是否有效，并确认 Enable Delhivery 已开启。检查 Geo zone，或 Ignore zones 与 Countries、重量限制以及 Show from subtotal。若没有实时运费，则需要国家价格或 Fallback price。请检查商品的 Requires Shipping 是否设为 Yes。

实时运费未出现：请检查 API 令牌、有效的 Origin pincode，以及（若默认货币不是 INR）汇率。客户必须输入有效的 6 位印度 pincode 作为邮政编码。开启 Debug log，重新加载结账页面，并查看扩展页面上的 Log 字段。它会显示原因，例如 pincode 不在服务范围内，或 Delhivery 返回的 HTTP 错误。

GST 被重复征收：Delhivery 的总金额已包含 GST。请将 Rate amount 设为 Gross amount (excluding GST)，或将 Tax class 设为 No tax。

测试：将 Environment 设为 Staging，并使用 Delhivery 测试令牌。

修改后运费看起来过时：请在扩展页面点击 Save。这会清除缓存的 Delhivery 运费。

无法保存 AWB：提示 You do not have permission to modify orders. 表示您的管理员用户组需要在 System > Users > User Groups 中获得 sale/order 的修改权限。

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

开发人员：该扩展会触发 OpenCart 事件 catalog/vfd_delhivery/api_url 和 catalog/vfd_delhivery/api_timeout，可用于更改 API 地址和超时时间。

卸载

进入 Extensions > Extensions，选择类型 Shipping，然后点击 VibeFox Delhivery 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会重置 Enable Delhivery、Sort order、Tax class 和 Geo zone。缓存的运费和扩展的事件始终会被删除。如果开启了 Remove data on uninstall，Delhivery 设置和调试日志也会被删除。如果关闭，其他设置会保留，并在您重新安装扩展时再次使用。订单中的 Delhivery 数据（模式、价格来源和 AWB 号码）永远不会被删除。现有订单保留其配送方式和费用。

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

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