VibeFox Balikobot for OpenCart — 帮助

系统要求

OpenCart：3.0.x（已在 3.0.5.0 上测试），或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。

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 购买。一个密钥只能用于一个域名。

安装

下载文件是一个 zip 压缩包，内含适用于两个 OpenCart 版本的安装包。请解压到您的电脑上。其中包含 README.txt、OpenCart 3 安装包 vfd_balikobot-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 vfd_balikobot.ocmod.zip。请只安装与您的 OpenCart 版本对应的安装包。两个版本的许可证密钥相同。

OpenCart 3

1. 在管理后台进入 Extensions > Installer，点击 Upload，选择文件 vfd_balikobot-oc3-(version).ocmod.zip。本扩展不添加 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用 Installer，而是将本安装包中 upload 文件夹的内容复制到商店的根目录中。

2. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Balikobot，点击 Install（绿色 + 按钮）。

3. 点击 Edit（铅笔按钮）打开设置页面。

4. 将您的 VibeFox 许可证密钥粘贴到 Edit 页面顶部许可证区块的 License key 中，然后点击 Activate（参见「许可证密钥」）。

5. 输入 API 用户和 API 密钥，选择承运商和服务类型、价格来源以及各国家的运费（参见「配置」）。对于取件服务，请开启 Pickup point selection。开启 Enable/Disable 并点击 Save。

OpenCart 4

1. 在管理后台进入 Extensions > Installer，点击 Upload，选择文件 vfd_balikobot.ocmod.zip。请勿重命名该文件：OpenCart 4 会从文件名获取扩展代码，重命名后的安装包无法使用。

2. 安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。

3. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Balikobot，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。

4. 按照 OpenCart 3 的第 4 和第 5 步输入许可证密钥和设置。两个版本的设置页面及其字段相同。

安装时，扩展会为结账和订单的取件点创建一张数据表。在您开启 Enable/Disable 并保存之前，该方式保持关闭。如果您卸载后重新安装扩展，之前保留的 Balikobot 设置将再次生效。

配置

所有设置都位于扩展页面：Extensions > Extensions > Shipping > VibeFox Balikobot > Edit。各部分列在左侧。点击一次 Save 按钮即可保存整个页面，无需重新加载。保存后您会看到 Settings saved. Cached rates and pickup points were cleared. 只有拥有本扩展修改权限的管理员用户才能保存设置。

某些错误会阻止保存，此时不会保存任何内容：Name 为空或过长、Sort Order 不是整数，或税类、地理区域未知。其他问题会以警告形式显示，其余设置仍会保存：不是数字（或为负数）的值不会被保存，警告会指出对应字段；无效的 Country prices 行会被删除并列出。

可能导致该方式、实时运费或取件点被隐藏的设置，会在页面顶部显示警告：没有 API 用户或 API 密钥时的实时运费或取件点；商店货币不是 CZK 且未设置 Exchange rate；使用固定运费或回退模式时 Country prices 为空；以及商店没有 kg 单位重量等级（此时将根据单位名称读取商品重量：kg、g、lb 或 oz）。

常规

Enable/Disable: 开启或关闭结账时的 Balikobot 配送。默认：关闭。

Name: 顾客看到的配送方式名称。默认：Balikobot。必填，最多 64 个字符。

Sort Order: 该方式在配送方式列表中的位置。整数。

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: 国家和价格的列表。点击 Add row 添加一行，点击删除按钮删除一行。选择 * All other countries 可涵盖所有没有单独一行的国家。小数可使用点号或逗号。用于固定模式以及 API 回退。没有价格的国家（且没有 * 行）不会有固定运费，因此该方式对其隐藏。

Fixed price per: Order（默认）按订单收取一次运费。Item (price x quantity) 则按购物车中的商品数量相乘。这仅适用于固定运费。Balikobot 实时运费始终针对整个包裹。

Exchange rate: 1 单位 Balikobot 价格币种（通常为 CZK）折合为您商店默认货币的数值，例如 0.04。仅当 Balikobot 返回其他币种的价格时使用。留空则会拒绝此类价格，以确保顾客绝不会被收取错误的金额。

条件

Min weight (kg): 当购物车重量低于此值时隐藏该方式。0 表示不限制（默认）。商品重量会从其 OpenCart 重量等级换算。

Max weight (kg): 当购物车重量高于此值时隐藏该方式。默认：100。0 表示不限制。留空即为 100 kg。如果 Min weight (kg) 大于最大值，您会看到警告，且保留之前的重量。

Minimum order amount: 仅当购物车小计（扣除优惠券后，不含税）达到此金额时才显示该方式。留空则始终显示。

Free shipping: 开启后，在下方金额以上免运费。

Free shipping from: 购物车小计（扣除优惠券后，不含税）达到此金额时免运费。此时不会向 Balikobot 发出请求。仅在 Free shipping 开启时使用。

Tax Class: 该税类的税款会加到运费上。Balikobot 价格通常不含增值税。默认：--- None ---。

可用性

