VibeFox DPD Pickup for OpenCart — 帮助
系统要求
OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP：8.0 或更高版本。
DPD Baltic 凭据（立陶宛、拉脱维亚、爱沙尼亚）：取货点列表来自 DPD Baltic 网络服务。您需要 DPD 发给其企业客户的 API 用户名和密码。请咨询您的 DPD 客户经理或您所在国家的 DPD 客服。一个 DPD Baltic 账户可列出立陶宛、拉脱维亚和爱沙尼亚的取货点。
DPD Slovakia：DPD Slovakia 的公开 parcelshop 查询无需凭据。
重量等级：商品重量会被换算为 kg。您的商店需要在 System > Localisation > Weight Classes 中设置一个单位为 kg 的重量等级（OpenCart 默认自带一个）。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
下载文件是一个 zip 压缩包，内含两个 OpenCart 版本的安装包。请先解压到您的电脑上。其中包含 README.txt、OpenCart 3 安装包 vfd_dpd_pickup-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 vfd_dpd_pickup.ocmod.zip。只安装与您的 OpenCart 版本对应的安装包。两个版本使用相同的许可证密钥。
OpenCart 3
1. 在后台进入 Extensions > Installer，点击 Upload，选择文件 vfd_dpd_pickup-oc3-(version).ocmod.zip。本扩展不添加任何 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用 Installer，而是将安装包中 upload 文件夹的内容复制到商店的根目录。
2. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox DPD Pickup，点击 Install（绿色 + 按钮）。
3. 点击 Edit（铅笔按钮）打开设置页面。
4. 在 Edit 页面顶部的许可证区块中，于 License key 处粘贴您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。
5. 选择您的 DPD API。若使用 DPD 立陶宛、拉脱维亚或爱沙尼亚，请输入 API 用户名和密码。检查各国价格，开启 Enable/Disable，然后点击 Save。之后点击 Refresh pickup points 检查连接（参见配置）。
OpenCart 4
1. 在后台进入 Extensions > Installer，点击 Upload，选择文件 vfd_dpd_pickup.ocmod.zip。请勿重命名该文件：OpenCart 4 根据文件名获取扩展代码，重命名后的安装包将无法使用。
2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。
3. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox DPD Pickup，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按 OpenCart 3 的步骤 4 和 5 输入许可证密钥和设置。两个版本的设置页面及其字段相同。
安装后，该方式保持关闭，直到您开启 Enable/Disable 并保存。如果您卸载后重新安装该扩展，将重新使用您保留的设置。
配置
所有设置都位于扩展页面：Extensions > Extensions > Shipping > VibeFox DPD Pickup > Edit。分区列在左侧。点击一个 Save 按钮即可保存整个页面，无需刷新。每次保存还会清除缓存的取货点列表。只有拥有该扩展修改权限的管理员用户才能保存设置、刷新取货点或清空日志。
页面顶部的警告会提示：DPD Baltic 用户名或密码为空，或未设置任何价格（在这两种情况下，结账时都不会显示该方式），以及商店没有单位为 kg 的重量等级（此时商品重量将按单位名称读取，未知单位按 kg 处理）。部分值会阻止保存，此时不会保存任何内容：Name 为空或超过 64 个字符、Sort order 不是整数，以及 Min weight (kg) 大于 Max weight (kg)。金额或重量字段中不是数字或为负数的值不会被保存：该字段会被清空并由警告指出，其他设置仍会保存。Country prices 中不符合 CC:PRICE 格式的行会在警告中列出并被忽略。
常规
该方式会在 Availability 中设置的地理区域内提供（未设置则为所有区域），或在 Ignore shipping zones 下、于此处选择的国家中提供。
Enable/Disable：在结账页面显示或隐藏 DPD Pickup。默认：关闭。
Name：顾客在结账时看到的配送方式名称。默认：DPD Pickup Point。必填，最多 64 个字符。
Tax class：应用于配送费用的税类，或选择 None（默认）表示不征税。
Sort order：该方式在配送方式列表中的位置。整数。
DPD 取货点列表
取货点从 DPD 加载并缓存（参见结账时的工作方式）。
DPD API：您的账户所属的 DPD 公司。Baltic 账户使用其所在国家的网络服务。
API username (Baltic)：您的 DPD Baltic 网络服务用户名。DPD Slovakia 不需要。清空该字段也会清除已保存的密码。
API password (Baltic)：您的 DPD Baltic 网络服务密码。DPD Slovakia 不需要。保存后该字段保持为空，并显示 Saved - leave empty to keep it. 只有需要更改时才输入新值。
Pickup points：点击 Refresh pickup points 会清除缓存，并立即从 DPD 加载取货点：Baltic API 为立陶宛、拉脱维亚和爱沙尼亚，DPD Slovakia 为布拉迪斯拉发的测试查询。它会按国家显示取货点数量或错误。请先保存设置。
价格
配送费用按国家固定，使用商店的默认货币，不含税。不会通过 API 向 DPD 查询价格。
Country prices：每个国家一行：CC:价格，例如 EE:3.50。也接受小数逗号。默认：SK:3.50, LT:4.00, LV:4.00, EE:4.00。
Fallback cost：未在 Country prices 中列出的国家所使用的价格。默认：5.00。留空则仅在列出的国家提供该方式。
Calculation type：Per order（默认）只收取一次价格。Per item (price x quantity) 则按购物车中的商品数量相乘。
Free shipping from：当订单小计（折扣后、税前）达到此金额时免运费。留空则关闭。
可用性
当 DPD 未返回顾客地址的取货点，或无法连接 DPD API 时，该方式也会被隐藏，因为没有取货点的订单无法配送。
Min weight (kg)：购物车的最小重量。商品重量根据其重量等级换算。留空或为 0 表示不限制。
Max weight (kg)：超过此重量的购物车不会看到该方式。默认：31.5。留空或为 0 表示不限制。请核实您所在国家 DPD Pickup 取货点和储物柜的包裹限制。
Minimum subtotal：仅当订单小计（折扣后、税前）至少为此金额时才显示该方式。留空则始终显示。
Geo zone：仅向该地理区域内的地址提供该方式。All zones（默认）表示不限制。地理区域在 System > Localisation > Geo Zones 中管理。与 Ignore shipping zones 不同时使用。
Ignore shipping zones：开启后，不检查地理区域，并在下方的国家中提供该方式。关闭（默认）时，仅使用上方的地理区域。
Countries：该模式下的目的地国家。留空表示所有国家。仅在 Ignore shipping zones 下使用。
取货点选择器
City order：优先显示主要城市（Tallinn、Riga、Vilnius、Bratislava 等）。默认开启。
City list width：城市列表的 CSS 宽度，例如 100% 或 300px。默认：100%。
Pickup point list width：取货点列表的 CSS 宽度，例如 100% 或 400px。默认：100%。
高级
Debug log：将 API 请求和结账步骤写入 storage/logs/vfd_dpd_debug.log.php（在 OpenCart 4 中为 system/storage/logs/vfd_dpd_debug.log.php）。该文件无法通过网页读取。即使此选项关闭，API 错误仍会始终记录。凭据从不写入日志。文件达到 5 MB 时，会移动到 vfd_dpd_debug.old.log.php，并开始新的日志。
Log：显示调试日志的大小和最新条目。点击 Clear log 可清空。
Remove data on uninstall：开启后，卸载扩展会删除其设置、日志以及未完成结账的选择。订单中保存的取货点始终保留。
导入 / 导出
Export：点击 Download JSON 可将设置保存为 JSON 文件。API 密码不会被导出。
Import：粘贴之前导出的 JSON，然后点击 Import 恢复设置，例如在另一家商店中。这些值会像正常保存一样进行检查。已保存的 API 密码将保留。
结账时的工作方式
OpenCart 显示配送方式时，会向扩展请求 DPD Pickup 的价格。如果设置了 Geo zone（且 Ignore shipping zones 已关闭），而地址不在该区域内，则不会提供该方式。只有 Requires Shipping 设为 Yes 的商品才会计入：其他商品不增加重量，也不计入小计。扩展会检查国家（配合 Ignore shipping zones）、购物车重量和最低小计，获取该国家的价格（或备用费用），并在小计足够高时应用免运费。小计是需要配送的商品价格，即扣除优惠券折扣后、税前的金额。
随后，扩展会加载该地址的 DPD 取货点。如果 DPD 未返回任何取货点、无法连接或缺少 Baltic 凭据，则隐藏该方式。对于 DPD Slovakia，在城市或邮政编码仍未填写时显示该方式，地址完整后即显示取货点。价格以默认货币计算，并以顾客的货币显示，同时包含所选 Tax class 的税款。
取货点列表最多缓存 24 小时，空列表最多缓存 1 小时，但不会超过 OpenCart 缓存有效期（默认 1 小时）。失败的请求会记住 5 分钟，因此 DPD 故障绝不会拖慢结账。API 超时时间为 15 秒。
本扩展不会向 DPD 查询价格、不会创建 DPD 运单、不会打印面单、不会生成交接清单、不会预约快递取件、不会追踪包裹，也不显示地图。仅支持 DPD Baltic 网络服务和 DPD Slovakia parcelshop 查询。
取货点
顾客选择 DPD Pickup 时，该方式下方会出现城市列表和取货点列表。顾客地址中的城市已预先选中。顾客一经选择，选择即会保存。使用 DPD Slovakia 时，在地址填写完整之前，顾客会看到 Enter your city and postcode to see the DPD pickup points nearby.，之后显示附近的取货点。如果 DPD 没有该地址的取货点，顾客会看到 No DPD pickup points are available for this address right now. Please check the address or choose another shipping method.
必须选择取货点。未选择则顾客无法继续，并会看到 Please select a DPD pickup point. 当顾客点击 Continue 时，服务器会检查该取货点是否属于顾客地址对应的 DPD 列表。伪造或过时的选择会被拒绝，并显示 The selected DPD pickup point is not available for this address. Please choose another one. 如果此时无法加载 DPD 列表，则接受顾客已选择的取货点，订单将显示其 ID 而非名称。
在 OpenCart 4 中，顾客在结账页面的配送方式区块中点击 Choose，并在 Shipping method options 窗口中选择 DPD Pickup。城市列表和取货点列表会在该窗口中显示在该方式下方，并按上文所述工作。窗口中的 Continue 按钮在未选择取货点时不会继续，并显示相同的提示。
所选取货点会添加到订单的配送方式中，例如使用默认标题时为 DPD Pickup Point: name, street, postcode city，使用您自己的标题时为 My title - DPD pickup point: name, street, postcode city（最多 128 个字符）。因此它会显示在后台订单、顾客的订单历史、订单邮件和发票中。订单中保存的名称来自 DPD，而不是来自浏览器。
在 OpenCart 4 中，配送方式的文本最多可包含 255 个字符。OpenCart 4 会为结账保留一个订单，并在顾客每次再次确认时更新该订单，订单中的取货点也会随之更新。
在后台订单页面（Sales > Orders），历史记录上方的 DPD pickup point 面板会显示取货点名称、ID 和国家。点击 Edit，选择城市和另一个取货点，然后点击 Save。该取货点会根据订单地址的 DPD 列表进行检查，面板会显示 Pickup point updated. 或 Pickup point not found for the order address. 订单的配送方式文本会随之更新，并在订单历史中添加一条备注（不会发送给顾客），记录旧取货点、新取货点和后台用户。更改取货点需要订单的修改权限，而不是扩展设置的访问权限。使用 DPD Slovakia 时，订单需要有配送城市和邮政编码，否则面板会显示 Add the shipping city and postcode to change the pickup point. 未选择取货点下的订单会显示 No pickup point was selected for this order.，并且调试日志中会有一条对应的错误。即使扩展已关闭，该面板和 Edit 仍可使用。
许可证密钥
本扩展需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox DPD Pickup 位于 Extensions > Extensions > Shipping > VibeFox DPD Pickup > Edit 页面的最上方，位于设置之上。将密钥粘贴到 License key 中并点击 Activate。之后该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入另一个密钥）和 Remove key（从本商店移除该密钥）。它们下方是 Product: opencart-shipping-dpd-pickup 一行，以及 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 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 DPD Pickup 配送方式，也不会计算费率。在同一浏览器中登录后台的管理员用户仍能在商店中看到该方式，并标记为 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试扩展。在 OpenCart 4 中，此预览不可用：商店看不到后台登录状态，因此没有有效密钥时，所有人都看不到该方式。打开一次 Edit 页面后，后台的 Dashboard 页面上会出现一条提醒。点击 × 将其关闭，可隐藏 7 天。现有订单不受影响。
许可证到期后，扩展会继续工作，但更新和支持需要续费。打开后台的 Dashboard 或 Edit 页面时会自动再次检查状态：输入密钥后的前 14 天每天检查一次，之后每周检查一次。无需 cron 任务。卸载扩展总会删除许可证密钥和许可证状态。
故障排除
DPD Pickup 未在结账时显示：请检查许可证是否有效，以及 Enable/Disable 是否已开启。检查 Geo zone（或 Ignore shipping zones 和 Countries）、重量和小计限制，以及该国家是否设置了价格（或备用费用）。查看扩展页面顶部的警告，并点击 Refresh pickup points。检查商品的 Requires Shipping 是否设为 Yes。
点击 Refresh pickup points 后出现错误：结果会按国家显示 DPD 错误。例如，"Login failed" 表示 DPD 拒绝了 Baltic 凭据，因此无法加载任何取货点。请与 DPD 核对 API 用户名和密码。
DPD Slovakia 不显示取货点：取货点会在顾客输入城市和邮政编码后显示。DPD 只列出该地址 50 公里范围内的取货点。
查找原因：开启 Debug log，重新加载结账页面，然后查看扩展页面上的 Log 字段。API 错误始终会被记录。API 用户名和密码绝不会写入日志。
更改后取货点看起来过时：在扩展页面点击 Save 或 Refresh pickup points。两者都会清除缓存的列表。
页面显示 "Warning: You do not have permission to modify VibeFox DPD Pickup!"：您的管理员用户组可能只能查看设置。请在 System > Users > User Groups 中为该用户组授予 extension/shipping/vfd_dpd_pickup（OpenCart 3）或 extension/vfd_dpd_pickup/shipping/vfd_dpd_pickup（OpenCart 4）的修改权限。
面向开发者：其他扩展可以通过 OpenCart 事件 vfd_dpd_pickup/sk_search_radius 修改 DPD Slovakia 的搜索半径。
卸载
进入 Extensions > Extensions，选择类型 Shipping，然后点击 VibeFox DPD Pickup 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态总会被删除。OpenCart 总会重置 Enable/Disable、Sort order、Tax class 和 Geo zone。扩展总会删除其事件和缓存的取货点列表。如果 Remove data on uninstall 已开启，其他设置、调试日志和未完成结账的选择也会被删除。如果已关闭，设置会被保留，并在您重新安装扩展时再次使用。订单中保存的取货点永远不会被删除，现有订单也会保留其配送方式和费用。
在 OpenCart 4 中，如需同时删除扩展的文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox DPD Pickup 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）删除已上传的安装包。
DPD 是其各自所有者的商标。本扩展与 DPD 无关联，也未获得 DPD 的认可。