VibeFox PostNL for WooCommerce — 帮助
系统要求
WordPress：5.8 或更高版本。
WooCommerce：7.0 或更高版本，已安装并启用。未安装时插件无法激活。
PHP：8.0 或更高版本。
PostNL API 密钥（仅用于自提点）：自提点从 PostNL Checkout API 加载。PostNL 企业客户可在 Mijn PostNL 的 My account > API beheren 中找到 API 密钥。PostNL 沙盒需要单独的沙盒密钥。送货上门方式不需要密钥。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 vfd_postnl 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Shipping > VibeFox PostNL，或在插件页面点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 填写价格。对于自提点，还需填写 PostNL 的 API key 和 Ship from (postcode)（见配置）。
6. 在 WooCommerce > Settings > Shipping > Shipping zones 中，将 VibeFox PostNL 添加到配送区域，例如荷兰和比利时。在该区域中设置 Title 和 Delivery to。再次添加该方式，用于另一种配送类型。
配置
除标题和配送类型外，所有设置都在同一页面：WooCommerce > Settings > Shipping > VibeFox PostNL。这些设置适用于所有配送区域。将该方式添加到区域时，区域窗口中有两个字段：
Title (zone)：顾客在此区域方式下看到的名称。留空则使用全局 Name。
Delivery to (zone)：As in the global settings（默认）、PostNL pickup point (customer chooses a point) 或 Home address。在一个区域中添加两次该方式，即可同时提供两者。
设置上方页面会显示警告：自提点缺少 API 密钥或发货邮编、沙盒已开启、未设置价格，以及最近一次失败的 PostNL 请求（含日期和错误）。
常规
Enable/Disable：一次性在所有区域中启用或禁用 PostNL 配送。
Name：结账时显示的配送方式名称。区域中设置的 Title 会覆盖它。默认：PostNL。
Delivery to：用于使用 As in the global settings 的区域方式以及 Ignore zones 模式的默认配送类型。
Tax status：Taxable 会将 WooCommerce 税费加到运费上，None 则不加。
PostNL API（自提点）（送货上门不需要）
API key：您在 Mijn PostNL（My account > API beheren）中获取的 PostNL API 密钥。它以 "apikey" 请求头发送给 PostNL，存储在 WordPress 数据库中，从不显示给顾客，也不写入日志。
Sandbox：使用 PostNL 沙盒（api-sandbox.postnl.nl）和沙盒 API 密钥。此时顾客看到的是测试自提点。正式店铺请保持关闭。
Ship from (country)：您将包裹交给 PostNL 的国家：荷兰或比利时。默认为您店铺所在国家。PostNL 使用发件人地址确定取件日期。
Ship from (postcode)：发件人邮编，例如荷兰的 1234AB 或比利时的 1000。如果店铺与发件地在同一国家，可留空以使用 WooCommerce > Settings > General 中的店铺邮编。无效邮编会被拒绝并显示提示。更改 API 密钥、沙盒设置或发货地址时，缓存的自提点列表会被清除。
价格（以店铺货币计）
PostNL 没有公开的运费 API，因此本插件不请求实时运费，也从不转换价格。
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" 均可接受。保存时会删除空行和无效国家代码。如果某个国家出现两次，保留第一行。无效价格会被忽略并显示提示。
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）。留空表示无限制。
Hide for shipping classes：购物车中包含这些 WooCommerce 配送类别中任意类别的商品时，隐藏该方式。
所有金额和重量都接受小数逗号，也可带千位分隔符（1.234,50 或 1,234.50）。无效数字会被忽略并显示提示。
无配送区域时的可用性
Ignore zones：当没有任何区域添加 PostNL 时，也向以下国家提供 PostNL。包含该方式的区域仍照常工作。此模式使用全局 Name 和 Delivery to。
Countries：此模式的目的地国家。留空则使用店铺配送的所有国家。此字段仅在 Ignore zones 开启时使用。
高级
Debug log：将调试信息写入 WooCommerce > Status > Logs（来源为 "vfd-postnl"）。API 错误始终会被记录。不会写入 API 密钥或顾客数据。完成后请关闭日志。
Remove data on uninstall：开启后，删除插件会移除 PostNL 设置和区域方式。停用插件从不删除设置。订单中保存的自提点始终保留。
结账时的工作方式
顾客输入配送地址时，WooCommerce 会向插件请求运费。插件检查条件：购物车重量、最低小计和配送类别。然后，它从表格中获取该国家和重量等级对应的价格，或其他国家的价格。如果没有价格，该方式会被隐藏。如果购物车小计达到 Free shipping from，价格为 0。
自提点方式仅对荷兰和比利时地址提供，且仅在有 API 密钥时提供。顾客输入有效邮编后，插件会向 PostNL Checkout API 请求最近的自提点。它会发送顾客的邮编、街道、门牌号、城市和国家，以及您的发货地址。送货上门方式不会发送任何内容。如果无法连接 PostNL，或该地址没有自提点，自提点方式会被隐藏，您的其他方式仍可使用。API 超时时间为 12 秒。
自提点列表按邮编缓存 6 小时，"无自提点" 的响应缓存 1 小时。失败的请求缓存 10 分钟，以免服务中断导致每次结账刷新都变慢。最后一次错误显示在设置页面。
该方式适用于经典结账以及购物车和结账区块。兼容 WooCommerce 高性能订单存储（HPOS）。
本插件不请求 PostNL 实时运费，也不生成运单标签、条形码、track and trace、退货或预先通知。没有送货日期、晚间或早晨送货选项。请使用已保存的自提点，在 Mijn PostNL 或其他 PostNL 工具中创建发货单。
自提点
顾客选择自提点方式后，其下方会显示 PostNL pickup point 列表，包括最近的三个自提点：公司名称、地址和距离。在输入邮编之前，顾客会看到提示 "请输入您的邮编（例如 1234 AB）以查看 PostNL 自提点。"（比利时为 4 位数字）。结账刷新时，所选自提点会被保留。
必须选择自提点。未选择时，结账会停止并显示 "请选择 PostNL 自提点。" 服务器会将自提点与 PostNL 针对配送地址的列表进行核对。如果不在列表中，结账会停止并显示 "所选 PostNL 自提点在该地址不可用。请重新选择。" 随订单保存的名称和地址来自 PostNL，而不是浏览器。
管理后台订单页面：PostNL pickup point，显示名称、地址和 Location code，位于配送地址下方。
感谢页面和「我的账户」订单视图：PostNL pickup point，显示名称和地址。
订单邮件：HTML 和纯文本邮件中的自提点名称和地址。
在数据库中，自提点保存在订单元数据 _vfd_ptnl_servicepoint_id（PostNL 位置代码）、_vfd_ptnl_servicepoint_name（名称和地址）以及 _vfd_ptnl_servicepoint（合作伙伴 ID、公司、街道、门牌号、邮编、城市、国家）中。
许可证密钥
本插件需要使用 vibefox.net 提供的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Shipping > VibeFox PostNL 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期截止日期和您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 从本站点移除密钥。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。
没有有效密钥时，结账时不会向顾客显示 PostNL。已登录的店铺管理员仍能看到它，并标有 (unlicensed — visible to admins only)，这样您可以在购买密钥前设置和测试插件。插件页面和 WooCommerce 页面会显示提醒。现有订单不受影响。
许可证到期后，插件仍会继续工作，但更新和支持需要续费。状态会在后台自动重新检查。
故障排除
结账时没有显示 PostNL：请检查许可证是否有效、Enable/Disable 是否开启、该方式是否已添加到顾客所在国家的区域中（或 Ignore zones 已开启且该国家被允许）。检查该国家是否设置了价格、重量限制、Minimum subtotal 和 Hide for shipping classes。
自提点方式未显示：它仅对荷兰和比利时地址显示，且需要 API 密钥、发货邮编和价格，并且仅当 PostNL 为顾客邮编返回自提点时才显示。请检查设置页面顶部的警告，以及 WooCommerce > Status > Logs（来源 "vfd-postnl"）。错误始终会被记录；如需详细信息，请开启 Debug log。
"目前无法加载 PostNL 自提点"：无法连接 PostNL、PostNL 拒绝了 API 密钥，或缺少发货邮编。设置页面会显示最近一次错误。沙盒密钥仅在 Sandbox 开启时有效，正式密钥仅在其关闭时有效。
顾客看到的是测试自提点：请关闭 Sandbox。
开发者过滤器：vfd_ptnl_number_of_locations（默认 3）、vfd_ptnl_checkout_request（请求正文）和 vfd_ptnl_api_url。
许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在其他域名上使用，请在您的 vibefox.net 账户中释放名额，然后点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活密钥。如果无法连接许可证服务器，插件会继续使用最后已知的状态运行。
卸载
停用插件会保留所有设置，只清除缓存的自提点列表。要删除插件，请先停用，然后在 Plugins 页面删除。本插件的许可证密钥和许可证状态始终会被移除，同时移除缓存的自提点列表和最后一次 API 错误。只有在 Remove data on uninstall 开启时，设置和区域方式才会被删除。否则，它们会保留，以便日后重新安装时使用。现有订单会保留其配送行和已保存的自提点。
PostNL 是其各自所有者的商标。本插件与 PostNL 无关联，也未获得 PostNL 的认可。