通常该方式会在此处选定的地理区域内提供（All Zones 表示所有地区）。Ignore geo zone 则改为在列表中的国家提供。

Geo Zone: 仅为该地理区域内的地址提供此方式。地理区域在 System > Localisation > Geo Zones 中管理。

Ignore geo zone: 无论地理区域如何，都在下方列出的国家提供此方式。

Countries: 该模式适用的目的国家。留空则允许所有国家。仅与 Ignore geo zone 一起使用。

取件点

Pickup point selection: 顾客必须选择取件点。适用于 Česká pošta NP 或 NB、Zásilkovna 等取件服务。需要 API 用户和 API 密钥。

Selector width: 取件点列表的 CSS 宽度，例如 100% 或 400px。默认：100%。

高级

Debug log: 将 API 请求和运费计算记录到 storage/logs/vfd_blkb_debug.log.php。该文件无法通过网页读取。API 错误始终会被记录。凭据和顾客地址永远不会被记录。使用完毕后请关闭日志。文件达到 5 MB 时会移至 vfd_blkb_debug.old.log.php，并开始新的日志。

Log: 显示日志的大小和最新条目。点击 Clear log 可清空日志。

Remove data on uninstall: 开启时，卸载扩展会删除设置、日志以及没有订单的结账取件点。关闭时（默认），设置会被保留。订单中保存的取件点始终保留。

导入 / 导出

Export: 点击 Download JSON，将设置保存为 JSON 文件。API 密钥不会被导出。

Import: 粘贴之前导出的 JSON，然后点击 Import 恢复设置，例如在另一家商店中使用。数值会像普通保存一样进行检查。已保存的 API 密钥会被保留。

结账时的工作方式

OpenCart 显示配送方式时，会向扩展请求 Balikobot 价格。如果设置了 Geo Zone（且 Ignore geo zone 关闭）且地址不在其中，则不会提供 Balikobot。开启 Ignore geo zone 时，由 Countries 列表决定。只有 Requires Shipping 设为 Yes 的商品才计入：其他商品不增加重量，也不计入订单金额。随后扩展会检查购物车重量和 Minimum order amount。订单金额是需要配送的商品价格，扣除优惠券之后、税前计算。若适用免运费，价格为 0，且不会向 Balikobot 发出请求。

在固定模式下，价格取自 Country prices。在实时模式下，扩展会向 Balikobot 发送承运商、服务类型、目的国家和邮编，以及以 kg 为单位的购物车重量。只有在配送地址有邮编时才会请求实时运费。其他币种的价格会按 Exchange rate 换算，未设置汇率则被拒绝。价格以商店的默认货币计算，按其小数位数取整，并以顾客的币种显示，同时加上所选 Tax Class 的税款。

实时价格缓存 1 小时，因此同一购物车不会触发新的请求。失败的请求缓存 5 分钟，API 超时时间为 12 秒，这样结账页面不会在每次刷新时都等待 Balikobot。API 错误绝不会显示给顾客：该方式会被隐藏，或在回退模式下使用固定运费。详细原因会记录到调试日志中。

扩展不会在 Balikobot 中创建发货单、打印面单或预约取件：请在 Balikobot 客户专区下单发货。它不跟踪包裹，也不更改订单状态。所有目的地均使用同一家承运商和同一种服务类型。取件点以下拉列表形式显示，不带地图。

在 OpenCart 4 中，顾客在结账页面的配送方式区块中点击 Choose，并在 Shipping method options 窗口中选择 Balikobot。该方式的工作方式与 OpenCart 3 相同；取件点列表见「取件点」部分。

取件点

开启 Pickup point selection 后，在 OpenCart 结账的 Delivery Method 步骤中，Balikobot 方式下方会出现取件点列表。该列表根据配送地址的国家、城市和邮编，从 Balikobot「branchlocator」加载。在地址有城市之前，顾客会看到 Enter your city to see the pickup points. 列表加载期间，顾客会看到 Loading pickup points... 列表缓存最长 12 小时。

顾客一旦选定取件点，选择就会保存。该选择是必需的：配送步骤中的 Continue 会被拒绝，并显示 Please select a pickup point. 服务器还会检查所选取件点是否属于配送地址。否则，顾客会看到 The selected pickup point is not available for your shipping address. Please choose a pickup point again. 如果此时无法连接 Balikobot，已选的取件点会被接受。如果找不到任何取件点，系统会请顾客检查城市和邮编，或改选其他配送方式。如果无法加载取件点，系统会请顾客稍后重试或改选其他配送方式。

在 OpenCart 4 中，顾客在结账页面的配送方式区块中点击 Choose。Shipping method options 窗口会在 Balikobot 方式下方显示取件点列表，文字和检查与 OpenCart 3 相同。每次打开窗口时都会加载列表，因为同一结账页面上的地址可能会变化，并且在可能时从缓存中获取。如果顾客在窗口中未选择有效取件点就点击 Continue，消息会显示在结账页面顶部，窗口保持打开。OpenCart 4 为结账保留一个订单，并在每次确认时更新它；订单的取件点也会随之更新。

