VibeFox Balikobot for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝在较旧的 PHP 版本上安装。
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. 在后台依次进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或之后在模块列表中找到 VibeFox Balikobot 并点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥粘贴到 License key 中，然后点击 Activate（参见许可证密钥）。
4. 输入 API 用户和 API 密钥，选择承运商和服务类型、价格来源以及各国价格（参见配置）。对于取件点服务，请开启 Pickup point selection。点击 Save。
安装时，模块会创建 Balikobot 承运商，其配送时间文字为 Delivery by Balikobot。该承运商会分配给捷克、斯洛伐克和匈牙利的区域以及所有客户组。您可以在 Shipping > Carriers 中更改区域、客户组、配送时间、徽标和尺寸限制。请勿在该处设置价格：价格始终来自模块。
配置
所有设置都在模块页面中：Modules > Module Manager > VibeFox Balikobot > Configure。每个部分都有各自的 Save 按钮，点击后将保存整个页面。保存后，您会看到 Settings saved. Cached rates and pickup points were cleared. 页面顶部会显示警告，提示哪些设置会隐藏承运商、实时运费或取件点：没有 API 用户或 API 密钥却使用实时运费或取件点；商店货币不是 CZK 却未填写 Exchange rate；使用固定价格或回退模式时 Country prices 为空；商店的重量单位模块无法识别（此时重量按千克读取；请使用 kg、g、lb 或 oz）；以及承运商已被删除。非数字的值不会被保存，您会看到一条带有字段名称的警告。
General
Enable/Disable：开启或关闭 Balikobot 配送。这与 Shipping > Carriers 中的承运商状态是同一个开关。
Name：向客户显示的配送方式名称（即承运商名称）。默认值：Balikobot。必填，最多 64 个字符。
Tax status：None，或 Taxable 并选择您的一条税务规则。选择税务规则后，其税额会加到配送价格上。该选择会保存到承运商。Balikobot 的价格通常不含增值税。默认值：None。
Balikobot API 账户（实时运费和取件点需要）
API user：您在客户专区中的 Balikobot API 用户。
API key：您在客户专区中的 Balikobot API 密钥。保存后，该字段保持为空，并显示 Saved - leave empty to keep it. Clear the API user to remove the saved key. 只有在需要更改时才输入新值。
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）和价格的表格。点击 Add row 添加国家，点击垃圾桶图标删除。使用 * 作为国家代码，可涵盖所有其他国家。小数可使用点或逗号。在固定模式下使用，也用作 API 的回退价格。没有价格的国家（且没有 * 行）不会有固定运费。保存时会删除无效行，并通过警告列出这些行。
Fixed price per：Order 表示按订单收取一次价格。Item (price x quantity) 表示按购物车中的商品数量相乘。这仅适用于固定价格。Balikobot 实时运费始终针对整个包裹。
Exchange rate：1 个 Balikobot 价格货币单位（通常为 CZK）折合为您商店默认货币的数值，例如 0.04。仅当 Balikobot 返回的价格使用其他货币时才会使用。留空则拒绝此类价格，确保客户绝不会被收取错误的价格。
条件
Min weight (kg)：购物车低于此重量时隐藏承运商。0 表示无限制。商品重量会从您商店的重量单位换算。
Max weight (kg)：购物车高于此重量时隐藏承运商。默认值：100。0 表示无限制。留空即表示 100 kg。如果 Min weight (kg) 大于最大值，您会看到警告，之前的重量设置将保留。
Minimum order amount：仅当购物车小计（折扣后、不含税）达到此金额时才显示承运商。留空则始终显示。
Free shipping：开启下方金额起的免运费。
Free shipping from：购物车小计（折扣后、不含税）达到此金额时免运费。在这种情况下不会向 API 发出请求。
无配送区域时的可用性
通常情况下，承运商仅在 Shipping > Carriers 中为其所属区域提供服务。
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 请求和运费计算记录到模块文件夹中的 logs/vfd_blkb_debug.log.php。该文件无法通过网页打开。API 错误始终会被记录。凭据和客户地址绝不会被记录。完成后请关闭日志。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Remove data on uninstall：开启后，卸载模块将删除模块设置和承运商。不开启此选项时，卸载不会删除任何数据。订单中保存的取件点会保留。
结账时的运作方式
在配送步骤中，PrestaShop 会向模块请求 Balikobot 价格。仅实体商品计入：虚拟商品不增加重量，也不计入订单金额。模块会先检查国家（启用 Ignore shipping zones 时）、购物车重量和 Minimum order amount。如果适用免运费，则价格为 0，并且不会向 Balikobot 发送请求。
在固定模式下，价格取自 Country prices。在实时模式下，模块会向 Balikobot 发送承运商、服务类型、目的国家和邮政编码以及以千克计的购物车重量。只有配送地址包含邮政编码时才会请求实时运费。其他货币的价格会按 Exchange rate 换算；如果未设置汇率，则拒绝该价格。价格以您商店的默认货币计算，然后以客户购物车的货币显示。
实时价格缓存 1 小时，因此同一购物车不会重复发出请求。失败的请求缓存 5 分钟，API 超时时间为 12 秒，使结账在每次刷新时都不必等待 Balikobot。API 错误绝不会显示给客户：承运商会被隐藏，或在回退模式下使用固定价格。详细信息会写入调试日志。
如果您在承运商已有订单后，在 Shipping > Carriers 中编辑该承运商，PrestaShop 会将其保存为承运商的新版本。模块会自动跟随新版本。
模块不会在 Balikobot 中创建运单、打印面单或预约取件：请在 Balikobot 客户专区下单发货。它不跟踪包裹，也不更新订单状态。所有区域都使用一个承运商和一种服务类型。取件点以下拉列表形式显示，没有地图。
取件点
开启 Pickup point selection 后，在配送步骤中，Balikobot 承运商下方会出现取件点列表。该列表根据配送地址的国家、城市和邮政编码，从 Balikobot "branchlocator" 加载。在地址填写城市之前，客户会看到 Enter your city to see the pickup points. 列表缓存 12 小时。
客户一旦选择取件点，该选择就会保存到购物车中。取件点为必选项：配送步骤中的 Continue 和 Place order 会被阻止，并显示 Please select a pickup point. 服务器还会检查所选取件点是否属于配送地址。否则，客户会看到 The selected pickup point is not available for your shipping address. Please choose a pickup point again. 如果找不到任何取件点，系统会请客户检查城市和邮政编码，或选择其他配送方式。如果无法加载取件点，系统会请客户稍后重试，或选择其他配送方式。
所选取件点会保存在订单中。在后台订单页面的 Balikobot pickup point 区块中会显示该取件点，包括 Balikobot 网点 ID 和承运商，您在 Balikobot 中创建运单时需要这些信息。点击 Change 可选择订单地址附近的其他取件点，然后点击 Save。更改取件点只需要编辑订单的权限，不需要访问模块页面。如果订单没有取件点，该区块会显示 No pickup point was selected for this order.
客户会在订单确认页面和订单详情中看到 Pickup point: 取件点信息。在订单确认邮件以及商店的新订单邮件（Mail alerts 模块）中，它会添加在承运商名称之后。现有订单保留其取件点数据。
许可证密钥
该模块需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Balikobot 位于 Modules > Module Manager > VibeFox Balikobot > Configure 页面中设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以隐藏方式显示密钥、许可证状态（例如许可证有效期截止日期以及您的域名），并提供以下按钮：Check now 用于重新检查状态，Change key 用于输入其他密钥，Remove key 用于从本商店移除密钥。其下方是 Product: presta-shipping-balikobot 一行，以及 Manage licenses and domains in your account 链接，该链接会打开您的 vibefox.net 账户。只有拥有该模块 Configure 权限的员工才能更改密钥。该区块的文字跟随后台语言（包括英语和俄语）。
如果密钥未被接受，该区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或 License expired on 加上日期。商店地址更改后，或在您的账户中释放了域名名额后，请点击 Check now。如果无法连接许可证服务器，模块将继续使用最后已知的状态运行。
一个密钥对应一个域名：即主商店的域名，多店铺设置中同样如此。从商店中移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
如果没有有效的密钥，Balikobot 承运商不会在结账时显示给客户，也不会计算任何运费。PrestaShop 前台无法得知您已登录后台，因此该承运商对您也会被隐藏：您可以在购买密钥之前设置模块，但无法在结账时进行测试。Modules > Module Manager 中的 Alerts 选项卡会显示提醒。现有订单不受影响。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。在您使用后台期间，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时没有显示 Balikobot：请检查许可证是否有效，以及 Enable/Disable 是否已开启。阅读模块页面顶部的警告。在 Shipping > Carriers 中，检查承运商是否覆盖客户所在国家的区域和客户组，或者开启 Ignore shipping zones 并检查 Countries。检查重量限制和 Minimum order amount。在固定模式下，检查该国家或 * 是否有价格。商品也可能在商品页面中被限制为特定承运商。
实时运费不显示：开启 Debug log，重新加载结账页面，并查看模块页面上的 Log 字段。该字段会显示原因：缺少 API 凭据、尚无邮政编码、承运商和服务的 Balikobot 错误（例如 authorization failed，请检查 API 用户和 API 密钥），或未设置 Exchange rate 时出现其他货币的价格。在您解决问题期间，启用 Live Balikobot rate, fixed price if the API fails 可让客户仍然看到固定价格。
价格货币错误：固定价格以您商店的默认货币计。Balikobot 以您 Balikobot 合同的货币返回实时价格（通常为 CZK）。如果该货币与默认货币不同，请设置 Exchange rate。
价格是否含税：Balikobot 的价格通常不含增值税。将 Tax status 设置为某条税务规则后，PrestaShop 会为配送加上税费。
列表中没有取件点：请检查是否已设置 API 用户和密钥，承运商是否支持 "branchlocator"，以及配送地址是否包含城市和邮政编码。查看日志中的 Balikobot 错误。
更改后运费或取件点看起来过时：在模块页面点击 Save。这会清除缓存的运费和取件点。
页面提示未找到 Balikobot 承运商：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块，以重新创建该承运商。
面向开发者：模块提供了自己的钩子，用于更改 API 地址（actionVfdBlkbApiUrl）、"transportcosts" 包（actionVfdBlkbTransportcostsPackage）以及取件点数量（actionVfdBlkbPickupMaxResults，默认 30）。
卸载
进入 Modules > Module Manager，打开 VibeFox Balikobot 旁边的菜单，然后选择 Uninstall。许可证密钥、许可证状态、缓存的运费和取件点始终会被删除。如果开启了 Remove data on uninstall，承运商会被删除（订单保留其历史记录），并且设置、日志以及没有订单的购物车中的取件点都会被删除。如果未开启，则只会停用承运商，所有设置都会保留。重新安装模块（或重置）后，已保存的承运商会恢复卸载前的状态：开启的保持开启，关闭的保持关闭。订单中保存的取件点数据永远不会被删除。
Balikobot 是其各自所有者的商标。本模块与 Balikobot 没有关联，也未获得 Balikobot 的认可。