VibeFox Delhivery for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

PHP：8.0 或更高版本。模块拒绝在更旧的 PHP 版本上安装。

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

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

安装

1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。

2. 上传完成后，点击 Configure；或者之后在模块列表中找到 VibeFox Delhivery，再点击 Configure。

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

4. 输入 API 令牌和发货 PIN 码，选择 Express 或 Surface 以及 Pre-paid 或 COD。如果您的店铺默认货币不是 INR，请输入汇率。也可以选择输入固定价格（参见「配置」）。点击 Save。

安装时，模块会创建 Delhivery 承运商，配送时效文本为 Courier delivery (India)，跟踪 URL 为 Delhivery 跟踪页面。该承运商会分配给所有区域和所有客户群组。您可以在 Shipping > Carriers 中修改区域、客户群组、配送时效、图标和尺寸限制。请不要在那里设置价格：价格始终来自模块。

配置

所有设置都位于模块页面：Modules > Module Manager > VibeFox Delhivery > Configure。设置适用于所有区域。每个部分都有自己的 Save 按钮，它会保存整个页面。每次保存还会清除缓存的 Delhivery 运费。金额可以输入「9.99」或「9,99」。如果数字字段中不是非负数，将显示错误，且不会保存任何内容。

如果您的店铺默认货币不是 INR，已保存 API 令牌但未设置汇率，表单上方的提示会提醒您：在输入汇率之前不会使用实时运费。如果您店铺的重量单位不是标准单位（kg、g、lb 或 oz），提示会要求您在 International > Localization（Local units）中设置，否则商品重量将被按千克计算。

常规

Enable Delhivery：启用或停用该承运商。这与 Shipping > Carriers 中的承运商状态是同一个开关。

Method title：在购物车和结账时显示的承运商名称。默认值：Delhivery。必填，最多 64 个字符。

Tax：承运商的税务规则，或 No tax。设置了规则后，PrestaShop 会在运费之上加收税费。

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 位 PIN 码，例如 110001。如果不是 6 位，将显示提示，并且在修正之前不会请求实时运费。

实时运费

对于印度目的地且 PIN 码有效（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 (shop currency) conversion rate：标签会显示您店铺的默认货币。Delhivery 运费以印度卢比计。如果您的默认货币不是 INR，请输入一个卢比等于多少单位您的货币，例如 0.011。汇率必须大于 0。留空则不使用实时运费，而是采用固定价格。如果默认货币是 INR，则无需设置。

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

当尚未设置令牌或 PIN 码、目的地在印度境外、PIN 码无法配送或 API 返回错误时，将使用固定价格。固定价格以您店铺的默认货币计，不含税。

Prices per country：每行一条，格式为 COUNTRY_CODE:price，例如 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：页面会显示错误，且不保存任何内容。

商品重量会从您店铺的重量单位换算为 kg。运费使用购物车的实际重量（商品重量之和），不计体积重量或包装箱。

无配送区域时的可用性

Ignore zones：关闭时，国家由 Shipping > Carriers 中承运商的区域决定。开启时，承运商会关联到所有区域（包括您以后创建的区域），并针对下方的国家提供服务。关闭后，承运商会恢复其之前的区域。

Countries：该模式下的目的国家，从您已启用的国家中选择。留空则使用您所有可配送的国家。仅在开启 Ignore zones 时使用。

高级

Debug log：将运费计算记录写入模块文件夹中的 logs/vfd_dlv_debug.log.php。该文件无法通过网页打开。即使此选项关闭，API 错误也始终会记录。令牌和客户的完整 PIN 码从不记录。

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

Remove data on uninstall：开启时，卸载模块会删除 Delhivery 设置、承运商、缓存的运费、订单数据和日志。关闭时，所有内容都会保留，便于重新安装。订单的 AWB 号码永远不会被删除。

结账时的工作流程

在配送步骤，PrestaShop 会向模块请求 Delhivery 价格。只有实体商品计入：虚拟商品不增加重量，也不计入小计。模块首先检查国家（开启 Ignore zones 时）、购物车重量和 Show from subtotal。如果适用免运费，价格为 0，且不会向 Delhivery 发送请求。