所选取件点会以 - Pickup point: 的形式添加到订单的配送方式中，后面跟随其名称和地址。顾客可在账户的订单页面和订单邮件中看到，并会打印在发票上。

在管理后台订单页面（Sales > Orders、View）中，Balikobot pickup point 面板会显示取件点、其 Balikobot ID 和承运商，您在 Balikobot 中创建发货单时需要这些信息。点击 Change，在订单地址附近选择其他取件点，然后点击 Save。订单的配送方式文本也会同时更新，并显示 Pickup point updated. 修改取件点只需要订单的修改权限，无需扩展设置的访问权限。如果订单没有取件点，面板会显示 No pickup point was selected for this order. 即使 Balikobot 已关闭，该面板仍可使用：现有订单保留其取件点数据，您仍可修改取件点。

许可证密钥

本扩展需要来自 vibefox.net 的 VibeFox 许可证密钥。扩展 Extensions > Extensions > Shipping > VibeFox Balikobot > Edit 页面的第一个区块是许可证区块 License — VibeFox Balikobot，位于设置上方。将密钥粘贴到 License key 中并点击 Activate。之后，该区块会显示隐藏部分字符的密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now 用于再次检查状态，Change key 用于输入其他密钥，Remove key 用于从本商店移除密钥。其下方是 Product: opencart-shipping-balikobot 一行，以及 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 账户中释放该名额。

没有有效密钥时，结账时不会向顾客显示 Balikobot，也不会计算任何运费。在同一浏览器中登录后台的管理员用户，仍会在商店中看到该方式，并标注 (unlicensed — visible to admins only)，因此您可以在购买密钥之前进行设置和测试。在 OpenCart 4 中此预览不可用：商店无法看到后台登录状态，因此没有有效密钥时，所有人都看不到该方式。打开一次 Edit 页面后，后台的 Dashboard 上会出现提醒。点击 × 可将其关闭，7 天内不再显示。现有订单不受影响。

许可证过期后，扩展仍会继续运行，但更新和支持需要续费。当您打开后台的 Dashboard 或 Edit 页面时，状态会自动再次检查：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展时，始终会删除许可证密钥和许可证状态。

故障排除

结账时不显示 Balikobot：请检查许可证是否有效，且 Enable/Disable 已开启。阅读扩展页面顶部的警告。检查 Geo Zone（或 Ignore geo zone 和 Countries）、重量限制和 Minimum order amount。在固定模式下，检查该国家或 * All other countries 是否有价格。检查商品的 Requires Shipping 是否设为 Yes。

实时运费不显示：开启 Debug log，重新加载结账页面，然后查看扩展页面上的 Log 字段。它会显示原因：缺少 API 凭据、尚无邮编、承运商和服务的 Balikobot 错误（例如 "authorization failed: check the API user and API key"），或其他币种的价格但未设置 Exchange rate。开启 Live Balikobot rate, fixed price if the API fails 时，在您解决问题期间，顾客仍会获得固定运费。

价格币种不对：固定运费使用商店的默认货币。Balikobot 以您 Balikobot 合同的币种返回实时运费（通常为 CZK）。如果与默认货币不同，请设置 Exchange rate。

价格是否含税：Balikobot 价格通常不含增值税。选择了 Tax Class 后，OpenCart 会为运费加上税款。

列表中没有取件点：请检查 API 用户和密钥是否已设置，承运商是否支持「branchlocator」，以及配送地址是否有城市和邮编。检查日志中的 Balikobot 错误。

修改后运费或取件点看起来过时：在扩展页面点击 Save。这会清除缓存的运费和取件点。

页面显示「Warning: You do not have permission to modify VibeFox Balikobot!」：您的管理员用户组可能只有查看设置的权限。请在 System > Users > User Groups 中为该组授予 extension/shipping/vfd_balikobot（OpenCart 3）或 extension/vfd_balikobot/shipping/vfd_balikobot（OpenCart 4） 的修改权限。

开发者须知：Balikobot API 地址可通过设置 vfd_blkb_api_url（用于测试）替换；设置页面上没有对应字段。

卸载

进入 Extensions > Extensions，选择类型 Shipping，点击 VibeFox Balikobot 旁边的 Uninstall（红色 − 按钮）。本扩展的许可证密钥和许可证状态始终会被删除。OpenCart 总会重置 Enable/Disable、Sort Order、Tax Class 和 Geo Zone。缓存的运费和取件点总会被删除，取件点面板和结账列表也将停止工作。如果 Remove data on uninstall 已开启，则设置、日志以及没有订单的结账取件点也会被删除。如果关闭，其他设置会被保留，并在您重新安装扩展时再次使用。订单中保存的取件点数据永远不会被删除，现有订单的配送方式文本仍会保留取件点信息。

要在 OpenCart 4 中同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox Balikobot 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）删除已上传的安装包。

Balikobot 是其各自所有者的商标。本扩展与 Balikobot 无关联，也未获得 Balikobot 的认可。