VibeFox DPD Pickup for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝在更早的 PHP 版本上安装。
DPD Baltic 凭据（立陶宛、拉脱维亚、爱沙尼亚）：取件点列表来自 DPD Baltic 网络服务。您需要 DPD 发放给其企业客户的 API 用户名和密码。请向您的 DPD 客户经理或您所在国家的 DPD 客服咨询。一个账户可列出立陶宛、拉脱维亚和爱沙尼亚的取件点。
DPD 斯洛伐克：DPD 斯洛伐克公开的 parcelshop 查询无需凭据。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者之后在模块列表中找到 VibeFox DPD Pickup 并点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，于 License key 字段输入您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。
4. 选择您的 DPD API。若使用 DPD 立陶宛、拉脱维亚或爱沙尼亚，请输入 API 用户名和密码。检查各国家的价格，然后点击 Save。接着点击 Refresh pickup points 检查连接（参见配置）。
安装时，模块会创建承运商 DPD Pickup Point，配送时间文本为 DPD Pickup point or locker。该承运商分配给斯洛伐克、立陶宛、拉脱维亚和爱沙尼亚的配送区域以及所有顾客组，不设税务规则。您可以在 Shipping > Carriers 中修改配送区域、顾客组、配送时间文本、徽标和尺寸限制。请不要在那里设置价格：价格始终来自模块。
配置
所有设置都在模块页面中：Modules > Module Manager > VibeFox DPD Pickup > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。每次保存还会清除缓存的取件点列表。
页面顶部的警告会提示：DPD Baltic 用户名或密码为空、未设置任何价格（这两种情况下结账时都不会显示该承运商）、承运商已被删除，以及模块无法识别商店的重量单位（International > Localization，Local units），此时商品重量将按千克读取。金额或重量字段中不是数字或为负数的值不会被保存：该字段会被清空，并且警告会指出该字段。Country prices 中不符合 CC:PRICE 格式的行会列在警告中并被忽略。
常规
Enable/Disable：开启或关闭 DPD Pickup。这与 Shipping > Carriers 中的承运商状态是同一个开关。
Name：结账时显示给顾客的承运商名称。默认：DPD Pickup Point。必填，最多 64 个字符。
Tax status：应用于配送价格的承运商税务规则。None 表示不征税。其他选项会显示 Taxable 以及您商店中某个税务规则的名称。
DPD 取件点列表
取件点从 DPD 加载，并缓存 24 小时。
DPD API：您的账户所属的 DPD 公司。波罗的海账户使用其所在国家的网络服务。
API username (Baltic)：您的 DPD Baltic 网络服务用户名。DPD 斯洛伐克不需要。清空该字段也会清除已保存的密码。
API password (Baltic)：您的 DPD Baltic 网络服务密码。DPD 斯洛伐克不需要。保存后该字段保持为空，并显示 Saved - leave empty to keep it. 只有在要更改时才输入新值。
Pickup points：Refresh pickup points 按钮会清除缓存，并立即从 DPD 加载取件点：Baltic API 加载立陶宛、拉脱维亚和爱沙尼亚的取件点，DPD 斯洛伐克则在布拉迪斯拉发进行一次测试查询。它会按国家显示取件点数量或错误信息。请先保存设置。
价格
配送价格按国家固定，以商店的默认货币计算，不含税。不会向 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 取件点和快递柜的包裹限制。Min weight (kg) 大于 Max weight (kg) 会被拒绝，且不会保存任何内容。
Minimum subtotal：只有当订单小计（折扣后、税前）至少达到此金额时才显示该承运商。留空则始终显示。
Ignore shipping zones：开启时，该承运商会关联到所有配送区域，并对下方列出的国家提供。之后创建的区域会立即关联。关闭时，该承运商只在 Shipping > Carriers 中为其设置的区域提供。关闭该选项会使承运商恢复为之前拥有的区域。
Countries：此模式下的目的地国家。留空表示所有国家。仅在开启 Ignore shipping zones 时使用。
取件点选择器
City order：优先显示主要城市（塔林、里加、维尔纽斯、布拉迪斯拉发等）。默认开启。
City list width：城市列表的 CSS 宽度，例如 100% 或 300px。默认：100%。
Pickup point list width：取件点列表的 CSS 宽度，例如 100% 或 400px。默认：100%。
高级
Debug log：将 API 请求和结账步骤写入模块文件夹中的 logs/vfd_dpd_debug.log.php。该文件无法通过网页打开。即使此选项关闭，API 错误也始终会记录。凭据永远不会被记录。
Log：显示调试日志的大小和最新条目。点击 Clear log 可将其清空。
Remove data on uninstall：开启时，卸载模块会删除模块设置和承运商。订单中保存的取件点始终保留。
结账时的工作方式
在配送步骤，PrestaShop 会向模块请求 DPD Pickup 的价格。只有实体商品才会计算：虚拟商品不增加重量，也不计入小计。模块会检查国家（配合 Ignore shipping zones）、购物车重量和最低小计，取该国家的价格（或备用费用），并在小计足够高时应用免运费。然后它会加载该地址的 DPD 取件点。如果 DPD 未返回任何取件点、无法连接，或缺少 Baltic 凭据，该承运商会被隐藏。价格以商店的默认货币计算，然后以顾客的购物车货币显示。
取件点列表缓存 24 小时，空列表缓存 1 小时。失败的请求会被记住 5 分钟，因此 DPD 故障永远不会拖慢结账。API 超时时间为 15 秒。
如果您在订单已产生后，在 Shipping > Carriers 中编辑该承运商，PrestaShop 会将其保存为新的承运商版本。模块会自动跟随新版本。
模块不会请求 DPD 价格，不会创建 DPD 运单，不打印面单，不生成交接清单，不预约快递上门取件，不跟踪包裹，也不显示地图。仅支持 DPD Baltic 网络服务和 DPD 斯洛伐克 parcelshop 查询。
取件点
当顾客选择 DPD Pickup 时，承运商下方会出现城市列表和取件点列表。顾客地址所在城市会被预先选中。顾客一做出选择，该选择就会保存到购物车中。使用 DPD 斯洛伐克时，在地址填写完整之前，顾客会看到 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. 服务器会检查该取件点是否属于顾客地址对应的 DPD 列表。伪造或过时的选择会被拒绝，并显示 The selected DPD pickup point is not available for this address. Please choose another one.
所选取件点会保存在订单中。它会显示在订单确认页面和顾客的订单详情中，标注为 DPD pickup point:。在订单确认电子邮件中，它会添加在承运商名称之后。发送给商店的新订单电子邮件（ps_emailalerts）也会显示取件点 ID。订单中保存的名称来自 DPD，而不是来自浏览器。
在后台的订单页面中，DPD pickup point 区块会显示取件点名称、ID 和国家。点击 Edit，选择城市和另一个取件点，然后点击 Save。系统会按订单地址对应的 DPD 列表检查该取件点，页面会显示 Pickup point updated. 或 Pickup point not found for the order address. 更改取件点需要编辑订单的权限，而不是访问 Modules 页面的权限。每次更改都会记录在订单的 Advanced Parameters > Logs 中，包括旧取件点、新取件点和操作员。使用 DPD 斯洛伐克更改取件点时，订单必须有配送城市和邮政编码。
如果一个购物车被拆分为多个订单，取件点会保留在第一个订单中。其他订单会显示 No pickup point was selected for this order.，调试日志中会为每个订单记录一条错误，并且其中的 Edit 会显示 The pickup point of this cart belongs to another order of the same cart. Nothing was changed. 这类订单的取件点需要您手动提交给 DPD。
许可证密钥
本模块需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox DPD Pickup 是 Modules > Module Manager > VibeFox DPD Pickup > Configure 中的第一个区块，位于设置上方。请将密钥输入 License key，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从此商店移除密钥）。其下方有一行 Product: presta-shipping-dpd-pickup，以及打开您 vibefox.net 账户的链接 Manage licenses and domains in your account。只有拥有本模块 Configure 权限的员工才能更改密钥。该区块的文字跟随后台语言显示（包括英语和俄语）。
如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或带有日期的 License expired on。商店地址变更后，或在您的账户中释放了域名名额后，请点击 Check now。如果无法连接许可证服务器，模块将按照最后已知的状态继续运行。
一个密钥只能用于一个域名：主商店的域名，多店铺配置下同样如此。从商店中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效的密钥时，DPD Pickup 承运商不会在结账时显示给顾客，也不会计算运费。PrestaShop 前台无法得知您已登录后台，因此该承运商对您也是隐藏的：您可以在购买密钥之前设置模块，但无法在结账时进行测试。Modules > Module Manager 的 Alerts 选项卡中会出现提醒。现有订单不受影响。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。您在后台工作时，状态会自动重新检查：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时没有显示 DPD Pickup：检查许可证是否有效，并且 Enable/Disable 已开启。在 Shipping > Carriers 中，检查该承运商是否覆盖顾客所在国家的配送区域以及顾客组（或 Ignore shipping zones 已开启且该国家被允许）。查看模块页面顶部的警告，并点击 Refresh pickup points。检查重量和小计限制，以及该国家是否有价格（或备用费用）。商品还可能在商品页面中被限制只能使用特定承运商。
点击 Refresh pickup points 后出现错误：结果会按国家显示 DPD 错误。例如，"Login failed" 表示 DPD 拒绝了 Baltic 凭据，因此无法加载任何取件点。请向 DPD 核对 API 用户名和密码。
DPD 斯洛伐克没有显示取件点：顾客输入城市和邮政编码后，取件点才会出现。DPD 只列出该地址 50 公里以内的取件点。开发人员可以通过模块钩子 actionVfdDpdSkSearchRadius 更改半径。
查找原因：开启 Debug log，重新加载结账页面，然后查看模块页面上的 Log 字段。每个判断都会记录在那里。API 错误始终会记录。API 用户名和密码永远不会写入日志。
更改后取件点看起来过时：在模块页面点击 Save 或 Refresh pickup points。两者都会清除缓存的列表。
页面提示找不到 DPD Pickup 承运商：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块以重新创建。
卸载
进入 Modules > Module Manager，打开 VibeFox DPD Pickup 旁边的菜单，然后选择 Uninstall。许可证密钥、许可证状态和取件点缓存始终会被删除。如果 Remove data on uninstall 已开启，承运商会被删除（订单保留其历史记录），并且设置、日志以及未完成购物车的选择都会被删除。如果已关闭，承运商只会被停用，所有设置都会保留。重新安装模块或执行 Reset 会使已保存的承运商恢复其之前的状态：您之前停用的承运商会保持停用。订单中保存的取件点永远不会被删除。
DPD 是其各自所有者的商标。本模块与 DPD 无关联，也未获得 DPD 的认可。