VibeFox DHL Africa for OpenCart — 帮助
系统要求
OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP：8.0 或更高版本，并启用 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 购买。一个密钥只能用于一个域名。
安装
下载文件是一个 zip 压缩包，内含适用于两个 OpenCart 版本的安装包。请先在您的电脑上解压。压缩包包含 README.txt、OpenCart 3 安装包 vfd_dhl_africa-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 vfd_dhl_africa.ocmod.zip。只需安装与您的 OpenCart 版本对应的安装包。两个版本使用同一个许可证密钥。
OpenCart 3
1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_dhl_africa-oc3-(version).ocmod.zip。本扩展不添加 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装器，而是将安装包中 upload 文件夹的内容复制到店铺的根目录。
2. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox DHL Africa，点击 Install（绿色 + 按钮）。
3. 点击 Edit（铅笔按钮）打开设置页面。
4. 在 Edit 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥粘贴到 License key，然后点击 Activate（参见 License key）。
5. 选择 DHL API，输入 API key、API secret 和您的 DHL 账号号码。使用测试凭据时请保持 Test mode 开启。输入 Ship from 地址。如果您的 DHL 账户不是以店铺默认货币结算，请设置 DHL quote currency 和 Exchange rate。可选择设置按国家的价格和备用运费（参见 Configuration）。开启 Enable DHL Express Africa，然后点击 Save。
OpenCart 4
1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_dhl_africa.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包无法使用。
2. 安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。
3. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox DHL Africa，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按照 OpenCart 3 第 4 和第 5 步的说明输入许可证密钥和设置。两个版本的设置页面及其字段相同。
安装后，该配送方式保持关闭，直到您开启 Enable DHL Express Africa 并保存。如果您卸载后重新安装本扩展，之前保留的 DHL 设置将再次生效。
配置
所有设置都位于扩展页面：Extensions > Extensions > Shipping > VibeFox DHL Africa > Edit。各部分列在左侧。点击一个 Save 按钮即可保存整个页面，无需重新加载。每次保存也会清除已缓存的 DHL 报价。价格和重量可接受小数点或小数逗号。只有拥有本扩展修改权限的管理员用户才能保存设置。
页面顶部的警告会告诉您实时运费何时被关闭：缺少 API key、API secret 或账号号码时（使用 XML Services 时则为 Site ID 或密码），缺少始发国家或城市时，选择了 XML Services 时（DHL 正在停止提供），设置了报价货币却没有汇率时，以及店铺的重量或长度单位无法被扩展识别时（此时商品重量按 kg、尺寸按 cm 读取；请在 System > Localisation > Weight Classes 中添加单位为 kg 的重量类别，或在 System > Localisation > Length Classes 中添加单位为 cm 的长度类别）。
如果保存时某个值无效（配送方式名称为空或超过 64 个字符、数字无效或为负数、汇率为 0、最低重量高于最高重量、报价货币、始发国家、税种或地理区域未知、排序值不是整数），设置上方的警告会指出该字段，例如 Select a valid origin country. It was not saved. 该字段保留原值，其他设置正常保存。
常规
Enable DHL Express Africa：在结账时显示或隐藏 DHL Express。默认：off。
Method title：结账时显示给顾客的配送方式名称。默认：DHL Express。必填，最多 64 个字符。
Tax class：配送费用的税种，或 No tax（默认）。设置税种时（且店铺已启用税费），DHL 运费将不含 DHL 报价中的税费，OpenCart 再添加其自身的税费。选择 No tax 时，DHL 运费按报价原样收取，税费已包含在内。
Sort order：DHL Express 在结账时各配送方式中的排列位置。一个整数。
DHL Express 账号（仅实时运费需要）
DHL API：使用哪个 DHL 接口。
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：仅在 MyDHL API 下、且已保存密钥或 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 测试环境。默认开启。测试凭据仅在测试环境中有效，正式凭据仅在正式环境中有效。正式上线时请关闭。
发货地址
DHL 取件的地址。运费取决于该地址。OpenCart 将店铺地址保存为自由文本，因此始发地始终需要在此处填写。本部分的提示会显示您的店铺所在国家。
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 (kg)。
Maximum weight (kg)：购物车重量高于此值时隐藏该配送方式。默认：70（字段为空时也使用此值）。0 表示不限制。
Minimum subtotal：仅当需要配送的商品小计（使用优惠券后、税前）至少为此金额时才显示该配送方式。留空则始终显示。
可用性
Geo zone：仅向该地理区域内的地址提供 DHL Express。All zones（默认）表示不限制。地理区域在 System > Localisation > Geo Zones 中管理。使用 Ignore shipping zones 时不做检查。
Ignore shipping zones：无论所选地理区域为何，都为下方列出的国家提供该配送方式（列表为空时为所有国家）。
Countries：该模式下的目的国家。仅与 Ignore shipping zones 一起使用。
高级
Debug log：将运费计算记录到 storage/logs/vfd_dhla_debug.log.php（OpenCart 4 中为 system/storage/logs/vfd_dhla_debug.log.php）。该文件无法通过网页读取。即使此选项关闭，DHL 错误也始终会被记录。凭据、账号号码和顾客地址从不写入日志。当文件达到 5 MB 时，它会被移动到 vfd_dhla_debug.old.log.php，并开始新的日志。
Log：显示调试日志的大小和最新条目。点击 Clear log 可清空。
Remove data on uninstall：开启后，卸载扩展时将删除设置、已缓存的 DHL 报价和日志。关闭（默认）时，所有内容都会保留，以便重新安装。已下单的 DHL 产品信息始终保留。
导入 / 导出
Export：点击 Download JSON 将设置保存为 JSON 文件。API key、API secret 和 XML 密码不会被导出。
Import：粘贴之前导出的 JSON，然后点击 Import 恢复设置，例如在另一家店铺中使用。这些值会像正常保存一样进行检查。已保存的凭据保持不变。
结账时的工作方式
当 OpenCart 显示配送方式时，它会向扩展请求 DHL Express 的价格。如果设置了 Geo zone（且 Ignore shipping zones 处于关闭状态），而地址不在该区域内，则不提供 DHL Express。只有 Requires Shipping 设为 Yes 的商品才计入：其他商品不增加重量，也不计入小计。然后扩展检查条件：Ignore shipping zones 中的国家、购物车重量和最低小计。小计是需要配送的商品价格，即使用优惠券折扣后、税前的金额。礼品卡、积分奖励和店铺余额不计入在内。如果适用免运费，价格为 0，且不会向 DHL 发送请求。
否则，扩展会向 DHL 发送始发地和目的地（国家、城市、邮政编码）、由商品重量级别换算为 kg 的购物车重量（至少 0.5 kg），以及根据商品尺寸构建的一个 cm 单位的箱子：最长的长度、最宽的宽度和叠放的高度。没有尺寸的商品不增加任何内容。如果没有任何商品有尺寸，则使用 10 x 10 x 10 cm 的箱子。发往其他国家的包裹会以购物车小计作为申报价值进行海关申报。国内包裹不予申报。取件日期为店铺时区的当天，周末则为周一。只有在顾客输入城市后才会请求实时运费（使用 XML Services 时为城市或邮政编码）。在此之前，适用备用价格。
最便宜的 DHL Express 产品会以一个价格显示，并使用您的配送方式名称。顾客看不到 DHL 产品。价格以您的默认货币计算，按其小数位数取整，并以顾客的货币显示，同时包含所选 Tax class 的税费。
每个报价按每个包裹和路线缓存 1 小时。失败的请求缓存 10 分钟，这样结账就不会在每次刷新时都等待 DHL。API 超时时间为 12 秒。如果 DHL 返回错误、没有可用服务或以无法使用的货币作答，顾客不会看到错误：会使用备用价格，或者隐藏该配送方式。原因会写入调试日志。
本扩展仅计算运费。它不会创建 DHL 运单、打印面单或商业发票、预约取件、追踪包裹、提供 DHL 服务网点、让顾客在 DHL 产品之间进行选择、将多个包裹装箱、添加保险或计算关税和税费。报价仅针对运费。关税和进口税由收件人支付。
在 OpenCart 4 中，顾客在结账页面的配送方式区块中点击 Choose，并在 Shipping method options 窗口中选择 DHL Express。该配送方式的工作方式与 OpenCart 3 相同。
订单
下单时，扩展会保存为其购物车计算出的运费。在 Sales > Orders 中打开订单：订单历史上方的 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)：以店铺默认货币计算的价格。
DHL 产品不会显示在发给顾客的电子邮件中，也不会显示在顾客的订单页面上。订单会像其他任何 OpenCart 配送方式一样显示配送方式名称和运费。
在 OpenCart 4 中，结账会保留一个订单，并在顾客每次重新确认时更新该订单。面板随后显示结账的最新运费。如果顾客切换到其他配送方式，则该订单不再显示此面板。
许可证密钥
本扩展需要使用来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox DHL Africa 许可证区块是 Extensions > Extensions > Shipping > VibeFox DHL Africa > Edit 页面中位于设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now 用于重新检查状态，Change key 用于输入其他密钥，Remove key 用于从本店铺中移除密钥。它们下方是 Product: opencart-shipping-dhl-africa 一行，以及用于打开您 vibefox.net 账户的链接 Manage licenses and domains in your account。只有拥有本扩展 Modify 权限的管理员用户才能更改密钥。该区块的文字跟随后台语言显示（包括英文和俄文）。
如果密钥未被接受，该区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached 或 License expired on 及一个日期。修改店铺地址后，或在您的账户中释放一个域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展将继续使用最后一次已知的状态。
一个密钥只能用于一个域名，即 OpenCart 配置中的店铺地址。从店铺中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效的许可证密钥时，结账时不会向顾客显示 DHL Express 配送方式，也不会计算运费。以同一浏览器登录后台的管理员用户仍会在店铺中看到该配送方式，并标记为 (unlicensed — visible to admins only)，这样您可以在购买密钥之前完成设置和测试。在 OpenCart 4 中，此预览不可用：店铺无法看到后台登录状态，因此没有有效密钥时，该配送方式对所有人都隐藏。您打开一次 Edit 页面后，后台 Dashboard 上会出现提醒。点击 × 可将其隐藏 7 天。现有订单不受影响。
许可证到期后，扩展仍会继续运行，但更新和支持需要续费。当您打开后台的 Dashboard 或 Edit 页面时，系统会自动重新检查状态：输入密钥后的前 14 天每天检查一次，之后每周检查一次。无需设置定时任务。卸载扩展时，始终会删除许可证密钥和许可证状态。
故障排除
结账时没有显示 DHL Express：请检查许可证是否有效，以及 Enable DHL Express Africa 是否已开启。检查 Geo zone（或开启 Ignore shipping zones 并检查 Countries）、重量限制和 Minimum subtotal。没有实时运费时，只有设置了国家价格或备用运费，该配送方式才会显示。检查产品的 Requires Shipping 是否设为 Yes。
实时运费没有显示：请检查扩展页面顶部的警告（缺少凭据或始发地）。开启 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 class，使 DHL 运费不含 DHL 的税费；或选择 No tax，按报价原样收取 DHL 金额。
修改后运费看起来已过时：在扩展页面上点击 Save。这会清除已缓存的 DHL 报价。
页面显示 "Warning: You do not have permission to modify VibeFox DHL Africa!"：您的管理员用户组可能只有查看设置的权限。请在 System > Users > User Groups 中为该组授予 extension/shipping/vfd_dhl_africa（OpenCart 3）或 extension/vfd_dhl_africa/shipping/vfd_dhl_africa（OpenCart 4）的修改权限。
面向开发者：本扩展会触发 OpenCart 事件 catalog/vfd_dhl_africa/api_url、is_dutiable、package_box、rest_request 和 xml_request（使用相同前缀），这些事件可以更改 API 地址、海关申报、箱子以及发给 DHL 的请求。
卸载
进入 Extensions > Extensions，选择类型 Shipping，然后点击 VibeFox DHL Africa 旁边的 Uninstall（红色 − 按钮）。本扩展的许可证密钥和许可证状态始终会被删除。OpenCart 总会重置 Enable DHL Express Africa、Sort order、Tax class 和 Geo zone。已缓存的 DHL 报价和扩展的事件总会被删除。如果开启了 Remove data on uninstall，DHL 设置和调试日志也会被删除。如果关闭，其他设置将保留，并在您重新安装扩展时再次使用。已下单的 DHL 产品信息永远不会被删除。现有订单保留其配送方式和费用。
在 OpenCart 4 中，若要同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox DHL Africa 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。
DHL 是其各自所有者的商标。本扩展与 DHL 无关联，也未获得 DHL 的认可。