对于印度地址且 PIN 码有效（6 位）的情况，模块会向 Delhivery 发送发货和目的地 PIN 码、以克为单位的购物车重量、配送模式和付款类型。返回的金额会从 INR 换算为您店铺的默认货币，然后以客户的购物车货币显示。每个响应缓存 1 小时。失败的请求缓存 10 分钟，这样结账时每次刷新都不必等待 Delhivery。API 超时时间为 10 秒。

如果没有实时运费，则使用国家价格或备用价格。如果两者都未设置，则隐藏该承运商。客户永远不会看到 API 错误。原因会写入日志。

如果您在承运商已有订单后，在 Shipping > Carriers 中编辑该承运商，PrestaShop 会将其保存为新版本的承运商。模块会自动跟随新版本。

模块计算运费，并为客户提供跟踪链接。它不会创建运单或面单，不打印标签，不预约取件或生成交接清单，不检查 PIN 码配送范围，不估算送达日期，不同步物流状态，也不报价 Delhivery 国际运费。在印度境外，仅使用固定价格。

订单与跟踪

使用 Delhivery 下单时，模块会将配送模式和价格来源与订单一起保存。在后台订单页面上，Delhivery 区块会显示 Mode:（Express 或 Surface）、Price:（Delhivery 实时运费、固定价格或免运费门槛）以及 Delhivery AWB / tracking number，若未填写则显示 Not entered yet.

在 Delhivery One 中创建运单，然后在订单页面的 Carriers 区块中（点击 Edit），将其 AWB 输入为订单的物流跟踪号。之后 Delhivery 区块会显示 Track on delhivery.com 链接。客户会在订单历史中看到跟踪链接，并收到 PrestaShop 发送的「运输中」邮件。

许可证密钥

模块需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Delhivery 是 Modules > Module Manager > VibeFox Delhivery > Configure 页面中位于设置上方的第一个区块。请将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（再次检查状态）、Change key（输入其他密钥）和 Remove key（从此店铺中移除密钥）。其下方是 Product: presta-shipping-delhivery 一行和 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 账户中释放该名额。

没有有效密钥时，结账时不会向客户显示 Delhivery 承运商，也不会计算运费。PrestaShop 前台无法得知您已登录后台，因此承运商对您也会被隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 的 Alerts 选项卡中会显示提醒。已有订单不受影响。

许可证到期后，模块仍会继续运行，但更新和支持需要续期。您在后台工作时会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，总会删除许可证密钥和许可证状态。

故障排除

结账时不显示 Delhivery：请检查许可证是否有效，以及 Enable Delhivery 是否已开启。在 Shipping > Carriers 中，检查承运商是否覆盖客户所在国家的区域和客户群组，或者开启 Ignore zones 并检查 Countries。检查重量限制和 Show from subtotal。没有实时运费时，需要设置国家价格或 Fallback price。商品也可以在商品页面中限定为特定承运商。

实时运费不显示：请检查 API 令牌、有效的 Origin pincode，以及（如果默认货币不是 INR）汇率。客户必须输入有效的 6 位印度 PIN 码。开启 Debug log，重新加载结账页面，并查看模块页面上的 Log 字段。它会显示原因，例如 PIN 码无法配送或 Delhivery 返回的 HTTP 错误。

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

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

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

页面提示找不到 Delhivery 承运商：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块以重新创建它。

面向开发者：模块会触发 actionVfdDlvApiUrl 和 actionVfdDlvApiTimeout 钩子，可用于修改 API 地址和超时时间。

卸载

进入 Modules > Module Manager，打开 VibeFox Delhivery 旁边的菜单，然后选择 Uninstall。许可证密钥、许可证状态和缓存的运费始终会被删除。如果 Remove data on uninstall 已开启，承运商会恢复其之前的区域并被删除（订单保留其历史记录），同时删除设置、日志以及订单的 Delhivery 数据（模式和价格来源）。如果已关闭，承运商仅被停用，所有设置都会保留。重新安装模块会以之前的状态恢复承运商。AWB 号码保留在订单中。

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