VibeFox bpost Cubee for OpenCart — 帮助
要求
OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP：8.0 或更高版本。
bpost Shipping Platform 账户（仅用于取件点选择器）：本扩展通过 bpost Shipping Platform API 搜索取件点。请在 plugins.bpost.be 登录您的 bpost Shipping Platform 账户，并在 Settings > Key management 中创建密钥。您需要三个值：Account ID（公钥）、Passphrase（私钥）和 App ID（X-APPID）。App ID 由 bpost 为您的集成颁发；请联系 bpost 电子商务支持（eol@bpost.be）。您还需要合同中的承运商 ID（68 = bpost）。如果没有完整的密钥，该方式仍可使用固定价格，但不会要求顾客选择取件点。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥仅适用于一个域名。
安装
下载包是一个 zip 文件，内含适用于两个 OpenCart 版本的安装包。请解压到您的计算机上。其中包括 README.txt、OpenCart 3 安装包 vfd_bpost_cubee-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 vfd_bpost_cubee.ocmod.zip。只需安装适用于您 OpenCart 版本的安装包。两个版本使用相同的许可证密钥。
OpenCart 3
1. 在管理后台进入 Extensions > Installer，点击 Upload，选择文件 vfd_bpost_cubee-oc3-(version).ocmod.zip。本扩展不添加任何 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装器，而是将安装包中 upload 文件夹的内容复制到店铺的根目录。
2. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox bpost Cubee，点击 Install（绿色 + 按钮）。
3. 点击 Edit（铅笔按钮）打开设置页面。
4. 在 Edit 页面顶部的许可证区块中，将 VibeFox 许可证密钥输入 License key 并点击 Activate（见许可证密钥）。
5. 输入您的价格，例如 BE=4.95 和 *=9.95；如需使用取件点选择器，还需输入 bpost API 密钥（见配置）。开启 Enable/Disable，然后点击 Save。
OpenCart 4
1. 在管理后台进入 Extensions > Installer，点击 Upload，选择文件 vfd_bpost_cubee.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包将无法使用。
2. 该安装包会出现在同一页面已安装扩展的列表中。点击其旁边的 Install（绿色 + 按钮）。
3. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox bpost Cubee，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按照 OpenCart 3 的步骤 4 和 5 输入许可证密钥和设置。两个版本的设置页面及其字段相同。
安装后，该方式处于关闭状态，直到您开启并保存。如果您卸载后重新安装本扩展，之前保留的设置会再次生效。
配置
所有设置都位于扩展页面：Extensions > Extensions > Shipping > VibeFox bpost Cubee > Edit。各部分列在左侧。点击一次 Save 按钮即可保存整个页面，无需重新加载。每次保存还会清除已保存的 API 令牌和已缓存的取件点列表。只有拥有本扩展修改权限的管理员用户才能保存设置。
有些错误会中止保存，此时不会保存任何内容：Name 超过 64 个字符，Sort Order 不是整数，或税类、地理区域未知。其他问题会以警告形式报告，其余部分仍会保存：不是数字或为负数的重量或金额不会保存，保留原值；如果 Min weight (kg) 大于 Max weight (kg)，重量不会保存；无法读取的 Country prices 行会被列出并忽略；Size prices 中如果没有识别出任何尺寸，也会被报告。
页面顶部会在某些情况悄悄隐藏该方式或选择器时发出警告：取件点选择器已开启但 API 密钥不完整，比利时（BE）没有价格且没有默认价格（*=价格），最近一次连接 bpost API 失败，或店铺没有单位为 "kg" 的重量类别（System > Localisation > Weight Classes）。在最后这种情况下，商品重量会按其单位名称读取（kg、g、lb 或 oz）。
通用
Enable/Disable：在结账时开启或关闭 bpost 包裹智能柜配送。默认：关闭。
Name：结账时向顾客显示的配送方式名称。默认：bpost parcel locker。如果留空，则使用默认值。最多 64 个字符。
Tax Class：此税类的税费会加在您的价格之上。--- None ---（默认）表示价格为最终价格。
Sort Order：该方式在配送方式列表中的位置。
bpost API（取件点搜索）（仅取件点选择器需要）
Account ID (public key)：您的 bpost Shipping Platform 账户的公钥，可在 plugins.bpost.be 的 Key management 中找到。清空此字段也会删除已保存的 passphrase。
Passphrase (private key)：用于为每个请求签名的私钥（HMAC-SHA256）。它从不发送给 bpost，也不写入日志。保存后该字段会保持为空，并显示 Saved - leave empty to keep it. 仅在需要更改时输入新值。
App ID (X-APPID)：bpost 为您的集成颁发的应用标识符。它会在 X-APPID 请求头中发送。
Carrier ID：您的 bpost Shipping Platform 合同中的承运商，其取件点和包裹智能柜将被列出。默认：68（bpost）。合同中启用的其他承运商有各自的 ID。
取件点选择器
Pickup points：在结账时显示取件点和包裹智能柜选择器。默认开启。只有当 Account ID、Passphrase 和 App ID 全部填写后，选择器才会出现，并且必须选择取件点。
Search field width：邮政编码 / 城市字段的 CSS 宽度，例如 100% 或 300px。默认：100%。
Pickup point list width：取件点列表的 CSS 宽度，例如 100% 或 400px。默认：100%。
价格（以店铺默认货币计，不含税；bpost 不通过此 API 返回配送价格）
Price by：价格的选择方式。
Country prices：每个国家一行，格式为 CC=价格，例如 BE=4.95。*=价格 一行为所有其他国家设置价格，例如 *=9.95。小数点和逗号都可作为小数分隔符。无效的行会被忽略。没有价格的国家（没有 * 行时）不会提供该方式。
Size prices：当 Price by 为包裹尺寸时使用，格式为 S=3.50、M=4.50、L=6.00、XL=8.00。尺寸由购物车重量决定：S 最高 2 kg，M 最高 5 kg，L 最高 10 kg，XL 以上。
Calculation：Per order（默认）只收取一次价格。Per item (price x number of items) 则将价格乘以购物车中的商品数量。
价格会按店铺默认货币的小数位数取整，然后以顾客的货币显示。
条件
Min weight (kg)：该方式显示所需的最低购物车重量。商品重量会换算为 kg。0 表示不限制（默认）。
Max weight (kg)：购物车重量超过此值时隐藏该方式。默认：30，因为 bpost 包裹智能柜可接受最高 30 kg 的包裹。0 表示不限制。
Minimum order amount：仅当购物车小计达到此金额时才显示该方式。小计包括需要配送的商品，已扣除优惠券，不含税。留空则始终显示该方式。
免运费
Free shipping：达到下方金额时开启免费配送。
Free shipping from：购物车小计（需要配送的商品，扣除优惠券，不含税），达到该金额即免运费。仅在 Free shipping 开启时使用。该国家仍需有价格，否则不提供该方式。
可用性
通常该方式会在下方选定的地理区域内提供。开启 Ignore geo zone 后，则改为在列表中的国家提供。
Geo Zone：仅向此地理区域内的地址提供该方式。All Zones（默认）表示所有地区。地理区域在 System > Localisation > Geo Zones 中管理。
Ignore geo zone：无论地理区域如何，都在下方列出的国家提供该方式。
Countries：该模式下的目的地国家。默认：Belgium。留空则允许所有国家。仅在 Ignore geo zone 开启时使用。
高级
Debug log：将 API 请求和价格计算写入 storage/logs/vfd_bpst_debug.log.php。该文件无法通过网页读取。即使此选项关闭，API 错误也始终会被记录。密钥和令牌从不写入日志。
Log：显示调试日志的大小和最新条目。点击 Clear log 可清空。
Remove data on uninstall：开启时，卸载扩展会删除设置、日志以及未完成结账的取件点选择。已保存在订单中的取件点始终保留。默认：关闭。
导入 / 导出
Export：点击 Download JSON，将设置保存为 JSON 文件。passphrase 不会被导出。
Import：粘贴之前导出的 JSON，然后点击 Import，即可恢复设置，例如在另一家店铺中使用。这些值会像正常保存时一样进行检查。已保存的 passphrase 会被保留。
结账时的工作方式
当 OpenCart 显示配送方式时，它会向扩展请求 bpost 价格。如果设置了 Geo Zone（且 Ignore geo zone 关闭），并且地址在该区域之外，则不会提供该方式。只有 Requires Shipping 设为 Yes 的商品才会计算在内：其他商品不增加重量，也不计入订单金额。扩展会检查各项条件：Ignore geo zone 的国家（若已开启）、购物车重量和最低订单金额。然后它从国家列表或包裹尺寸中获取价格，在按商品计算模式下乘以商品数量，并在适用免运费时将其设为零。计算价格时不会向 bpost 发送任何请求。
在 bpost 选项下，顾客会看到 Postal code or city 字段、Search 按钮和取件点列表。当顾客选择 bpost 且列表尚未加载时，会自动搜索配送地址的邮政编码（或顾客上次的搜索）。顾客可以输入其他邮政编码或城市名称。每个取件点都会显示其名称和地址。最多列出 50 个取件点。当店铺语言为荷兰语时，列表以荷兰语请求，其他情况下以法语请求。
顾客必须选择一个取件点。没有选择时，配送方式步骤中的 Continue 会显示 Please select a bpost pickup point. 只接受 bpost 搜索列表中的取件点。否则顾客会看到 The selected bpost pickup point is not in the list of your search. Please choose another one. 搜索和选择结果会为结账保存，因此刷新页面不会丢失。新的搜索会清除之前的选择。
在 OpenCart 4 中，顾客在结账页面的配送方式区块中点击 Choose，并在 Shipping method options 窗口中选择 bpost。取件点搜索和列表会显示在该窗口中 bpost 选项的下方。在没有选择取件点的情况下，窗口中的 Continue 会显示 Please select a bpost pickup point. 其余操作与 OpenCart 3 相同。
为列出取件点，扩展只向 bpost 发送所搜索的邮政编码或城市、国家和承运商 ID，并使用您的密钥签名。API 令牌会自动申请和续期。如果 bpost 拒绝令牌，将重新申请一次并重复搜索。搜索结果最长缓存 6 小时，但不超过 OpenCart 缓存的有效期（默认 1 小时）。如果 bpost 没有响应，顾客会看到 Pickup points cannot be loaded right now. Please try again in a few minutes or choose another shipping method.，扩展会在 5 分钟后重试。API 超时时间为 15 秒。
扩展只使用固定价格。它不会从 bpost 获取实时运费，不会创建发货单、打印面单或跟踪包裹。取件点以列表形式显示，而非地图。请在您的 bpost Shipping Platform 或 Shipping Manager 账户中创建发货；取件点 ID 位于管理后台的订单页面。
取件点
下单时，所选取件点会以 bpost pickup point: 的形式，连同取件点名称和地址，添加到订单的配送方式中，例如 "bpost parcel locker - bpost pickup point: …"。因此顾客会在订单确认、账户订单历史、订单电子邮件和发票中看到它。包含 ID 的完整取件点信息也会保存在扩展的单独数据表中。在 OpenCart 4 中，结账会保留一个订单：当顾客再次确认订单时（例如选择了另一个取件点后），订单中的取件点会被更新。
在管理后台，Sales > Orders 中的订单页面会显示 bpost pickup point 面板，其中包含取件点及其 ID，或者显示 No pickup point was selected for this order. 点击 Change，搜索邮政编码或城市，从列表中选择另一个取件点，然后点击 Save。订单及其配送方式文本会立即更新，页面显示 Pickup point updated. 如果该取件点不在此次搜索的 bpost 列表中，页面会显示 Pickup point not found in the bpost list of this search. 当 Debug log 开启时，此更改会写入调试日志。Change 仅在 API 密钥已填写且管理员用户有修改订单权限时可用；无需访问扩展设置。
若要同时提供包裹智能柜和送货上门，请为送货上门使用另一种配送方式。取件点选择器仅在 bpost 选项下显示。
许可证密钥
本扩展需要一个来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox bpost Cubee 许可证区块是 Extensions > Extensions > Shipping > VibeFox bpost Cubee > Edit 页面中位于设置上方的第一个区块。将密钥粘贴到 License key 中并点击 Activate。之后，该区块会以隐藏方式显示密钥、状态（例如许可证有效期截止日期和您的域名），并提供以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺移除密钥）。其下方是 Product: opencart-shipping-bpost-cubee 一行，以及 Manage licenses and domains in your account 链接，可打开您的 vibefox.net 账户。只有拥有本扩展 Modify 权限的管理员用户才能更改密钥。该区块的文字跟随后台语言显示（包括英语和俄语）。
如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或带有日期的 License expired on。在店铺地址变更后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展将继续使用最后已知的状态运行。
一个密钥仅适用于一个域名：即 OpenCart 配置中的店铺地址。从店铺中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，bpost 配送方式不会在结账时显示给顾客，也不会计算运费。在同一浏览器中登录后台的管理员用户仍能在店铺中看到该方式，并标注 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试本扩展。在 OpenCart 4 中，此预览不可用：店铺看不到后台登录状态，因此没有有效密钥时，该方式会对所有人隐藏。打开一次 Edit 页面后，后台的 Dashboard 上会出现提醒。点击 × 可将其隐藏 7 天。现有订单不受影响。
许可证到期后，扩展仍会继续运行，但更新和支持需要续费。打开后台的 Dashboard 或 Edit 页面时，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展时，总会删除许可证密钥和许可证状态。
故障排除
bpost 未出现在结账页面：检查许可证是否有效以及 Enable/Disable 是否开启。检查 Geo Zone，或确认 Ignore geo zone 已开启且该国家在 Countries 中。检查该国家是否有价格，或是否存在 *=价格 行，并检查重量限制和 Minimum order amount。检查商品的 Requires Shipping 是否设为 Yes。若比利时没有价格，设置页面会显示警告。
结账时没有取件点选择器：检查 Pickup points 是否开启，并且 Account ID (public key)、Passphrase (private key) 和 App ID (X-APPID) 是否全部填写。如果密钥不完整，设置页面会显示警告。
顾客看到 "Pickup points cannot be loaded right now"：bpost 没有响应或拒绝了密钥。原因会显示在设置页面顶部以及调试日志中（扩展页面的 Log 字段）。扩展会在 5 分钟后自动重试。保存设置会立即重试。
该邮政编码或城市没有找到取件点：bpost 未针对此搜索返回任何取件点。请让顾客尝试附近的邮政编码或城市名称，并检查 Carrier ID。
带逗号的价格未被使用：5,50 和 5.50 都会被接受。Country prices 中不符合 CC=价格 格式的行会被忽略；保存后的警告会列出这些行。
价格是否含税？当 Tax Class 设为 --- None --- 时，价格为最终价格。设置了税类后，OpenCart 会在您的价格之上加上该税。
页面显示 "Warning: You do not have permission to modify VibeFox bpost Cubee!"：您的管理员用户组可能只能查看设置。请在 System > Users > User Groups 中为该组授予 extension/shipping/vfd_bpost_cubee（OpenCart 3）或 extension/vfd_bpost_cubee/shipping/vfd_bpost_cubee（OpenCart 4）的修改权限。
开发人员：bpost API 地址可通过设置 vfd_bpst_api_url（用于测试）替换；设置页面中没有对应字段。
卸载
进入 Extensions > Extensions，选择类型 Shipping，然后点击 VibeFox bpost Cubee 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态总会被删除。OpenCart 总会重置 Enable/Disable、Sort Order、Tax Class 和 Geo Zone。已保存的 API 令牌和已缓存的取件点列表总会被删除。如果开启了 Remove data on uninstall，设置、日志以及未完成结账的取件点也会被删除。如果关闭，其他设置会保留，并在您重新安装扩展时再次使用。保存在订单中的取件点属于订单历史，永远不会被删除。现有订单会保留其配送方式和费用。
在 OpenCart 4 中，如需同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox bpost Cubee 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。
bpost 是其各自所有者的商标。本扩展与 bpost 无关联，也未获得 bpost 的认可或背书。