VibeFox DHL Packstation for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。支持 Classic 和 Hummingbird 主题。
PHP：8.0 或更高版本。模块拒绝安装在更早的 PHP 版本上。
DHL API key：取件点列表来自免费的 DHL Location Finder API。请在 DHL 开发者门户（developer.dhl.com）注册，创建应用，添加“Location Finder - Unified” API，然后复制应用的 API 密钥。使用该 API 无需 DHL 商务合同。没有该密钥时，承运商会在结账时隐藏。请注意您 DHL 应用的请求限制：每次新的邮编或城市搜索都会计为一次 API 请求。
VibeFox license key：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或之后在模块列表中找到 VibeFox DHL Packstation，点击 Configure。
3. 将您的 VibeFox 许可证密钥输入到 Configure 页面顶部许可证区块中的 License key 字段，然后点击 Activate（参见许可证密钥）。
4. 粘贴 DHL API 密钥，点击 Save，然后点击 Test API key。选择取件点类型，并输入各国家的价格（参见配置）。
安装时，模块会创建 DHL Packstation 承运商，配送时间文本为 Delivery to a DHL Packstation or post office。该承运商已启用，分配给所有客户组，以及德国和奥地利的区域（默认价格表中的国家）。您可以在 Shipping > Carriers 中更改区域、客户组、配送时间、徽标和尺寸限制。请不要在那里设置价格：价格始终来自模块。
配置
所有设置都在模块页面：Modules > Module Manager > VibeFox DHL Packstation > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。如果某个字段有错误（无效或负数、Min weight (kg) 大于 Max weight (kg)、名称超过 64 个字符），则不会保存任何内容，错误会显示在顶部。每次保存都会清空取件点缓存。
设置上方的警告会提示：未找到承运商；模块无法识别店铺的重量单位（International > Localization，Local units）（此时重量按千克读取；请使用 kg、g、lb 或 oz）；DHL API 密钥为空；没有启用任何取件点类型；国家价格条目不是 CC:PRICE 格式（这些条目将被忽略）。
常规
承运商的客户组、区域和尺寸限制在 Shipping > Carriers 中设置。以下设置适用于所有区域。
Enable/Disable：开启或关闭承运商。这与 Shipping > Carriers 中的承运商状态是同一个开关。
Name：显示给顾客的承运商名称。默认：DHL Packstation。必填，最多 64 个字符。
Tax：承运商的税务规则，或 No tax。PrestaShop 会在下方价格之上加收此税。选择 No tax 时，价格为最终价格。
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 附近的取件点，并清空取件点缓存。请先保存设置。它会显示找到的取件点数量、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 米（DHL 最大值）的值将被调整为该限制。
Max results：每次搜索显示的取件点最大数量。默认：20。整数；DHL 最多允许 50，更大的值将减少为 50。
Shipping address：将所选取件点用作订单的配送地址。默认开启。地址第 1 行会变为例如“Packstation 105”（对于 Post Office 或 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 千克的包裹。0 表示不设限制。
Minimum subtotal：仅当购物车小计（需要配送的商品，折扣之后、税费之前）不低于此值时显示承运商。留空则始终显示。
Ignore shipping zones：开启后，承运商将关联到所有启用的区域（包括之后创建的区域），并提供给下方列出的国家；如果列表为空，则提供给所有国家。再次关闭时，承运商会恢复其之前拥有的区域。
Countries (ignore zones)：该模式的目的地国家。按住 Ctrl/Cmd 并点击可选择多个国家。仅在启用 Ignore shipping zones 时使用。
高级
Debug log：将 API 请求和结账步骤写入模块文件夹中的 logs/vfd_dhlp_debug.log.php。该文件无法通过网页打开。即使此项关闭，API 错误也始终会被记录。API 密钥、Postnummer 和顾客地址绝不会写入。
Log：显示调试日志的大小和最新条目。点击 Clear log 可清空。
Remove data on uninstall：开启时，卸载模块会删除设置、承运商、缓存的搜索和日志。所选取件点仍保留在订单中。关闭时，所有内容都会保留，以便重新安装。
结账时的工作方式
在配送步骤，PrestaShop 会向模块请求 DHL Packstation 的价格。只有实体商品才计入：虚拟商品不增加重量，也不计入小计。模块会检查是否已设置 API 密钥和至少一种取件点类型、允许的国家（需启用 Ignore shipping zones）、购物车重量和最低小计。然后，它取得目的地国家的价格（或其他国家的价格），并在小计足够高时应用免运费。价格以您店铺的默认货币计算，并以顾客购物车的货币显示。
如果承运商已有订单后您在 Shipping > Carriers 中对其进行了编辑，PrestaShop 会将其保存为新的承运商版本。模块会自动采用新版本。
模块不会创建 DHL 运单、打印面单或跟踪包裹。请使用 DHL 商务客户门户或面单工具：开启 Shipping address 后，订单中已包含 Packstation 地址和 Postnummer。模块不计算 DHL 实时运费，也不显示地图。不支持手动输入 Packstation 编号。
取件点
当顾客选择 DHL Packstation 时，承运商下方会出现一个选择器。系统会加载配送邮编和城市附近的 DHL 取件点。DHL 仅针对所选承运商进行查询。顾客可以输入其他邮编或城市，然后点击 Search。取件点按类型（Packstation、Post Office、Parcel Shop）分组，并按距离排序。如果没有找到任何结果，顾客会看到 No DHL locations found near "…". Try another postcode or city.
对于 Packstation，顾客必须输入 DHL Postnummer，即其在 DHL 应用或 DHL 账户中的 6–12 位 DHL 客户编号。对于其他取件点，该项为可选。选择一经做出，即会保存到购物车。点击 Continue 时，服务器会再次检查：取件点必须是配送国家中 DHL 搜索结果之一。如果没有取件点，顾客会看到 Please choose a DHL Packstation or post office for delivery. 并无法继续。缺失或无效的 Postnummer 也会以相同方式提示。
搜索结果会缓存 12 小时。空的或失败的搜索会缓存 10 分钟，因此结账时不会在每次刷新时都等待 DHL。API 超时时间为 12 秒。如果无法连接 DHL API，顾客会看到 DHL locations cannot be loaded right now. Please try again later or choose another shipping method. 顾客已选择的取件点仍会被接受。
下单时，取件点（ID、类型、编号、名称、地址）和 Postnummer 会与订单一同保存。如果开启了 Shipping address，订单的配送地址会被替换为取件点的地址。取件点会显示在订单确认页面、顾客账户中的 Order history and details，以及订单确认电子邮件和 Mail alerts 模块的新订单电子邮件中；承运商名称后会添加 DHL pickup location 和 DHL Postnummer 标签。
在后台的订单页面，DHL pickup location 区块会显示取件点、其类型和 ID，以及 Postnummer。点击 Change，按邮编或城市搜索，选择其他取件点，修改 Postnummer，然后点击 Save location。您也可以只修改 Postnummer。每次修改都会向订单添加一条私密消息：DHL pickup location changed to: …。如果开启了 Shipping address，订单的配送地址也会更新。修改取件点需要编辑订单的权限；无需访问模块页面的权限。如果同一个购物车生成了多个订单，取件点只属于第一个订单；该购物车的另一个订单上点击 Change 会显示 The DHL location of this cart belongs to another order of the same cart - nothing was changed.
许可证密钥
本模块需要来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox DHL Packstation 许可证区块位于 Modules > Module Manager > VibeFox DHL Packstation > Configure 页面中设置上方的第一个区块。在 License key 中输入密钥并点击 Activate。之后该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入另一个密钥）和 Remove key（从此店铺中移除该密钥）。其下方是 Product: presta-shipping-dhl-packstation 这一行，以及 Manage licenses and domains in your account 链接，该链接会打开您的 vibefox.net 账户。只有拥有本模块 Configure 权限的员工才能更改密钥。该区块的文字跟随后台语言显示（包含英文和俄文）。
如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或带有日期的 License expired on。店铺地址更改后，或在账户中释放域名名额后，请点击 Check now。如果无法连接许可证服务器，模块会继续按上一次已知的状态运行。
一个密钥只能用于一个域名：主店铺的域名，多店铺设置中也是如此。从店铺中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。
没有有效密钥时，DHL Packstation 承运商不会在结账时显示给顾客，也不会计算任何运费。PrestaShop 前台无法得知您已登录后台，因此该承运商对您也会隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 的 Alerts 选项卡中会出现提醒。现有订单不受影响。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。在您使用后台期间会自动重新检查状态：输入密钥后的前 14 天每天检查一次，之后每周检查一次。无需 cron 任务。卸载模块总会删除许可证密钥和许可证状态。Reset 模块不会删除数据，因此密钥和状态会保留。
故障排除
结账时没有显示 DHL Packstation：检查许可证是否有效，并且 Enable/Disable 已开启。在 Shipping > Carriers 中，检查承运商是否涵盖顾客所在国家的区域和顾客的客户组（或开启 Ignore shipping zones 并检查 Countries (ignore zones)）。检查 DHL API key 是否已填写，是否至少选中了一种取件点类型，目的地国家是否设置了价格（或已设置 Other countries），以及重量和小计规则是否没有将其隐藏。商品也可能在商品页面中被限定为特定承运商。
没有显示任何取件点：点击 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 Packstation 承运商：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块以重新创建。重置会保留现有承运商的开启/关闭状态。
卸载
进入 Modules > Module Manager，打开 VibeFox DHL Packstation 旁边的菜单，然后选择 Uninstall。许可证密钥、许可证状态和取件点缓存始终会被删除。如果开启了 Remove data on uninstall，承运商将被删除（订单保留其历史记录），并删除设置、日志以及没有订单的购物车中的取件点。如果关闭，承运商仅会被禁用，所有设置都会保留。重新安装模块会恢复承运商之前的状态。所选取件点始终保留在订单中。
DHL 和 Packstation 是其各自所有者的商标。本模块与 DHL 无关联，也未获得 DHL 的认可。