VibeFox bpost Cubee for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块不会安装在较旧的 PHP 版本上。
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 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或之后在模块列表中找到 VibeFox bpost Cubee 并点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入 License key 字段，然后点击 Activate（参见许可证密钥）。
4. 输入您的运费，并为取件点选择器输入 bpost API 密钥（见配置）。点击 Save。
安装时，模块会创建承运商 bpost parcel locker，配送时间文本为 Pickup point or parcel locker。该承运商关联比利时区域和所有顾客群组，不设税务规则。您可以在 Shipping > Carriers 中更改区域、顾客群组、配送时间和标志。请不要在那里设置运费：运费始终来自模块。
配置
所有设置都位于模块页面：Modules > Module Manager > VibeFox bpost Cubee > Configure。每个部分都有自己的 Save 按钮，会保存整个页面。每次保存还会清除已存储的 API 令牌和缓存的取件点列表。
当有内容悄悄隐藏了承运商或选择器时，页面会显示警告：取件点选择器已开启但 API 密钥不完整，比利时（BE）没有运费且没有默认运费，最近一次连接 bpost API 失败，模块无法识别商店的重量单位（请在 International > Localization 的 Local units 中设置），或未找到 bpost 承运商。保存时，无法读取的 Country prices 行会列在警告中，无法识别任何尺寸的 Size prices 值也会如此。不是数字或为负数的重量或金额不会被保存：警告会指出该字段，并保留之前的值。如果 Min weight (kg) 大于 Max weight (kg)，重量也不会被保存。
常规
Enable/Disable：开启或关闭 bpost parcel locker 配送。这与 Shipping > Carriers 中的承运商状态是同一个开关。
Name：结账时显示给顾客的配送方式名称（承运商名称）。默认：bpost parcel locker。如果留空，则使用默认值。最多 64 个字符；超过长度的名称会被拒绝，且不会保存任何内容。
Tax status：None 表示运费为最终价格。Taxable 并配合税务规则时，会在您的运费之上加上该规则的税。该选择会保存到承运商。
bpost API（取件点搜索）（仅取件点选择器需要）
Account ID (public key)：您在 plugins.bpost.be 的 Key management 中获得的 bpost Shipping Platform 账户公钥。清空此字段也会删除已保存的 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 合同中承运商的 ID，其取件点和包裹储物柜将被列出。默认：68（bpost）。合同中启用的其他承运商有各自的 ID。
取件点选择器
Pickup points：在结账时显示取件点和包裹储物柜选择器。默认开启。只有当三个 API 密钥都已填写时，选择器才会出现，并且才需要选择取件点。
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 超过 10 kg。
Calculation：Per order 只收取一次运费。Per item (price x number of items) 则乘以购物车中的商品数量。
价格会按默认货币的小数位数取整，然后以顾客购物车的货币显示。
条件
Min weight (kg)：承运商显示所需的最低购物车重量。商品重量从您商店的重量单位转换。0 表示无限制。
Max weight (kg)：购物车重量超过此值时隐藏承运商。默认：30，因为 bpost 包裹储物柜可接受最多 30 kg 的包裹。0 表示无限制。
Minimum order amount：仅当购物车小计达到此金额时才显示承运商。小计按折扣后、不含税的需要配送的商品计算。留空则始终显示承运商。
免运费
Free shipping：开启以下金额起的免费配送。
Free shipping from：免运费起点的购物车小计（需要配送的商品，折扣后，不含税）。仅在 Free shipping 开启时使用。该国家仍需有价格，否则不会提供承运商。
无配送区域时的可用性
通常，承运商在 Shipping > Carriers 中的配送区域内提供。安装时，即比利时区域。
Ignore shipping zones：在下方的国家中提供承运商，但不将其添加到某个区域。此时，承运商会关联到所有有效区域，包括您之后创建的区域。当您再次关闭该选项时，承运商会恢复之前的区域。
Countries：该模式下的目的地国家。默认：比利时。留空则使用您发货的所有国家。此字段仅在 Ignore shipping zones 开启时使用。
高级
Debug log：将 API 请求和运费计算记录到模块文件夹中的 logs/vfd_bpst_debug.log.php。该文件无法通过网页打开。即使此选项关闭，API 错误也总会被记录。密钥和令牌永远不会被记录。
Log：显示调试日志的大小和最新条目。点击 Clear log 可清空。
Remove data on uninstall：开启时，卸载模块会删除模块设置和承运商。订单中保存的取件点始终保留。
结账时的工作方式
在配送步骤，PrestaShop 向模块请求 bpost 运费。只计算需要配送的商品：虚拟商品不增加重量，也不计入订单金额。模块检查各项条件：Ignore shipping zones 的国家（若已开启）、购物车重量和最低订单金额。然后从国家列表或按包裹尺寸获取运费，在按商品模式下乘以商品数量，并在适用免运费时将其设为零。计算运费时不会向 bpost 发送请求。
在 bpost 承运商下方，顾客会看到一个 Postal code or city 字段、一个 Search 按钮和一个取件点列表。当顾客选择该承运商且尚未搜索时，会自动搜索配送地址的邮政编码。顾客可以输入其他邮政编码或城市名称。每个取件点以名称和地址显示。最多列出 50 个取件点。当商店语言为荷兰语时，列表以荷兰语请求，否则以法语请求。
顾客必须选择一个取件点。若未选择，配送步骤中的 Continue 会显示 Please select a bpost pickup point.，并且 Place order 按钮会在页面上被拦截，显示相同的信息。只接受 bpost 搜索列表中的取件点。否则，顾客会看到 The selected bpost pickup point is not in the list of your search. Please choose another one. 搜索和选择会与购物车一起保存，因此刷新页面不会丢失。新搜索会清除之前的选择。
为列出取件点，模块仅向 bpost 发送搜索的邮政编码或城市、国家和承运商 ID，并使用您的密钥签名。API 令牌会自动请求和续期。如果 bpost 拒绝令牌，将重新请求一次并重复搜索。搜索结果缓存 6 小时。如果 bpost 没有响应，顾客会看到 Pickup points cannot be loaded right now. Please try again in a few minutes or choose another shipping method.，模块将在 5 分钟后重试。API 超时为 15 秒。
如果您在 Shipping > Carriers 中编辑已有订单的承运商，PrestaShop 会将其保存为新的承运商版本。模块会自动跟随新版本。
模块仅使用固定运费。它不会从 bpost 获取实时运费、创建发货单、打印运单或追踪包裹。取件点以列表形式显示，而非地图。请在您的 bpost Shipping Platform 或 Shipping Manager 账户中创建发货单；取件点 ID 位于订单中。
取件点
下单时，所选取件点（名称和地址）及其 ID 会与订单一同保存。在后台订单页面，bpost pickup point 区块会显示该取件点及其 ID，或显示 No pickup point was selected for this order. 点击 Change，搜索邮政编码或城市，从列表中选择另一个取件点，然后点击 Save。订单会立即更新，页面显示 Pickup point updated. 当 Debug log 开启时，该更改会写入模块调试日志。仅当 API 密钥已填写时，才可使用 Change 链接。保存新取件点需要编辑订单的权限；否则页面会显示 Permission denied. 无需访问 Modules 页面。
如果 PrestaShop 将一个购物车拆分为多个订单，取件点会保留在第一个订单中。其他订单没有取件点，调试日志会显示一条错误，指明第一个订单；请在 bpost 中手动为这些包裹设置取件点。
顾客会在订单确认页面以及其账户的订单详情中，将取件点看作 bpost pickup point:。它还会添加到订单确认邮件的承运商名称中。发给商店的新订单邮件（如果您使用电子邮件提醒模块）也包含取件点 ID。
若要同时提供包裹储物柜和送货上门，请在同一区域为送货上门使用另一承运商。取件点选择器仅在 bpost 承运商下显示。
许可证密钥
本模块使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox bpost Cubee 位于 Modules > Module Manager > VibeFox bpost Cubee > Configure 页面的最上方，位于设置之上。将密钥输入 License key 并点击 Activate。之后，该区块会以隐藏方式显示密钥、状态（例如许可证有效期截止日期和您的域名），并提供以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺移除密钥）。其下方是 Product: presta-shipping-bpost-cubee 一行，以及打开您 vibefox.net 账户的链接 Manage licenses and domains in your account。只有拥有本模块 Configure 权限的员工才能更改密钥。该区块的文字会跟随后台语言显示（包含英文和俄文）。
如果密钥未被接受，该区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或带日期的 License expired on。在店铺地址更改后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，模块将继续使用最后已知的状态运行。
一个密钥只能用于一个域名：主店铺的域名，多店铺设置中也是如此。从店铺中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效的密钥时，bpost 承运商不会在结账时显示给客户，也不会计算任何运费。PrestaShop 前台无法得知您已登录后台，因此承运商对您也是隐藏的：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 中的 Alerts 选项卡会显示提醒。现有订单不受影响。
许可证过期后，模块仍会继续运行，但更新和支持需要续费。在您使用后台时，系统会自动再次检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时没有 bpost：请检查许可证是否有效，且 Enable/Disable 已开启。在 Shipping > Carriers 中，检查该承运商是否覆盖顾客所在国家的区域和顾客群组，或者 Ignore shipping zones 已开启且该国家在 Countries 中。检查该国家是否有运费，或是否存在 *=价格 行，并检查重量限制和 Minimum order amount。商品也可能在商品页面中被限制为特定承运商。当比利时没有运费时，设置页面会显示警告。
结账时没有取件点选择器：请检查 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 均被接受。不符合 CC=价格 格式的 Country prices 行会被忽略；保存后的警告会列出这些行。
价格是否含税？当 Tax status 设为 None 时，价格为最终价格。使用 Taxable 税务规则时，PrestaShop 会在您的价格之上加上该税。
页面提示未找到 bpost 承运商：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块，以重新创建它。
对于开发人员，actionVfdBpstApiUrl 和 actionVfdBpstApiLanguage 钩子可更改 bpost API 地址以及取件点列表的语言。
卸载
进入 Modules > Module Manager，打开 VibeFox bpost Cubee 旁边的菜单，然后选择 Uninstall。许可证密钥和许可证状态总会被删除。已存储的 API 令牌和缓存的取件点列表总会被删除。如果 Remove data on uninstall 已开启，承运商将被删除（订单保留历史记录），未完成购物车的设置、日志和取件点也会被删除。如果关闭，承运商仅会被停用，所有设置都会保留。重新安装模块会使承运商恢复到卸载前的状态。Modules > Module Manager 中的 Reset 工作方式相同，因此已停用的承运商仍保持停用。订单中保存的取件点属于订单历史，永远不会被删除。
bpost 是其各自所有者的商标。本模块与 bpost 无关联，也未获得 bpost 的认可。