VibeFox bpost Cubee for WooCommerce — 帮助
系统要求
WordPress：5.8 或更高版本。
WooCommerce：7.0 或更高版本，已安装并启用。没有它，插件无法启用。
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 购买。一个密钥只能用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 vfd_bpost_cubee 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Shipping > VibeFox bpost Cubee，或在插件页面点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 输入您的价格；如需使用取件点选择器，请输入 bpost API 密钥（参见配置）。
6. 在 WooCommerce > Settings > Shipping > Shipping zones 中，将 VibeFox bpost Cubee 添加到比利时的配送区域；或者开启 Ignore shipping zones 并选择国家。
配置
所有设置都在同一页面：WooCommerce > Settings > Shipping > VibeFox bpost Cubee。这些设置适用于所有配送区域。将该方式添加到某个区域时，区域窗口中只有一个字段：
Title (zone)：该区域结账时此选项的名称。留空则使用全局 Name。
设置页面会在某些情况下显示警告，这些情况会悄悄隐藏该方式或选择器：取件点选择器已开启但 API 密钥不完整、比利时没有价格，或最近一次连接 bpost API 失败。每次保存设置时，已存储的 API 令牌和缓存的取件点列表都会被清除。
常规
Enable/Disable：一次性开启或关闭所有区域的 bpost 包裹储物柜配送。
Name：结账时显示给顾客的配送方式名称。默认：bpost parcel locker。
Tax status：Taxable 会在您的价格上加收 WooCommerce 税费，None 表示价格为最终价格。
bpost API（取件点搜索）（仅取件点选择器需要）
Account ID (public key)：您的 bpost Shipping Platform 账户的公钥，可在 plugins.bpost.be 的 Key management 中获取。
Passphrase (private key)：用于签名每个请求的私钥（HMAC-SHA256）。它从不发送给 bpost，也不写入日志。
App ID (X-APPID)：bpost 为您的集成颁发的应用标识符。它在 X-APPID 请求头中发送。
Carrier ID：您的 bpost Shipping Platform 合同中，其取件点和包裹储物柜会被列出的承运商。默认：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=PRICE，例如 BE=4.95。*=PRICE 这一行为所有其他国家设置价格，例如 *=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：仅当购物车小计（不含税）达到此金额时才显示该方式。留空则始终显示。
Excluded shipping classes：当购物车中任何商品属于这些 WooCommerce 配送类别之一时，隐藏该方式。
商品重量会从商店的重量单位换算为千克。
免运费
Free shipping：开启后，达到下方金额即免运费。
Free shipping from：购物车小计（不含税）达到此金额后免运费。仅在 Free shipping 开启时使用。
无配送区域时的可用性
Ignore shipping zones：无需添加到某个区域，即可在下方所列国家提供该方式。
Countries：该模式下的目的地国家。默认：比利时。留空则使用您配送的所有国家。此字段仅在 Ignore shipping zones 开启时使用。
高级
Debug log：在 WooCommerce > Status > Logs 中记录 API 请求和价格计算，来源为 vfd-bpost-cubee。即使此选项关闭，API 错误也始终会被记录。密钥、令牌和顾客数据绝不会被记录。
Remove data on uninstall：开启后，删除插件时会移除其设置和区域配送方式。停用插件从不删除数据。订单中保存的取件点始终保留。
结账时的工作方式
顾客输入配送地址时，WooCommerce 会向插件请求费率。插件检查条件：配送国家、购物车重量、最低订单金额和排除的配送类别。然后从国家列表中获取价格，或按包裹尺寸计算价格；在按商品计算模式下，将其乘以商品数量；如适用免运费，则将其设为零。
顾客选择 bpost 费率后，其下方会出现搜索字段、Search 按钮和取件点列表。如果搜索字段为空，将自动搜索结账地址中的邮政编码。顾客可以输入其他邮政编码或城市名称。每个取件点都会显示名称和地址。最多列出 50 个取件点。在荷兰语站点上，取件点列表以荷兰语请求；其他情况下以法语请求。
顾客必须选择一个取件点。未选择时，经典结账会显示 Please select a bpost pickup point.，区块结账则会以相同消息拒绝下单。选择结果会在结账会话期间保留，因此刷新页面不会丢失。
为列出取件点，插件仅向 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 秒。
该方式适用于经典结账，以及购物车和结账区块。它兼容 WooCommerce 高性能订单存储（HPOS）。
插件仅使用固定价格。它不会从 bpost 获取实时运费，不创建发货单、不打印运单，也不追踪包裹。取件点以列表形式显示，而非地图。请在您的 bpost Shipping Platform 或 Shipping Manager 账户中创建发货单；取件点 ID 位于订单中。
取件点
所选取件点（名称和地址）及其 ID 会保存在订单中。在后台订单页面，它显示在配送地址下方，标注为 bpost pickup point。点击 Change，搜索邮政编码或城市，并从列表中选择另一个取件点。订单会立即更新，并添加订单备注 bpost pickup point changed to: …。只有 API 密钥已填写时，Change 链接才可用。
顾客可以在感谢页面以及 My account > Orders 中看到取件点。它也会添加到订单电子邮件中，包括 HTML 和纯文本版本。
若要同时提供储物柜和送货上门，请在同一区域添加另一种配送方式，例如 Flat rate。取件点选择器只会出现在 bpost 费率下方。
许可证密钥
插件需要使用从 vibefox.net 获取的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Shipping > VibeFox bpost Cubee 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期截止日期以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从本站点移除。Manage licenses and domains in your account 链接会打开您在 vibefox.net 的账户。
一个密钥只能用于一个域名。从站点移除密钥不会释放该域名名额。请在您的 vibefox.net 账户中释放名额。
没有有效密钥时，bpost 方式不会在结账时向顾客显示。已登录的商店管理员仍可看到该方式，并标注 (unlicensed — visible to admins only)，以便您在购买密钥前完成设置和测试。插件页面和 WooCommerce 页面会显示提醒。现有订单不受影响。
许可证到期后，插件仍可继续运行，但更新和支持需要续订。系统会在后台自动再次检查状态。
故障排除
bpost 未在结账时显示：请检查许可证是否有效、Enable/Disable 是否开启，以及该方式是否已添加到顾客所在国家的区域中（或 Ignore shipping zones 已开启且该国家被允许）。检查该国家是否有价格或 *=PRICE 行，并检查重量限制、Minimum order amount 和 Excluded shipping classes。当比利时没有价格时，设置页面会显示警告。
结账时没有取件点选择器：请检查 Pickup points 是否开启，并确认 Account ID (public key)、Passphrase (private key) 和 App ID (X-APPID) 均已填写。当密钥不完整时，设置页面会显示警告。
顾客看到 "Pickup points cannot be loaded right now"：bpost 没有响应，或拒绝了密钥。原因可在 WooCommerce > Status > Logs（来源 vfd-bpost-cubee）和设置页面中查看。插件会在 5 分钟后自动重试。保存设置会立即重试。
未找到该邮政编码或城市的取件点：bpost 未针对该搜索返回任何取件点。请让顾客尝试附近的邮政编码或城市名称，并检查 Carrier ID。
带逗号的价格未被使用：5,50 和 5.50 均可接受。Country prices 中不符合 CC=PRICE 格式的行会被忽略；保存后的错误消息会列出这些行。
价格是否含税？当 Tax status 设为 Taxable 时，WooCommerce 会在您的价格上加收税费。设为 None 时，价格为最终价格。
许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在另一个域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now 为新域名激活密钥。如果无法连接许可证服务器，插件将继续使用上次已知的状态运行。
卸载
停用插件会保留所有设置；它只会清除 API 令牌和缓存的取件点列表。要删除插件，请先停用，然后在 Plugins 页面中删除。本插件的许可证密钥和许可证状态、API 令牌以及缓存始终会被删除。只有在开启了 Remove data on uninstall 的情况下，设置和区域配送方式才会被删除；否则，它们会保留，以便日后重新安装时使用。订单中的取件点属于订单历史，永远不会被删除。
bpost 是其各自所有者的商标。本插件与 bpost 无关联，也未获得 bpost 的认可或背书。