VibeFox PostNL for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x，Classic 或 Hummingbird 主题（或基于它们的主题）。
PHP：8.0 或更高版本。模块拒绝在较旧的 PHP 版本上安装。
PostNL API 密钥（仅用于自提点）：自提点从 PostNL Checkout API 加载。PostNL 企业客户可在 Mijn PostNL 中的 My account > API beheren 下找到 API 密钥。PostNL 沙盒需要单独的沙盒密钥。送货上门承运商不需要密钥。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure，或之后在模块列表中找到 VibeFox PostNL 并点击 Configure。
3. 在 Configure 页面顶部的许可证区块中的 License key 字段输入您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。
4. 填写价格。对于自提点，还需输入 PostNL 的 API key 和 Ship from (postcode)（参见配置）。点击 Save。
安装时，模块会创建两个承运商：PostNL pickup point（配送时间文字为 Delivery to a PostNL pickup point）和 PostNL（PostNL delivery to the home address）。两者都关联荷兰和比利时的区域以及所有客户组。您可以在 Shipping > Carriers 中添加区域，并更改客户组、配送时间、Logo 和尺寸限制。请不要在那里设置价格：价格始终来自模块。
配置
所有设置都在模块页面：Modules > Module Manager > VibeFox PostNL > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。在 WooCommerce 中，一个方式要为每种配送类型各添加一次到区域中。在 PrestaShop 中，每种配送类型都是独立的承运商，拥有自己的名称、状态和区域。
在设置上方，页面会显示警告：自提点缺少 API 密钥或发货邮编、已开启沙盒、未设置任何价格、最近一次失败的 PostNL 请求（含日期和错误）、模块无法识别的商店重量单位，以及已删除的承运商。
通用
PostNL pickup point：开启或关闭自提点承运商。顾客必须在结账时选择一个 PostNL 网点。仅对荷兰和比利时地址提供，且仅在有 API 密钥时提供。这与 Shipping > Carriers 中的承运商状态是同一个开关。
Pickup point carrier name：顾客在结账时看到的名称。默认：PostNL pickup point。必填。
PostNL home address：开启或关闭送货上门承运商。不选择网点。对于设置了价格的每个国家都有效。与承运商状态是同一个开关。
Home delivery carrier name：顾客在结账时看到的名称。默认：PostNL。必填。
Tax status：两个承运商的税务规则。Taxable 规则会在价格之上加上该规则的运费税。None 表示价格为最终价格。
PostNL API（自提点）（送货上门不需要）
API key：您在 Mijn PostNL（My account > API beheren）中获得的 PostNL API 密钥。它以 "apikey" 请求头发送给 PostNL，从不显示给顾客，也不写入日志。保存后，该字段保持为空，并显示 Saved - leave empty to keep it. 只有在要更改时才输入新值。
Remove the saved API key：勾选后点击 Save，即可删除已保存的密钥。之后将不再提供自提点承运商。
Sandbox：使用 PostNL 沙盒（api-sandbox.postnl.nl）和沙盒 API 密钥。此时顾客会看到测试网点。正式店铺请保持关闭。
Ship from (country)：您将包裹交给 PostNL 的国家：Netherlands 或 Belgium。默认：Netherlands。PostNL 使用发件人地址确定取件日期。
Ship from (postcode)：发件人邮编，例如荷兰的 1234AB 或比利时的 1000。如果店铺位于同一国家，可留空以使用 Shop Parameters > Contact > Stores 中的店铺邮编。无效邮编会以空值保存并给出警告。更改 API 密钥、沙盒设置或发货地址时，已缓存的自提点列表和最近一次 API 错误会被清除。
价格（以商店默认货币计，不含税）
价格适用于两个承运商。PostNL 没有公开的运费 API，因此本模块不请求实时运费。对于使用其他货币付款的顾客，PrestaShop 会按您商店的汇率换算价格。
Price per country：每个目的国家一行。点击 + Add country 添加一行，点击垃圾桶图标删除。选择 * All other countries 可设置一行覆盖所有没有单独一行的国家。每行都有一个 Price，以及按购物车重量划分的可选重量等级：XS 最高 1 kg，S 最高 2 kg，M 最高 3 kg，L 最高 5 kg，XL 超过 5 kg。重量等级价格会覆盖 Price；留空则使用 Price。Price 为 0 表示免运费。可接受 "6.95"、"6,95"，以及带千位分隔符的金额，如 "1.234,50" 或 "1,234.50"。保存时会删除空行和无效的国家代码。如果某个国家出现两次，保留第一行。无效价格会被忽略并给出警告。
Calculation：Per order 只收取一次价格。Per item (price x quantity) 则按需要配送的商品数量相乘。
Price for other countries：当表格中既没有该国家也没有 * 行时使用。留空则在这些国家隐藏承运商。
条件
Free shipping from：免运费起点的购物车小计（需要配送的商品，不含税，折扣后）。仅适用于找到价格的地区。留空则从不提供免运费。
Minimum subtotal：仅当购物车小计至少达到此金额时才显示承运商。留空则始终显示。
Minimum weight (kg)：购物车重量低于此值时隐藏承运商。商品重量会从商店的重量单位换算。留空表示无限制。
Maximum weight (kg)：对于更重的购物车隐藏承运商。默认：30（PostNL 包裹在 Benelux 最重可达 30 kg）。0 表示无限制。如果留空，承运商区域内适用 30 kg，而无限制仅适用于通过 Ignore zones 覆盖的国家。最低重量大于最高重量会被拒绝并给出错误，因为承运商将永远不会显示。
所有金额和重量都接受小数逗号，也可带千位分隔符。无效或负数会被忽略并给出警告，该字段将以空值保存。
无配送区域时的可用性
通常，承运商会在 Shipping > Carriers 中与其关联的配送区域内提供。
Ignore zones：也在下方国家提供 PostNL，即使其区域不包含这些国家。此时承运商会关联到每个启用的区域，包括您以后创建的区域。再次关闭时，承运商会恢复到之前的区域。
Countries：该模式的目的国家。留空则允许所有国家。仅当 Ignore zones 开启时才使用此字段。在这些国家可以提供两个承运商；但自提点承运商仍只适用于荷兰和比利时。
高级
Debug log：将调试信息写入模块文件夹中的 logs/vfd_ptnl_debug.log.php。该文件无法通过网页打开。API 错误始终会记录。不会写入 API 密钥或顾客数据。完成后请关闭日志。
Log：显示日志的大小和最新条目。点击 Clear log 可清空。
Remove data on uninstall：开启时，卸载模块会删除 PostNL 设置和承运商。关闭时，卸载只会关闭承运商。订单上保存的自提点始终会保留。
结账时的工作方式
在配送步骤，PrestaShop 会向模块请求每个 PostNL 承运商的价格。只计算实体商品：虚拟商品不增加重量，也不计入小计。模块检查条件：购物车重量和最低小计。然后从表格中获取该国家和重量等级的价格，或其他国家的价格。如果没有价格，承运商会被隐藏。如果购物车小计达到 Free shipping from，价格为 0。
自提点承运商仅对荷兰和比利时地址提供，且仅在有 API 密钥时提供。当配送地址有有效邮编时，模块会向 PostNL Checkout API 请求最近的三个自提点。它会发送顾客的邮编、街道、门牌号、城市和国家，以及您的发货地址。送货上门承运商不会发送任何内容。如果无法连接 PostNL，或该地址没有网点，则隐藏自提点承运商，送货上门承运商仍然可用。API 超时时间为 12 秒。
网点列表按邮编缓存 6 小时，"无网点" 的回复缓存 1 小时。失败的请求缓存 10 分钟，以免故障使每次结账刷新都变慢。最近一次错误显示在模块页面。
如果您在 Shipping > Carriers 中编辑已有订单的承运商，PrestaShop 会将其保存为新的承运商版本。模块会自动跟随新版本。
模块不请求 PostNL 实时运费，也不生成运单标签、条形码、track and trace、退货或预报。它没有送货日期、晚间或早间送货选项。请使用保存的自提点，在 Mijn PostNL 或其他 PostNL 工具中创建发货单。
自提点
当顾客选择自提点承运商时，其下方会出现 PostNL pickup point 列表，显示最近的三个网点：公司名称、地址和距离。页面从不等待 PostNL：如果列表尚未缓存，则会在选择承运商后立即加载。在输入完整邮编之前，顾客会看到 "请输入您的邮编（例如 1234 AB），以查看 PostNL 自提点。"（比利时为 4 位数字）。所选网点会保存到购物车中，并在结账刷新时保留。
自提点为必选项。如果没有选择，顾客无法继续，并会看到 "请选择 PostNL 自提点。"。顾客点击 Continue 时，服务器会将该网点与 PostNL 针对配送地址的列表进行核对。如果不在列表中，顾客会看到 "所选 PostNL 自提点不适用于此地址。请重新选择。"。如果无法连接 PostNL，顾客会看到 "目前无法加载 PostNL 自提点。请几分钟后重试，或选择其他配送方式。"。为其他地址选择的网点永远不会用于订单。随订单保存的名称和地址来自 PostNL，而不是浏览器。
后台订单页面：一个 PostNL pickup point 区块，包含名称和地址、Location code 和 Partner ID。
订单确认页和订单详情页：PostNL pickup point，包含名称和地址。
订单邮件：网点名称和地址会添加到订单确认邮件中的承运商名称后面。商店的新订单邮件（Mail alerts 模块）还会显示位置代码。
许可证密钥
本模块需要使用从 vibefox.net 获取的 VibeFox 许可证密钥。该模块的许可证区块 License — VibeFox PostNL 是 Modules > Module Manager > VibeFox PostNL > Configure 页面中位于设置上方的第一个区块。请将密钥输入 License key 并点击 Activate。之后，该区块会显示被遮蔽的密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从此店铺移除密钥）。其下方是 Product: presta-shipping-postnl 一行和 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 账户中释放该名额。
没有有效的密钥时，结账时不会向顾客显示 PostNL 承运商，也不会计算运费。PrestaShop 前台无法得知您已登录后台，因此承运商对您也会隐藏：您可以在购买密钥前设置模块，但无法在结账时测试。Modules > Module Manager 中的 Alerts 标签页会显示提醒。已有订单不受影响。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。在后台工作时，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载模块时，始终会删除许可证密钥和许可证状态。Reset 本模块不会删除数据，因此密钥和状态会被保留。
故障排除
结账时没有 PostNL：请检查许可证是否有效，以及承运商开关是否已开启。在 Shipping > Carriers 中，检查该承运商是否覆盖顾客所在国家的区域和顾客的客户组（或 Ignore zones 已开启且允许该国家）。检查该国家是否设置了价格、重量限制和 Minimum subtotal。商品也可能在商品页面中被限制为某些承运商。
自提点承运商没有出现：它仅对荷兰和比利时地址显示，且仅在有 API 密钥、发货邮编和价格，并且 PostNL 为顾客邮编返回网点时才显示。请检查模块页面顶部的警告和 Log 字段。错误始终会记录；如需详细信息，请开启 Debug log。
"PostNL pickup points cannot be loaded right now"：无法连接 PostNL、PostNL 拒绝了 API 密钥，或缺少发货邮编。模块页面会显示最近一次错误。沙盒密钥仅在 Sandbox 开启时有效，正式密钥仅在关闭时有效。
客户看到测试自提点：关闭 Sandbox。
商品重量看起来不对：如果模块页面提示商店重量单位未知，请在 International > Localization 的 Local units 下设置标准单位（kg、g、lb 或 oz）。在此之前，商品重量会按 kg 读取。
页面提示未找到 PostNL 承运商：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块以重新创建。重置会保留您的设置和承运商状态。
卸载
进入 Modules > Module Manager，打开 VibeFox PostNL 旁边的菜单，选择 Uninstall。许可证密钥和许可证状态总会被删除。缓存的自提点列表和最近一次 API 错误始终会被删除。如果 Remove data on uninstall 已开启，承运商会被删除（订单保留其历史记录），设置和日志也会被删除。如果已关闭，承运商仅会被关闭，所有设置都会保留。重新安装模块会让承运商恢复之前的状态。现有订单保留其配送行和已保存的自提点。
PostNL 是其各自所有者的商标。本模块与 PostNL 无关联，也未获得 PostNL 的认可。