VibeFox PostNL for OpenCart — 帮助
系统要求
OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP：8.0 或更高版本。
PostNL API 密钥（仅用于取件点）：取件点从 PostNL Checkout API 加载。PostNL 企业客户可在 Mijn PostNL 的 My account > API beheren 下找到 API 密钥。PostNL 沙盒需要单独的沙盒密钥。上门配送选项不需要密钥。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能在一个域名上使用。
安装
下载文件是一个 zip 文件，内含两个 OpenCart 版本的安装包。请在您的电脑上解压。其中包含 README.txt、OpenCart 3 安装包 vfd_postnl-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 vfd_postnl.ocmod.zip。请只安装与您的 OpenCart 版本对应的安装包。两个版本的许可证密钥相同。
OpenCart 3
1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_postnl-oc3-(version).ocmod.zip。本扩展不添加 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用 Installer，而是将安装包中 upload 文件夹的内容复制到店铺的根目录。
2. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox PostNL，点击 Install（绿色 + 按钮）。
3. 点击 Edit（铅笔按钮）打开设置页面。
4. 在 Edit 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥粘贴到 License key，然后点击 Activate（参见许可证密钥）。
5. 开启 PostNL pickup point 和/或 PostNL home address，并填写价格。对于取件点，还需输入 PostNL API key 和 Ship from (postcode)（参见配置）。点击 Save。
OpenCart 4
1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_postnl.ocmod.zip。请不要重命名该文件：OpenCart 4 会从文件名获取扩展代码，重命名后的安装包无法使用。
2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色的 + 按钮）。
3. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox PostNL，点击 Install（绿色的 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按照 OpenCart 3 步骤 4 和 5 的方式输入许可证密钥和设置。两个版本的设置页面及其字段相同。
安装后，两个选项都处于关闭状态，直到您开启其中一个并保存。如果您卸载后重新安装扩展，之前保留的 PostNL 设置会再次生效。
配置
所有设置都在扩展页面中：Extensions > Extensions > Shipping > VibeFox PostNL > Edit。各个部分列在左侧。底部的一个 Save 按钮会保存整个页面，无需刷新。只有拥有本扩展修改权限的管理员用户才能保存设置。
如果某个值有误，则不会保存任何内容，页面会显示原因：选项名称为空、超过 64 个字符，或包含 < > ; = # { }；排序不是整数；最低重量高于最高重量；或税类、地理区域无效。较小的问题会带备注保存：无效或负数会使对应字段留空，无效的发货邮政编码会以空值保存，价格表中的无效价格会被忽略。
设置上方的页面会显示警告：取件点缺少 API 密钥或发货邮政编码、已开启沙盒、未设置任何价格、最近一次失败的 PostNL 请求（含日期和错误），或店铺中没有重量单位为“kg”的重量类别。
常规
每种配送方式在结账时都是独立的选项。本页的设置对两者均适用。
PostNL pickup point：开启或关闭取件点选项。顾客必须在结账时选择一个 PostNL 网点。该选项仅对荷兰和比利时的地址提供，且仅在填写了 API 密钥的情况下提供。默认：关闭。
Pickup point option name：顾客在结账时看到的名称。默认：PostNL pickup point。必填，最多 64 个字符，不得包含 < > ; = # { }。
PostNL home address：开启或关闭上门配送选项。不选择任何网点。对每个设置了价格的国家都有效。默认：关闭。
Home delivery option name：顾客在结账时看到的名称。默认：PostNL。规则与取件点名称相同。
Sort order：PostNL 在结账时的配送方式中的位置。一个整数。
Tax class：两个选项的税类。选择税类后，OpenCart 会在价格上加收该税。No tax 表示价格为最终价格。
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 的国家：荷兰或比利时。PostNL 使用发件人地址确定取件日期。安装时，如果店铺所在国家是荷兰或比利时，则设为该国家，否则设为荷兰。
Ship from (postcode)：发件人邮政编码，例如荷兰的 1234AB 或比利时的 1000。取件点必填：OpenCart 没有店铺邮政编码，因此不会从店铺地址中获取。无效的邮政编码会以空值保存并给出警告。
更改 API 密钥、沙盒设置或发货地址时，已缓存的取件点列表和最近一次 API 错误都会被清除。
价格（以店铺默认货币计，不含税）
价格适用于两个选项。PostNL 没有公开的运费 API，因此本扩展不会请求实时运费。对于使用其他货币付款的顾客，OpenCart 会按店铺的汇率换算价格。
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)：购物车较重时隐藏选项。PostNL 包裹在 Benelux 地区最重可达 30 kg。0 表示没有限制。留空时适用 30 kg，若 Ignore shipping zones 已开启则没有限制。
所有金额和重量都接受小数逗号。
可用性
Geo zone：仅对此地理区域内的地址提供 PostNL。All zones（默认）表示没有限制。当 Ignore shipping zones 开启时不检查地理区域。地理区域在 System > Localisation > Geo Zones 中管理。
Ignore shipping zones：开启时，不检查地理区域，并对下方选定的国家提供 PostNL（若列表为空则对所有国家提供）。关闭时，只有地理区域有效。
Countries：该模式下的目的国家。留空则允许所有国家。仅当 Ignore shipping zones 开启时使用此字段。取件点选项仍然只对荷兰和比利时提供。
高级
Debug log：将调试信息写入 storage/logs/vfd_ptnl_debug.log.php（在 OpenCart 4 中为 system/storage/logs/vfd_ptnl_debug.log.php）。该文件无法通过网页读取。API 错误以及没有有效取件点的订单始终会被记录。不会写入 API 密钥或顾客数据。完成后请关闭日志。当文件达到 5 MB 时，将开始新的日志。
Log：显示调试日志的大小和最新条目。点击 Clear log 可清空日志。
Remove data on uninstall：开启时，卸载扩展会删除 PostNL 设置和日志。已缓存的网点列表始终会被删除。订单中保存的取件点始终会保留。
导入 / 导出
导出：点击 Download JSON 将设置保存为 JSON 文件。API 密钥不会被导出。
导入：粘贴之前导出的 JSON，然后点击 Import 恢复设置，例如在另一家店铺中使用。这些值会像普通保存一样进行检查。已保存的 API 密钥会保留。
结账时的工作方式
OpenCart 显示配送方式时，会向扩展请求每个 PostNL 选项的价格。如果开启了 Ignore shipping zones，则只对允许的国家提供 PostNL，与地理区域无关。否则，如果设置了 Geo zone，地址必须位于其中。只有 Requires Shipping 设为 Yes 的商品才计入：其他商品不会增加重量，也不计入小计。扩展会检查购物车重量和最低小计。然后，它会从价格表中获取该国家和重量等级对应的价格，或获取其他国家的价格。如果没有价格，该选项将被隐藏。如果购物车小计达到 Free shipping from，价格为 0。价格会以顾客的货币显示，并包含所选 Tax class 的税费。
取件点选项仅对荷兰和比利时的地址提供，且仅在填写了 API 密钥的情况下提供。当配送地址包含完整邮政编码时，扩展会向 PostNL Checkout API 请求最近的三个取件点。它会发送顾客的邮政编码、街道和门牌号、城市和国家，以及您的发货地址。上门配送选项不会发送任何内容。如果无法连接 PostNL，或该地址没有网点，则隐藏取件点选项，上门配送仍然可用。API 超时时间为 12 秒。
网点列表按地址缓存 6 小时，“无网点”的回复缓存 1 小时。失败的请求缓存 10 分钟，以免故障使每次结账刷新都变慢。缓存保存在扩展自己的数据库表中。最近一次错误会显示在扩展页面上，直到下一次请求成功为止。
本扩展不会请求 PostNL 的实时运费，也不会创建运输标签、条形码、包裹追踪、退货或预先通知。它没有配送日期、晚间或上午配送选项。请使用保存的取件点，在 Mijn PostNL 或其他 PostNL 工具中创建发货单。
在 OpenCart 4 中，顾客在结账页的配送方式区块中点击 Choose，并在 Shipping method options 窗口中选择一个 PostNL 选项。价格与 OpenCart 3 相同。
取件点
当配送地址位于荷兰或比利时时，取件点选项下方会出现一个 PostNL pickup point 列表，显示最近的三个网点：公司名称、地址和距离，最近的排在最前。页面从不等待 PostNL：如果列表尚未缓存，则会在选择该选项后立即加载。在输入完整邮政编码之前，顾客会看到 "Enter your postcode (for example 1234 AB) to see PostNL pickup points."（比利时为 4 位数字）。所选取件点会立即保存用于结账。
取件点是必填的。当顾客在配送方式步骤点击 Continue 时，服务器会将取件点与 PostNL 针对该配送地址的列表进行核对。如果没有选择取件点，顾客会看到 "Please choose a PostNL pickup point."。如果该取件点不在列表中，顾客会看到 "The chosen PostNL pickup point is not available for this address. Please choose it again."。如果无法连接 PostNL，顾客会看到 "PostNL pickup points cannot be loaded right now. Please try again in a few minutes or choose another shipping method."。为其他地址选择的取件点绝不会用于订单。随订单保存的名称和地址来自 PostNL，而非浏览器。
订单页面、邮件和发票：取件点会添加到订单的配送方式中，例如 "PostNL pickup point: 名称, 地址"（先是取件点选项的名称，然后是取件点）（最多 128 个字符，在 OpenCart 4 中最多 255 个字符）。它会显示在 OpenCart 显示配送方式的所有地方：顾客的订单历史、订单邮件、发票以及 Sales > Orders。
管理后台订单页面：在 Sales > Orders 中，订单页面会在历史记录上方显示一个 PostNL pickup point 面板，包含取件点、Location code 和 Partner ID。仅对保存了取件点的订单显示，即使扩展已被禁用也是如此。
在 OpenCart 4 中，列表显示在 Shipping method options 窗口中 PostNL pickup point 选项的下方，并且每次打开窗口时都会重新加载，因为在一页式结账中地址可能会变化。窗口中的 Continue 按钮在没有有效取件点时不会继续，并显示相同的消息。OpenCart 4 为结账保留一个订单，并在顾客每次重新确认时更新它，订单的取件点也会随之更新。
许可证密钥
本扩展需要配合 vibefox.net 提供的 VibeFox 许可证密钥使用。许可证区块 License — VibeFox PostNL 是 Extensions > Extensions > Shipping > VibeFox PostNL > Edit 页面中位于设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以隐藏方式显示密钥、状态（例如许可证有效期截止日期和您的域名），并提供以下按钮：Check now 用于重新检查状态，Change key 用于输入其他密钥，Remove key 用于从本店铺移除密钥。其下方是 Product: opencart-shipping-postnl 一行，以及打开您 vibefox.net 账户的链接 Manage licenses and domains in your account。只有拥有本扩展 Modify 权限的管理员用户才能更改密钥。该区块的文字跟随管理后台语言（包含英语和俄语）。
如果密钥未被接受，该区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或带有日期的 License expired on。在店铺地址更改后，或在您的账户中释放了域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展将继续使用最后已知的状态运行。
一个密钥只能在一个域名上使用：即 OpenCart 配置中的店铺地址。从店铺中移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
如果没有有效的密钥，PostNL 配送选项不会在结账时显示给顾客，也不会计算运费。在后台同一浏览器中登录的管理员用户仍能在店铺中看到这些选项，并标记为 (unlicensed — visible to admins only)，因此您可以在购买密钥之前完成设置和测试。在 OpenCart 4 中没有此预览功能：店铺无法识别后台登录状态，因此没有有效密钥时，这些选项对所有人都隐藏。打开一次 Edit 页面后，后台 Dashboard 会出现提醒。点击 × 关闭，可隐藏 7 天。现有订单不受影响。
许可证到期后，扩展仍会继续运行，但更新和支持需要续费。当您打开后台 Dashboard 或 Edit 页面时会自动再次检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展总会删除许可证密钥和许可证状态。
故障排除
PostNL 未出现在结账页面：请检查许可证是否有效，PostNL pickup point 或 PostNL home address 是否已开启。检查 Geo zone（或 Ignore shipping zones 是否开启且该国家已被允许）、该国家是否设置了价格、重量限制以及 Minimum subtotal。检查商品的 Requires Shipping 是否设为 Yes。
取件点选项未出现：它只会对荷兰和比利时的地址显示，且只有在填写了 API 密钥、发货邮政编码和价格，并且 PostNL 为顾客的邮政编码返回了网点时才会显示。请查看扩展页面顶部的警告和 Log 字段。错误总会被记录；如需详细信息，请开启 Debug log。
"PostNL pickup points cannot be loaded right now"：无法连接 PostNL、PostNL 拒绝了 API 密钥，或缺少发货邮政编码。扩展页面会显示最近一次错误。沙盒密钥仅在开启 Sandbox 时有效，正式密钥仅在关闭时有效。
顾客看到的是测试取件点：关闭 Sandbox。
商品重量看起来不对：如果扩展页面提示店铺没有重量单位为“kg”的重量类别，请检查 System > Localisation > Weight Classes。商品重量会根据其类别的单位名称换算，无法识别的单位将按千克处理。
页面显示 "Warning: You do not have permission to modify VibeFox PostNL!"：您的管理员用户组可能只能查看设置。请在 System > Users > User Groups 中，为该组授予 extension/shipping/vfd_postnl（OpenCart 3）或 extension/vfd_postnl/shipping/vfd_postnl（OpenCart 4） 的修改权限。
面向开发者：可以使用设置 vfd_ptnl_api_url（用于测试）替换 PostNL API 地址；设置页面上没有对应字段。
卸载
进入 Extensions > Extensions，选择类型 Shipping，然后点击 VibeFox PostNL 旁边的 Uninstall（红色 − 按钮）。本扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会重置扩展状态、Sort order、Tax class 和 Geo zone。已缓存的取件点列表和最近一次 API 错误始终会被删除。如果 Remove data on uninstall 处于开启状态，则 PostNL 设置、调试日志以及从未成为订单的结账中的取件点也会被删除。如果处于关闭状态，其他设置会保留，并在您重新安装扩展时再次使用。现有订单会保留其配送方式、费用和已保存的取件点。
在 OpenCart 4 中，如需同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox PostNL 旁边的 Uninstall（橙色的 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。
PostNL 是其各自所有者的商标。本扩展与 PostNL 无关联，也未获得 PostNL 的认可。