VibeFox DHL Packstation for OpenCart — 帮助
系统要求
OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。取货点选择器适用于 OpenCart 标准结账流程。
PHP：8.0 或更高版本。
DHL API 密钥：取货点列表来自免费的 DHL Location Finder API。请在 DHL 开发者门户（developer.dhl.com）注册，创建一个应用，添加 “Location Finder - Unified” API，然后复制该应用的 API 密钥。使用该 API 无需与 DHL 签订商务合同。没有密钥时，该配送方式在结账时会被隐藏。请注意您 DHL 应用的请求次数限制：每次新的邮编或城市搜索都会消耗一次 API 请求。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
下载文件是一个 zip 压缩包，内含两个 OpenCart 版本的安装包。请先将其解压到您的电脑上。压缩包中包含 README.txt、OpenCart 3 安装包 vfd_dhl_packstation-oc3-(version).ocmod.zip，以及 OpenCart 4 安装包 vfd_dhl_packstation.ocmod.zip。只安装与您的 OpenCart 版本相符的安装包。两个版本使用相同的许可证密钥。
OpenCart 3
1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_dhl_packstation-oc3-(version).ocmod.zip。本扩展不添加 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装器，而是将本安装包中 upload 文件夹的内容复制到店铺的根目录。
2. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox DHL Packstation，点击 Install（绿色 + 按钮）。
3. 点击 Edit（铅笔按钮）打开设置页面。
4. 在 Edit 页面顶部的许可证区块中，将 VibeFox 许可证密钥粘贴到 License key 中，然后点击 Activate（参见许可证密钥）。
5. 粘贴 DHL API 密钥，点击 Save，然后点击 Test API key。选择取货点类型并输入各国价格（参见 Configuration）。开启 Enable/Disable，然后点击 Save。
OpenCart 4
1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_dhl_packstation.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名中读取扩展代码，重命名后的安装包将无法使用。
2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。
3. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox DHL Packstation，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按照 OpenCart 3 的第 4 和第 5 步输入许可证密钥和设置。两个版本的设置页面及其字段相同。
安装后，该配送方式保持关闭，直到您开启 Enable/Disable 并保存。默认价格表包含德国和奥地利的价格，以及其他国家的一个价格。如果您卸载后重新安装本扩展，之前保留的设置将再次生效。
配置
所有设置都位于扩展页面：Extensions > Extensions > Shipping > VibeFox DHL Packstation > Edit。各部分列在左侧。点击一个 Save 按钮即可保存整个页面，无需重新加载。每次保存都会清除取货点缓存。如果某个字段有误（名称无效或超过 64 个字符，半径或结果数量不是整数，数字无效或为负数，Min weight (kg) 大于 Max weight (kg)，排序值不是整数，税种或地理区域未知），则不会保存任何内容，并显示错误信息。只有拥有本扩展修改权限的管理员用户才能保存设置。
页面顶部的警告会告诉您：DHL API 密钥为空时、未启用任何网点类型时（这两种情况下该配送方式在结账时都不会显示）、国家价格条目不是 CC:PRICE 格式时（这些条目会被忽略），以及 System > Localisation > Weight Classes 中没有单位为 kg 的重量类别时（此时商品重量将根据其类别的单位名称读取：kg、g、lb 或 oz，未知单位按 kg 处理）。
常规
这些设置适用于所有地理区域。
Enable/Disable：在结账时启用 DHL Packstation。默认：off。
Name：显示给顾客的配送方式名称。默认：DHL Packstation。必填，最多 64 个字符，且不能包含以下字符：< > ; = # { }。
Tax Class：配送费用的税种，或 --- None ---（默认）。OpenCart 会在下方价格之上加收此税。选择 --- None --- 时，价格即为最终价格。
Sort Order：DHL Packstation 在各配送方式中的排列位置。一个整数。
DHL Location Finder API
DHL API key：您在 developer.dhl.com 上应用的 “API Key”。没有它，该配送方式在结账时会被隐藏。保存后，该字段保持为空并显示 Saved - leave empty to keep it. 仅在需要更改时才输入新值。
Remove the saved API key：在已保存密钥时显示。勾选此框并保存，即可删除已保存的密钥。
Connection test：Test API key 按钮会使用已保存的密钥搜索 53113 Bonn 附近的网点，并清除取货点缓存。请先保存设置。它会显示找到的网点数量（Connected: … DHL locations found near 53113 Bonn.）、DHL 拒绝了该密钥（401/403），或 API 未正确响应（详情见调试日志）。
取货点
在结账时，顾客会看到其配送邮编附近的网点，并可以搜索其他邮编或城市。
Location types：顾客可以选择的 DHL 网点：Packstation (parcel locker)、Post Office (Postfiliale) 和 DHL Parcel Shop (Paketshop)。默认全部启用。如果一个都不选，该配送方式会被隐藏。选择 Packstation 时，顾客必须输入其 DHL Postnummer。
Search radius (meters)：所搜索邮编或城市周围的半径。默认：5000。必须为整数；低于 100 或高于 25000 m（DHL 的最大值）的数值会被调整为该限值。
Max results：每次搜索显示的最大网点数量。默认：20。必须为整数；DHL 最多允许 50，更大的值会被降至 50。
Shipping address：将所选网点用作订单的配送地址。默认开启。地址第 1 行会变为例如 “Packstation 105”（邮局或 Parcel Shop 则为 “Postfiliale 502”），第 2 行为 “Postnummer” 加上编号，并附上网点的邮编、城市和国家，这样从订单打印的面单才会送到正确的地点。姓名、公司和电话取自顾客的地址。省/州字段会被清空。顾客的地址簿不会被修改。
价格（该部分标题显示您店铺的默认货币）
Country prices：按目的国家设置的价格，使用店铺默认货币，不含税，格式为 CC:PRICE，以逗号或换行分隔。默认：DE:4.99, AT:5.99。也支持小数逗号（DE:4,99）。
Other countries：未包含在 Country prices 中的目的国家的价格。默认：5.99。留空则对这些国家隐藏该配送方式。
Calculation：Per order（默认）只收取一次价格。Per item (price x quantity) 则按购物车中的商品数量相乘。
Free shipping from：需要配送的商品小计（使用优惠券后、税前）达到该金额时，此配送免费。留空则从不免运费。
可用性
Min weight (kg)：购物车的最低重量。商品重量会根据其重量类别进行换算。0 表示不限制（默认）。
Max weight (kg)：购物车重量超过此值时，该配送方式会被隐藏。默认：31.5，因为一个 Packstation 最多可接收 31.5 kg 的包裹。0 表示不限制。
Minimum subtotal：仅当需要配送的商品小计（使用优惠券后、税前）达到此值时才显示该配送方式。留空则始终显示。
Geo Zone：仅在此地理区域提供该配送方式。All Zones（默认）表示不限制。地理区域在 System > Localisation > Geo Zones 中管理。与 Ignore shipping zones 同时使用时不生效。
Ignore shipping zones：开启后，无论地址位于哪个地理区域，都会为下方列出的国家提供该配送方式（列表为空时为所有国家）。
Countries (ignore zones)：该模式下的目的国家。仅与 Ignore shipping zones 一起使用。
高级
Debug log：将 API 请求和结账步骤写入 storage/logs/vfd_dhlp_debug.log.php（在 OpenCart 4 中为 system/storage/logs/vfd_dhlp_debug.log.php）。该文件无法通过网页读取。即使此选项关闭，API 错误也始终会被记录。API 密钥、Postnummer 和顾客地址从不写入。当文件达到 5 MB 时，它会被移动到 vfd_dhlp_debug.old.log.php，并开始新的日志。
Log：显示调试日志的大小和最新条目。点击 Clear log 可清空。
Remove data on uninstall：开启后，卸载扩展时将删除设置、缓存的搜索结果、日志以及未完成结账的取货点。已选的取货点仍保留在订单中。关闭（默认）时，所有内容都会保留，以便重新安装。
导入 / 导出
Export：点击 Download JSON 将设置保存为 JSON 文件。API 密钥不会被导出。
Import：粘贴之前导出的 JSON，然后点击 Import 恢复设置，例如在另一家店铺中使用。这些值会像正常保存一样进行检查。已保存的 API 密钥保持不变。
结账时的工作方式
当 OpenCart 显示配送方式时，它会向扩展请求 DHL Packstation 的价格。如果设置了 Geo Zone（且 Ignore shipping zones 处于关闭状态），而地址不在该区域内，则不提供该配送方式。只有 Requires Shipping 设为 Yes 的商品才计入：其他商品不增加重量，也不计入小计。扩展会检查 API 密钥和至少一个网点类型是否已设置、允许的国家（使用 Ignore shipping zones 时）、购物车重量以及最低小计。然后它会获取目的国家的价格（或其他国家的价格），若小计足够高则应用免运费。小计是需要配送的商品价格，即使用优惠券折扣后、税前的金额。价格与取货点无关，计算价格时不会向 DHL 发送任何请求。价格以您的默认货币计算，并以顾客的货币显示，同时包含所选 Tax Class 的税费。
扩展不会创建 DHL 运单、打印面单或追踪包裹。请使用 DHL 的商业客户门户或面单工具：开启 Shipping address 后，订单中已包含 Packstation 地址和 Postnummer。扩展不计算 DHL 实时运费，也不显示地图。没有手动输入 Packstation 编号的功能。
取货点
当顾客在配送方式步骤中选择 DHL Packstation 时，该方式下方会出现一个选择器。系统会加载配送邮编和城市附近的 DHL 网点。顾客可以输入其他邮编或城市，然后点击 Search。网点按类型分组（Packstation、Post Office、Parcel Shop）并按距离排序。若未找到任何结果，顾客会看到 No DHL locations found near "…". Try another postcode or city.
对于 Packstation，顾客必须输入 DHL Postnummer，即其 6 至 12 位的 DHL 客户号，可在 DHL 应用或 DHL 账户中找到。对于其他网点，该项为可选。一旦做出选择，就会立即保存。点击 Continue 时，服务器会再次检查：所选网点必须是配送国家中 DHL 搜索结果之一。如果没有选择网点，顾客会看到 Please choose a DHL Packstation or post office for delivery. 并无法继续。若 Packstation 缺少 Postnummer，会显示 Please enter your DHL Postnummer - it is required for delivery to a Packstation.；若 Postnummer 无效，则显示 The DHL Postnummer must consist of 6 to 12 digits.
搜索结果缓存 12 小时。空的或失败的搜索缓存 10 分钟，这样结账时就不会在每次刷新时都等待 DHL。在 OpenCart 默认的文件缓存下，缓存条目的有效期最长与店铺缓存生命周期相同（默认为 1 小时），因此列表每小时刷新一次。API 超时时间为 12 秒。如果无法连接 DHL API，顾客会看到 DHL locations cannot be loaded right now. Please try again later or choose another shipping method. 顾客此前已选择的网点仍会被接受。
在 OpenCart 4 中，顾客在结账页面的配送方式区块中点击 Choose，并在 Shipping method options 窗口中选择 DHL Packstation。取货点选择器会在该窗口中显示在配送方式下方，并按上文所述工作。窗口中的 Continue 按钮在没有有效取货点、或（对于 Packstation）没有 Postnummer 时无法继续，并显示相同的提示信息。
订单提交后，网点信息（ID、类型、编号、名称、地址）和 Postnummer 会随订单一起保存。网点会以 DHL pickup location: 和 DHL Postnummer: 的形式添加到订单的配送方式中，因此会出现在 OpenCart 显示配送方式的所有位置：顾客的订单页面、订单电子邮件和发票。如果 Shipping address 已开启，订单的配送地址将被替换为该网点的地址。
OpenCart 4 会为结账保留一个订单，并在顾客每次重新确认时更新该订单。取货点、配送方式文本和订单地址会随之一并更新。
订单
在 Sales > Orders 中打开订单。订单历史上方的 DHL pickup location 面板会显示网点、其类型和 ID，以及 Postnummer，即使扩展已关闭也会显示。没有网点的订单会显示 No DHL location was selected for this order.
点击 Change，按邮编或城市搜索，从 DHL 列表中选择其他网点，如有需要可修改 Postnummer，然后点击 Save location。您也可以只修改 Postnummer。订单的配送方式文本会随之更新。如果 Shipping address 已开启，订单的配送地址也会更新，且会从顾客的原始地址重新开始。每次修改都会在订单历史中添加一条 DHL pickup location changed to: … 记录，并附带当前订单状态，且不会通知顾客。修改取货点需要订单的修改权限；无需访问扩展设置。
许可证密钥
本扩展需要使用来自 vibefox.net 的 VibeFox 许可证密钥。扩展的 Extensions > Extensions > Shipping > VibeFox DHL Packstation > Edit 页面中，位于设置上方的第一个区块是许可证区块 License — VibeFox DHL Packstation。将密钥粘贴到 License key 中并点击 Activate。之后，该区块会以掩码形式显示密钥，并显示状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺移除密钥）。它们下方有一行 Product: opencart-shipping-dhl-packstation，以及一个 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 账户中释放该名额。
没有有效的密钥时，结账时不会向顾客显示 DHL Packstation 配送方式，也不会计算运费。在同一浏览器中登录后台的管理员用户，仍会在店铺中看到该配送方式，并标注为 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试扩展。在 OpenCart 4 中没有此预览功能：店铺无法看到后台登录状态，因此没有有效密钥时，该配送方式对所有人都隐藏。打开一次 Edit 页面后，后台的 Dashboard 上会出现提醒。点击 × 可将其关闭，隐藏 7 天。现有订单不受影响。
许可证到期后，扩展仍会继续工作，但更新和支持需要续费。当您打开后台的 Dashboard 或 Edit 页面时，系统会自动再次检查状态：输入密钥后的前 14 天每天检查一次，之后每周检查一次。无需设置 cron 任务。卸载扩展时总会移除许可证密钥和许可证状态。
故障排除
结账时没有显示 DHL Packstation：请检查许可证是否有效，以及 Enable/Disable 是否已开启。检查 Geo Zone（或开启 Ignore shipping zones 并检查 Countries (ignore zones)）。确认 DHL API key 已填写，至少选择了一个网点类型，目的国家有价格（或已设置 Other countries），并且重量和小计规则没有将其隐藏。检查产品的 Requires Shipping 是否设为 Yes。
没有显示任何网点：点击 Test API key。如果 DHL 拒绝该密钥（401/403），请检查密钥，并确认您的应用已添加 “Location Finder - Unified” API。开启 Debug log，重新加载结账页面，然后查看扩展页面上的 Log 字段。确认您的 DHL 应用未达到请求次数限制。
某地址附近没有网点：增大 Search radius (meters) 或 Max results，或让顾客搜索其他邮编或城市。DHL 数据中没有编号的 Packstation 不会被列出。
顾客看到 “Enter your postcode or city to see DHL locations near you.”：配送地址中既没有邮编也没有城市。顾客可以在搜索框中输入其中之一。
后台订单页面的 Change 显示 “Please choose a DHL location of the search - nothing was changed.”：请按邮编或城市搜索，并从结果中选择一个网点。如果订单还没有网点，必须先选择网点才能保存 Postnummer。
订单页面缺少 DHL pickup location 面板：该面板仅对使用 DHL Packstation 发货的订单显示（即使扩展已关闭，仍会保留）。
页面显示 “Warning: You do not have permission to modify VibeFox DHL Packstation!”：您的管理员用户组可能只有查看设置的权限。请在 System > Users > User Groups 中为该组授予 extension/shipping/vfd_dhl_packstation（OpenCart 3）或 extension/vfd_dhl_packstation/shipping/vfd_dhl_packstation（OpenCart 4）的修改权限。
卸载
进入 Extensions > Extensions，选择类型 Shipping，然后点击 VibeFox DHL Packstation 旁边的 Uninstall（红色 − 按钮）。OpenCart 总会重置 Enable/Disable、Sort Order、Tax Class 和 Geo Zone。该扩展的许可证密钥和许可证状态总会被删除。取货点缓存和扩展的事件总会被删除。如果开启了 Remove data on uninstall，设置、日志以及未完成结账的取货点也会被删除。如果关闭，其他设置将保留，并在您重新安装扩展时再次使用。已选的取货点始终保留在订单中，现有订单保留其配送方式、费用和地址。
在 OpenCart 4 中，如需同时删除扩展的文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox DHL Packstation 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）删除已上传的安装包。
DHL 和 Packstation 是其各自所有者的商标。本扩展与 DHL 无关联，也未获得 DHL 的认可。