VibeFox Balikobot for WooCommerce — 帮助
系统要求
WordPress：5.8 或更高版本。
WooCommerce：7.0 或更高版本，已安装并启用。未安装时插件无法激活。
PHP：8.0 或更高版本。
Balikobot 账户（用于实时运费和取件点）：您需要一个具有 API 访问权限的 Balikobot 账户。API 用户和 API 密钥位于 Balikobot 客户专区（client.balikobot.cz）。Balikobot 支持团队（podpora@balikobot.cz）会为您的账户和承运商开通 API。实时运费需要 Balikobot 支持 "transportcosts" 的承运商和服务。取件点需要支持 "branchlocator" 的承运商（例如 Česká pošta、Zásilkovna、PPL、DPD、GLS）。如不确定，请咨询 Balikobot 支持团队。固定价格无需账户即可使用。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 vfd_balikobot 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Shipping > VibeFox Balikobot，或在插件页面中点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 输入 API 用户和 API 密钥，选择承运商、服务类型、价格来源以及各国价格（参见“配置”）。对于取件服务，请开启 Pickup point selection。
6. 在 WooCommerce > Settings > Shipping > Shipping zones 中，将 VibeFox Balikobot 添加到配送区域（例如捷克），或开启 Ignore shipping zones 并选择国家。
配置
所有设置都位于同一页面：WooCommerce > Settings > Shipping > VibeFox Balikobot。这些设置适用于所有配送区域。页面顶部会显示警告，提示哪些设置可能导致该方式、实时运费或取件点被隐藏。每次保存设置时，缓存的运费和取件点都会被清除。将该方式添加到区域时，区域窗口只有一个字段：
Title (zone)：该区域中向客户显示的配送方式名称。留空则使用全局的 Name。
常规
Enable/Disable：一次性在所有区域中启用或禁用 Balikobot 配送。
Name：向客户显示的配送方式名称。区域可以用自己的 Title 覆盖它。默认：Balikobot。
Tax status：Taxable 表示 WooCommerce 会在价格之上另加配送税费；None 表示不加。Balikobot 价格通常不含增值税。
Balikobot API 账户（实时运费和取件点需要）
API user：您在客户专区中的 Balikobot API 用户。
API key：您在客户专区中的 Balikobot API 密钥。
Carrier：用于运费和取件点的 Balikobot 承运商：Česká pošta（默认）、Zásilkovna（Packeta）、PPL、DPD、GLS、DHL Express、UPS、TNT、FedEx、Geis、InTime、Uloženka、Toptrans、Pošta bez hranic、Slovenská pošta、SPS（Slovak Parcel Service）或 Magyar Posta。该承运商必须已在您的 Balikobot 账户中启用。
Service type：承运商的 Balikobot 服务代码。默认：NP。对于 Česká pošta：NP = 寄往邮局的包裹，NB = 寄往 Balíkovna 的包裹，DR = 送货上门。其他承运商的代码列在 Balikobot 客户专区和 API 文档中。
价格（所有价格均以您的商店货币计）
Price source：价格的计算方式。
Country prices：每个目的国家的固定价格（2 位字母代码，例如 CZ、SK）。所有其他国家请使用 *。可使用点或逗号作为小数点。用于固定模式，以及作为 API 失败时的备用价格。没有价格的国家（且没有 * 行）不会获得固定运费。
Fixed price per：Order 只收取一次价格。Item (price × quantity) 按购物车中的商品数量相乘。这仅适用于固定价格。Balikobot 实时运费始终针对整个包裹。
Exchange rate：Balikobot 价格货币（通常为 CZK）1 个单位相当于您商店货币的数值，例如 0.04。仅在 Balikobot 返回其他货币的价格时使用。留空则拒绝此类价格，从而确保客户永远不会被收取错误的价格。
条件
Min weight (kg)：购物车低于此重量时隐藏该方式。0 表示无限制。商品重量会从您商店的重量单位换算。
Max weight (kg)：购物车高于此重量时隐藏该方式。默认：100。0 表示无限制。
Minimum order amount：仅当购物车小计（扣除折扣后、不含税）达到此金额时才显示该方式。留空则始终显示。
Excluded shipping classes：如果购物车包含这些 WooCommerce 配送类别中任一类别的商品，则隐藏该方式。
Free shipping：开启以下金额起的免运费。
Free shipping from：购物车小计（扣除折扣后、不含税）达到此金额时免运费。在这种情况下不会向 API 发送请求。
无配送区域时的可用性
Ignore shipping zones：即使未将该方式添加到对应区域，也会在以下国家提供该方式。
Countries：该模式的目的国家。留空则使用您配送的所有国家。仅在开启 Ignore shipping zones 时使用。
取件点
Pickup point selection：客户必须选择一个取件点。用于取件类服务，例如 Česká pošta NP 或 NB，或 Zásilkovna。需要 API 用户和 API 密钥。
Selector width：取件点列表的 CSS 宽度，例如 100% 或 400px。默认：100%。
高级
Debug log：将 API 请求和运费计算记录到 WooCommerce > Status > Logs，来源为 "vfd-balikobot"。API 错误始终会被记录。凭据和客户地址永远不会被记录。
Remove data on uninstall：开启后，删除插件会移除其设置和区域方式。停用插件永远不会删除数据。订单中保存的取件点会保留。
结账时的工作方式
当客户输入配送地址时，插件会检查购物车重量、Minimum order amount 和 Excluded shipping classes。如果适用免运费，运费为 0，且不会向 Balikobot 发送任何请求。
在固定模式下，价格取自 Country prices。在实时模式下，插件会向 Balikobot 发送承运商、服务类型、目的国家和邮政编码，以及以千克为单位的购物车重量。只有客户输入邮政编码之后才会请求实时运费。其他货币的价格会按 Exchange rate 换算，若未设置汇率则会被拒绝。
实时价格缓存 1 小时，因此同一购物车不会触发新的请求。失败的请求缓存 5 分钟，API 超时时间为 12 秒，这样结账页面不会在每次刷新时都等待 Balikobot。API 错误绝不会显示给客户：该方式会被隐藏，或在备用模式下使用固定价格。详细信息会记录到日志中。
该方式适用于经典结账以及购物车和结账区块。它兼容 WooCommerce 高性能订单存储（HPOS）。
插件不会在 Balikobot 中创建运单、打印面单或预约取件：请在 Balikobot 客户专区中下单发货。它不跟踪包裹，也不更新订单状态。所有区域使用同一个承运商和服务类型。取件点以下拉列表形式显示，没有地图。
取件点
开启 Pickup point selection 后，在结账页面的 Balikobot 选项下方会显示取件点列表，经典结账和区块结账均如此。列表根据客户的国家、城市和邮政编码，从 Balikobot "branchlocator" 加载。在输入城市和邮政编码之前，客户会看到 Enter your city and postcode to see the pickup points. 列表缓存 12 小时。
必须选择：客户会看到 Please select a pickup point. 服务器还会检查所选取件点是否属于配送地址。地址更改后，系统会要求客户重新选择取件点。如果无法加载取件点，系统会提示客户稍后重试或选择其他配送方式。
所选取件点会保存到订单中。在管理员订单页面，它显示在配送地址下方，标签为 Balikobot pickup point，并附有 Balikobot 网点 ID 和承运商，这些信息在您于 Balikobot 中创建运单时需要。点击 Change 可选择订单地址附近的其他取件点。客户在订单页面和订单邮件（HTML 与纯文本）中会看到该取件点，标签为 Pickup point。现有订单保留其取件点数据。
许可证密钥
本插件需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Shipping > VibeFox Balikobot 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期截止日期以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从本站点移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥不会释放域名名额，请在 vibefox.net 账户中释放名额。
没有有效密钥时，结账页面不会向客户显示 Balikobot。已登录的商店管理人员仍可看到它，并标注 (unlicensed — visible to admins only)，方便您在购买密钥之前设置和测试插件。插件页面和 WooCommerce 页面会显示提醒。现有订单不受影响。
许可证过期后，插件仍可继续运行，但更新和支持需要续费。系统会在后台自动重新检查状态。
故障排除
结账时不显示 Balikobot：检查许可证是否有效、Enable/Disable 是否已开启、该方式是否已添加到客户所在国家的区域（或已开启 Ignore shipping zones 且该国家被允许）。阅读设置页面顶部的警告。检查重量限制、Minimum order amount 和 Excluded shipping classes。在固定模式下，检查该国家或 * 是否设置了价格。
实时运费不显示：开启 Debug log，刷新结账页面，然后打开 WooCommerce > Status > Logs（来源 "vfd-balikobot"）。日志会显示原因：缺少 API 凭据、尚未输入邮政编码、承运商和服务的 Balikobot 错误，或未设置 Exchange rate 时出现其他货币的价格。使用 Live Balikobot rate, fixed price if the API fails 时，在您解决问题期间，客户仍会获得固定价格。
价格货币错误：固定价格以您的商店货币计。Balikobot 返回的实时价格使用您 Balikobot 合同的货币（通常为 CZK）。如果与商店货币不同，请设置 Exchange rate。
是否包含增值税？Balikobot 价格通常不含增值税。将 Tax status 设为 Taxable 后，WooCommerce 会添加配送税费。
列表中没有取件点：检查是否已填写 API 用户和密钥、承运商是否支持 "branchlocator"，以及客户是否已输入城市和邮政编码。查看日志中的 Balikobot 错误。
修改后运费或取件点看起来过时：保存设置页面。这会清除缓存的运费和取件点。
许可证区块显示错误：按照区块中的提示操作。例如，如果该密钥已在其他域名上使用，请在 vibefox.net 账户中释放名额并点击 Check now。如果站点地址已更改，请点击 Check now 为新域名激活密钥。如果无法连接许可证服务器，插件将按照最后已知的状态继续运行。
卸载
停用插件会保留所有设置，仅清除缓存。要移除插件，请先停用，然后在 Plugins 页面删除。本插件的许可证密钥和许可证状态，以及缓存的运费和取件点，始终会被删除。只有在 Remove data on uninstall 已开启时，设置和区域方式才会被删除；否则它们会保留，供以后重新安装时使用。订单中保存的取件点数据永远不会被删除。
Balikobot 是其各自所有者的商标。本插件与 Balikobot 没有关联，也未获得其认可。