VibeFox DHL Africa for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本并启用 cURL 扩展。低于此版本的 PHP 或未启用 cURL 时，模块拒绝安装。DHL XML Services 还需要 PHP SimpleXML 扩展。
DHL Express 账号（仅用于实时运费）：实时运费使用 MyDHL API。您需要 DHL Express 账号号码以及 MyDHL API 凭据：API key 和 API secret。可以在 DHL Developer Portal（MyDHL API，"Get access"）申请，或向您的 DHL Express 客户经理索取。仍持有 DHL XML Services 凭据（Site ID 和密码）的账号可以改用这些凭据。如果您只使用备用价格，则不需要 DHL 凭据。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 进入后台，前往 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者之后在模块列表中找到 VibeFox DHL Africa，点击 Configure。
3. 将您的 VibeFox 许可证密钥输入到 Configure 页面顶部许可证区块中的 License key 字段，然后点击 Activate（参见许可证密钥）。
4. 选择 DHL API，输入 API key、API secret 和您的 DHL 账号号码。使用测试凭据时，请保持 Test mode 开启。填写 Ship from 发货地址。如果您的 DHL 账户不以店铺默认货币结算，请设置 DHL quote currency 和 Exchange rate。可选设置按国家的价格以及备用运费（参见配置）。点击 Save。
安装时，模块会创建 DHL Express 承运商，其配送时间文字为 DHL Express courier。该承运商会分配给所有区域和所有客户群组。您可以在 Shipping > Carriers 中更改区域、客户群组、配送时间、图标和尺寸限制。请不要在那里设置价格：价格始终来自本模块。
配置
所有设置都在模块页面中：Modules > Module Manager > VibeFox DHL Africa > Configure。它们适用于该承运商的每个区域。每个部分都有各自的 Save 按钮，点击后会保存整个页面。每次保存也会清除缓存的 DHL 报价。价格和重量可以使用小数点或小数逗号。
页面顶部的警告会提示：由于缺少 API key、API secret 或账号号码（使用 XML Services 时则是缺少 Site ID 或密码），实时运费已关闭；缺少发货国家或城市；已选择 XML Services（DHL 正在停用）；设置了报价货币却没有汇率；以及 International > Localization（Local units）中的店铺重量或尺寸单位不被模块识别（此时按 kg 或 cm 处理）。如果保存时某个值无效（名称为空或超过 64 个字符、数字无效或为负数、汇率为 0、最小重量大于最大重量、报价货币、发货国家或税务规则），错误会指出对应字段，该字段保留之前的值，其他设置仍会保存。
常规
Enable DHL Express Africa：开启或关闭该承运商。这与 Shipping > Carriers 中的承运商状态是同一个开关。
Name：顾客在结账时看到的承运商名称。默认：DHL Express。必填，最多 64 个字符。
Tax：承运商的税务规则，或 No tax。设置了税务规则（且店铺已启用税费）时，DHL 运费会扣除 DHL 报价中包含的税款后采用，再由 PrestaShop 添加其自身税款。选择 No tax 时，DHL 运费按报价原样收取（含税）。
DHL Express 账号（仅实时运费需要）
DHL API：使用哪种 DHL 接口。只显示所选 API 的字段。
API key：您的 MyDHL API 用户名（API key）。
API secret：您的 MyDHL API 密码（API secret）。保存后，API key 和 API secret 字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。
Remove the saved API key and API secret：仅在已保存 key 或 secret 时显示。开启后点击 Save，即可同时删除两者。
XML Site ID：您的 DHL XML Services Site ID（仅适用于旧版 API）。清空它也会删除已保存的 XML 密码。
XML password：您的 DHL XML Services 密码（仅适用于旧版 API）。与 API secret 一样，保存后不会再次显示。
DHL account number：您的 DHL Express 账号号码（9 位数字）。MyDHL API 需要该号码。使用 XML Services 时，返回的是您账户的运费，而不是公布的运费。
Test mode：使用 DHL 测试环境。默认开启。测试凭据仅在测试环境中有效，正式凭据仅在正式环境中有效。正式上线时请关闭。
Ship from
DHL 取件的地址。运费取决于该地址。
Origin country：您发货的国家。
Origin city：您发货的城市，例如 Johannesburg。MyDHL API 需要该城市。
Origin postcode：对于没有邮政编码的国家（例如肯尼亚、尼日利亚、加纳），请留空。
运费
所有价格均以您店铺的默认货币计算，不含税。实时运费是该包裹最便宜的 DHL Express 产品。如果 DHL 未配置、请求失败或该路线没有可用服务，则使用国家价格，再不行则使用备用运费。两者都没有时，承运商会被隐藏。
DHL quote currency：DHL 以您 DHL 账户所在国家的货币报价（例如 ZAR、NGN 或 KES）。如果 DHL 没有返回您店铺默认货币的金额，实时运费将按下方的汇率从该货币换算。否则不予使用。默认：— None —。
Exchange rate：DHL 报价货币的 1 个单位相当于店铺默认货币的多少，例如 1 ZAR = 0.05。必须大于 0。不需要换算时请留空。汇率为手动设置。
Fallback cost：在没有实时运费和国家价格时使用的固定费用。留空则在这种情况下隐藏该承运商。
Country prices：按目的国家设置的备用价格，每行一条：CC:Price，例如 ZA:25.00。在没有实时运费时使用。格式不同的行会被忽略，保存时的警告会列出这些行。
Fallback price basis：Per order 只收取一次价格。Per item (multiplied by the cart quantity) 按购物车商品数量相乘。仅适用于国家价格和备用运费。DHL 实时运费始终针对整个包裹。
Free shipping from：购物车小计（需要配送的商品，扣除折扣后、税前）达到此金额时，该承运商免运费。不会向 DHL 请求报价。留空则永不免运费。
条件
Minimum weight：购物车重量低于此值时隐藏该承运商（单位 kg）。0 表示不设限制。不能大于 Maximum weight。
Maximum weight：购物车重量高于此值时隐藏该承运商（单位 kg）。默认：70（字段为空时同样使用此值）。0 表示不设限制。
Minimum subtotal：仅当购物车小计（扣除折扣后、税前）不低于此金额时才显示该承运商。留空则始终显示。
无配送区域时的可用性
Ignore shipping zones：无需您为承运商手动分配区域即可提供该承运商。承运商会获得所有区域，包括您之后创建的区域，并由下方的国家决定是否可用。关闭后，承运商将恢复为其自己的区域。
Countries：该模式下的目的国家。留空则允许您配送的所有国家。仅与 Ignore shipping zones 一起使用。
高级
Debug log：将运费计算过程写入模块文件夹中的 logs/vfd_dhla_debug.log.php。该文件无法通过网页打开。即使此选项关闭，DHL 错误也始终会被记录。凭据和顾客地址从不记录。
Log：显示调试日志的大小和最新条目。点击 Clear log 可将其清空。
Remove data on uninstall：开启后，卸载模块时会删除设置、承运商、订单中保存的 DHL 产品以及日志。关闭后，所有数据都会保留，便于重新安装。
结账时的工作方式
在配送步骤，PrestaShop 会向模块请求 DHL Express 价格。只有实体商品才计入：虚拟商品不增加重量，也不计入小计。模块先检查条件：Ignore shipping zones 的国家、购物车重量和最低小计。若适用免运费，则价格为 0，不会向 DHL 发出请求。
否则，模块会向 DHL 发送发货地和收货地（国家、城市、邮政编码）、换算为 kg 的购物车重量（至少 0.5 kg），以及根据商品尺寸（单位 cm）组成的一个箱子：最长边长、最宽边宽和叠放后的高度。没有尺寸的商品不计入。若没有任何商品有尺寸，则使用 10 x 10 x 10 cm 的箱子。寄往其他国家的包裹会以购物车小计作为申报价值进行报关。国内包裹不报关。取件日期为今天；周末则为周一。只有在顾客输入城市之后（使用 XML Services 时，输入城市或邮政编码之后）才会请求实时运费。在此之前，适用备用价格。
最便宜的 DHL Express 产品会以一个价格显示，并使用您的承运商名称。顾客看不到 DHL 产品。价格以您的默认货币计算、取整，然后以顾客购物车的货币显示。
每个报价按每个包裹和路线缓存 1 小时。失败的请求缓存 10 分钟，这样结账页面在每次刷新时都不必等待 DHL。API 超时时间为 12 秒。如果 DHL 返回错误、没有服务，或以无法使用的货币回复，顾客不会看到任何错误：会使用备用价格，或隐藏该承运商。原因会写入调试日志。
如果您在承运商已有订单后，在 Shipping > Carriers 中编辑该承运商，PrestaShop 会将其保存为新版本的承运商。模块会自动跟随新版本。
模块仅计算运费。它不创建 DHL 运单，不打印面单或商业发票，不预约取件，不跟踪包裹，不提供 DHL 服务网点，不让顾客在 DHL 产品之间选择，不将多个箱子打包，不添加保险，也不计算关税和税费。报价仅针对运费。关税和进口税由收件人支付。
订单
下单时，模块会保存为其购物车计算出的运费。随后，后台订单页面会显示 DHL Express Africa 区块，方便您知道需要在 DHL 预订什么：
DHL product：实时运费对应的 DHL Express 产品，例如 "EXPRESS WORLDWIDE (P)"。仅在实时运费时显示。
Price source：Live DHL rate、Fallback price (no live rate) 或 Free shipping threshold。
Calculated price (excl. tax)：以您店铺默认货币计算的价格。
之后对购物车的重新计算（例如在后台编辑订单时）不会更改这些值。从未成为订单的购物车运费记录会在 30 天后删除。
许可证密钥
本模块需要来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox DHL Africa 许可证区块位于 Modules > Module Manager > VibeFox DHL Africa > Configure 页面中设置上方的第一个区块。在 License key 中输入密钥并点击 Activate。之后该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入另一个密钥）和 Remove key（从此店铺中移除该密钥）。其下方是 Product: presta-shipping-dhl-africa 这一行，以及 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 账户中释放名额。
没有有效密钥时，DHL Express 承运商不会在结账时显示给顾客，也不会计算任何运费。PrestaShop 前台无法得知您已登录后台，因此该承运商对您也会隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 的 Alerts 选项卡中会出现提醒。现有订单不受影响。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。在您使用后台期间会自动重新检查状态：输入密钥后的前 14 天每天检查一次，之后每周检查一次。无需 cron 任务。卸载或重置模块总会删除许可证密钥和许可证状态。
故障排除
结账时不显示 DHL Express：请检查许可证是否有效，以及 Enable DHL Express Africa 是否开启。在 Shipping > Carriers 中，检查该承运商是否覆盖顾客所在国家的区域和顾客所属的群组（或开启 Ignore shipping zones 并检查 Countries）。检查重量限制和 Minimum subtotal。没有实时运费时，只有设置了国家价格或备用运费，承运商才会出现。此外，产品页面也可能将商品限制为特定承运商。
实时运费不显示：请检查模块页面顶部的警告（缺少凭据或发货地）。开启 Debug log，刷新结账页面，然后查看模块页面上的 Log 字段。DHL 错误（例如 MyDHL API 的 HTTP 错误、该路线没有产品或货币问题）始终会被记录。检查 Test mode 是否与您的凭据匹配，并确认顾客地址中包含城市。
DHL 返回的是 ZAR、NGN 或 KES 运费，但我的店铺使用其他货币：日志显示 DHL quote not usable。请将 DHL quote currency 设为该货币，并填写 Exchange rate。否则不会使用实时运费，而是使用备用价格。
我有旧的 DHL XML Services 凭据：在 DHL API 中选择 XML Services (legacy)。收到 MyDHL 凭据后，请切换到 MyDHL API。
运费被重复征税：在 Tax 中设置税务规则，使 DHL 运费扣除 DHL 的增值税后采用；或者选择 No tax，按 DHL 报价原样收取。
修改后运费看起来过时：在模块页面点击 Save。这会清除缓存的 DHL 报价。
页面显示未找到 DHL Express 承运商：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块，以重新创建它。
面向开发者，模块提供以下钩子：actionVfdDhlaApiUrl、actionVfdDhlaIsDutiable、actionVfdDhlaPackageBox、actionVfdDhlaRestRequest 和 actionVfdDhlaXmlRequest，用于修改 API 地址、海关申报、箱子以及 DHL 请求。
卸载
前往 Modules > Module Manager，打开 VibeFox DHL Africa 旁边的菜单，选择 Uninstall。许可证密钥、许可证状态和缓存的 DHL 报价始终会被删除。如果 Remove data on uninstall 已开启，承运商会被删除（订单保留其历史记录），同时删除设置、订单中保存的 DHL 产品以及日志。如果已关闭，承运商仅会被停用，设置以及已下单订单的 DHL 产品会保留。重新安装模块后，会恢复承运商之前的状态。
DHL 是其各自所有者的商标。本模块与 DHL 无关联，也未获得 DHL 的认可。