VibeFox DHL Africa for WooCommerce — 帮助
系统要求
WordPress：5.8 或更高版本。
WooCommerce：5.0 或更高版本，已安装并启用。没有 WooCommerce 时插件无法激活。
PHP：8.0 或更高版本。
DHL Express 账户（仅用于实时运费）：实时运费使用 MyDHL API。您需要 DHL Express 账号以及 MyDHL API 凭据：API 密钥和 API secret。可在 DHL Developer Portal（MyDHL API，"Get access"）申请，或向您的 DHL Express 客户经理索取。仍持有 DHL XML Services 凭据（Site ID 和密码）的账户可改用这些凭据。若您只使用备用价格，则无需 DHL 凭据。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥仅适用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 vfd_dhl_africa 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Shipping > DHL Express Africa，或在插件列表页点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 选择 DHL API，输入 API 密钥、API secret 和您的 DHL 账号。使用测试凭据时请保持 Test mode 开启。填写 Ship from 发货地址。如果您的 DHL 账户不以店铺货币结算，请设置 DHL quote currency 和 Exchange rate。可选设置按国家价格和备用运费（参见“配置”）。
6. 在 WooCommerce > Settings > Shipping > Shipping zones 中，将 DHL Express Africa 添加到您的配送区域；或开启 Ignore shipping zones 并选择国家。
配置
所有设置位于同一页面：WooCommerce > Settings > Shipping > DHL Express Africa。它们适用于所有配送区域。将该方式添加到某个区域时，区域窗口只有一个字段：
Title (zone): 该区域结账时此选项的名称。留空则使用全局 Name。
设置上方的警告会提示：因凭据或发货地缺失而关闭实时运费，以及设置了报价货币但未设置汇率。每次保存设置时，缓存的 DHL 报价都会被清除。价格和重量可输入小数点或小数逗号。
常规
Enable/Disable: 一次性在所有区域中开启或关闭该方式。
Name: 结账时显示的配送方式名称。默认：DHL Express。
Tax status: Taxable（需启用 WooCommerce 税费）采用不含 DHL 报价税费的 DHL 运费，并由 WooCommerce 添加其自身税款。None 则按报价收取 DHL 运费（含税）。
DHL Express 账户（仅实时运费需要）
DHL API: 使用哪种 DHL 接口。仅显示所选 API 的字段。
API key: 您的 MyDHL API 用户名（API 密钥）。
API secret: 您的 MyDHL API 密码（API secret）。
XML Site ID: 您的 DHL XML Services Site ID（仅限旧版 API）。
XML password: 您的 DHL XML Services 密码（仅限旧版 API）。
DHL account number: 您的 DHL Express 账号（9 位数字）。MyDHL API 要求填写此项。使用 XML Services 时，返回的是您的账户运费，而非公开牌价。
Test mode: 使用 DHL 测试环境。默认开启。测试凭据仅适用于测试环境，正式凭据仅适用于正式环境。正式上线时请关闭。
发货地
DHL 上门取件的地址。运费取决于该地址。
Origin country: 您发货的国家。
Origin city: 您发货的城市，例如 Johannesburg。MyDHL API 要求填写此项。
Origin postcode: 对于没有邮政编码的国家（例如肯尼亚、尼日利亚、加纳），请留空。
运费
所有价格均以您的店铺货币计。实时运费为该包裹最便宜的 DHL Express 产品。若 DHL 未配置、请求失败或该路线无可用服务，则使用国家价格，其次使用备用运费。两者均未设置时，隐藏该配送方式。
DHL quote currency: DHL 以您 DHL 账户所在国家的货币报价（例如 ZAR、NGN 或 KES）。若 DHL 未返回您店铺货币的金额，则实时运费将按下方汇率从该货币换算。否则不予使用。
Exchange rate: 1 个 DHL 报价货币等于多少您的店铺货币，例如 1 ZAR = 0.05。留空则不进行换算。该汇率为手动设置。
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): 购物车重量高于此值时隐藏该方式。默认：70。0 表示无限制。
Minimum subtotal: 仅当购物车小计至少达到此金额时显示该方式。留空则始终显示。
Excluded shipping classes: 若购物车中包含属于这些 WooCommerce 配送类别的商品，则隐藏该方式。
不使用配送区域时的可用性
Ignore shipping zones: 即使匹配的配送区域中未包含此配送方式，也为下方国家提供该方式。
Countries: 该模式下的目的国家。留空则使用您所有可发货的国家。仅在开启 Ignore shipping zones 时使用。
高级
Debug log: 在 WooCommerce > Status > Logs 中记录运费计算，来源为 vfd-dhl-africa。即使关闭此项，DHL 错误仍会被记录。凭据和顾客地址永不记录。
Remove data on uninstall: 开启后，删除插件时会移除其设置和区域配送方式。停用插件不会删除任何数据。
结账时的工作方式
顾客输入收货地址时，WooCommerce 会向插件请求运费。插件首先检查购物车重量、最低小计和排除的配送类别。若适用免运费，顾客即可免费配送，且不会向 DHL 发送请求。
否则，插件会向 DHL 发送发货地和收货地（国家、城市、邮政编码）、换算为公斤的购物车重量（至少 0.5 公斤），以及根据商品尺寸（厘米）生成的一个箱子：最长边长、最宽边宽和叠放后的总高度。没有尺寸的商品不计入。若所有商品都没有尺寸，则使用 10 x 10 x 10 厘米的箱子。国际运输以货物形式申报，申报价值为购物车小计，以便 DHL 按包裹商品报价。国内运输不申报。只有顾客填写城市后（使用 XML Services 时，填写城市或邮政编码即可），才会请求实时运费。
最便宜的 DHL Express 产品会以您设定的名称显示为一个运费选项。顾客看不到 DHL 产品或送达时间。产品名称（例如 "EXPRESS WORLDWIDE (P)"）会以 DHL product 的形式保存在订单的配送明细中，便于您据此预订。
每个报价按每个包裹和路线缓存 1 小时。失败的请求缓存 10 分钟，因此每次刷新结账页面时都不必等待 DHL。API 超时时间为 12 秒。若 DHL 返回错误或无可用服务，顾客不会看到任何错误：将使用备用价格，或隐藏该方式。
该方式适用于经典结账页面以及购物车和结账区块。兼容 WooCommerce 高性能订单存储（HPOS）。
插件仅计算运费。它不创建 DHL 运单，不打印面单或商业发票，不预约取件，不跟踪包裹，不提供 DHL 服务网点，不允许顾客在 DHL 产品之间选择，不打包多个箱子，不提供保险，也不估算关税和税费。报价仅针对运费。关税和进口税由收件人支付。
许可证密钥
本插件需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Shipping > DHL Express Africa 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期截止日期和您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从此站点移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。
一个密钥仅适用于一个域名。从站点移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。
没有有效密钥时，DHL Express 不会显示给结账的顾客。已登录的店铺管理员仍可看到该方式，并标注 (unlicensed — visible to admins only)，以便您在购买密钥前完成设置和测试。插件页面和 WooCommerce 页面会显示提醒。现有订单不受影响。
许可证到期后，插件仍可继续工作，但更新和支持需要续费。系统会在后台自动重新检查状态。
故障排除
结账时不显示 DHL Express：请检查许可证是否有效、Enable/Disable 是否开启，以及该方式是否已添加到顾客所在国家的区域中（或已开启 Ignore shipping zones 且该国家被允许）。检查重量限制、Minimum subtotal 和 Excluded shipping classes。没有实时运费时，只有设置了国家价格或备用运费，该方式才会显示。
实时运费不显示：请检查设置页面顶部的警告（凭据或发货地缺失）。开启 Debug log，然后打开 WooCommerce > Status > Logs，来源选择 vfd-dhl-africa。凭据错误、该路线无可用服务或货币问题等 DHL 错误始终会被记录。请检查 Test mode 是否与您的凭据匹配。
DHL 以 ZAR、NGN 或 KES 返回运费，但我的店铺使用其他货币：将 DHL quote currency 设为该货币，并输入 Exchange rate。否则不会使用实时运费，而是采用备用价格。
我有旧的 DHL XML Services 凭据：在 DHL API 中选择 XML Services (legacy)。收到 MyDHL 凭据后，请切换到 MyDHL API。
运费被重复征税：将 Tax status 设为 Taxable，使 DHL 运费扣除 DHL 增值税后采用；或设为 None，按报价收取 DHL 金额。
修改后运费似乎过时：保存设置页面，这将清除缓存的 DHL 报价。
许可证区块显示错误：请按区块中的提示操作。例如，若密钥已在另一个域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。若站点地址已更改，请点击 Check now 为新域名激活密钥。若无法连接许可证服务器，插件将沿用最后已知的状态继续工作。
卸载
停用插件会保留所有设置，只清除缓存的 DHL 报价。若要移除插件，请在 Plugins 页面停用并删除。本插件的许可证密钥和许可证状态始终会被移除，缓存的报价也会被移除。只有开启了 Remove data on uninstall 时，设置和区域配送方式才会被移除；否则将保留，以便日后重新安装时使用。订单永远不会被修改，现有订单将保留其配送明细。
DHL 是其各自所有者的商标。本插件与 DHL 无隶属关系，也未获得 DHL 认可。