VibeFox Bob Go for OpenCart — 帮助
要求
OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP：8.0 或更高版本。
Bob Go 账户（仅用于实时运费）：Bob Go 不使用 API 密钥。您需要一个 Bob Go 账户（bobgo.co.za），并在您的 Bob Go 账户中将店铺安装为 WooCommerce 销售渠道（Sales channels），且为该渠道启用 "Rates at checkout"。服务、价格和规则均在 Bob Go 上设置。如果您只使用固定价格，则无需 Bob Go 账户。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只适用于一个域名。
安装
下载文件为一个 zip 压缩包，内含适用于两个 OpenCart 版本的安装包。请在您的电脑上解压。其中包含 README.txt、OpenCart 3 安装包 vfd_bob_go-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 vfd_bob_go.ocmod.zip。只安装与您的 OpenCart 版本对应的安装包。两个版本使用相同的许可证密钥。
OpenCart 3
1. 在管理后台进入 Extensions > Installer，点击 Upload，选择文件 vfd_bob_go-oc3-(version).ocmod.zip。本扩展不添加任何 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装器，而是将安装包中 upload 文件夹的内容复制到店铺的根目录。
2. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Bob Go，点击 Install（绿色 + 按钮）。
3. 点击 Edit（铅笔按钮）打开设置页面。
4. 在 Edit 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入 License key，然后点击 Activate（见许可证密钥）。
5. 在您的 Bob Go 账户中，将店铺安装为销售渠道。为该渠道启用 "Rates at checkout"，并设置您的服务和价格。
6. 在 Edit 页面检查店铺域名、发货地址（发货地点），以及如果店铺货币不是 ZAR，还需检查 ZAR 汇率（见配置）。开启 Enable Bob Go，然后点击 Save。
OpenCart 4
1. 在管理后台进入 Extensions > Installer，点击 Upload，选择文件 vfd_bob_go.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包无法使用。
2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。
3. 进入 Extensions > Extensions，选择类型 Shipping。找到 VibeFox Bob Go，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。
4. 设置 Bob Go，按照 OpenCart 3 第 4 至 6 步的方法输入许可证密钥和设置。两个版本的设置页面及其字段相同。
安装后，该配送方式处于关闭状态，直到您开启 Enable Bob Go 并保存。默认使用 Bob Go 的实时运费。如果您卸载后重新安装本扩展，之前保留的 Bob Go 设置会再次生效。
配置
所有设置都位于扩展页面：Extensions > Extensions > Shipping > VibeFox Bob Go > Edit。各部分列在左侧。点击一次 Save 按钮即可保存整个页面，无需重新加载。每次保存还会清除已缓存的 Bob Go 运费。数字可使用小数点或逗号作为小数分隔符。如果某个值有误，则不会保存任何内容，页面会显示原因：Method title 为空或超过 64 个字符，某个值不是数字（"…" must be a number.），金额或重量为负数（"…" must be a number of 0 or more.），ZAR conversion rate 小于或等于 0，Minimum weight (kg) 大于 Maximum weight (kg)，或者税类或地理区域未知。只有拥有本扩展修改权限的管理员用户才能保存设置。
在设置上方，如果实时运费无法工作，页面会发出警告：Live rates are not requested: your store currency is … — set the "ZAR conversion rate".，当您的店铺中没有南非的地区（省份）时，或者店铺中没有单位为 "kg" 的重量类别或单位为 "cm" 的长度类别时。在最后这种情况下，重量和尺寸将按其类别的单位名称换算（kg、g、lb、oz；cm、mm、m、in），其他单位则按 kg 或 cm 读取。
通用
这些设置适用于每个地理区域。结账时，每项 Bob Go 服务都是配送方式名称下的独立配送选项。
Enable Bob Go：在结账时显示或隐藏 Bob Go。默认：关闭。
Method title：顾客看到的配送方式名称。Bob Go 服务（例如 "The Courier Guy - Economy"）会以 Bob Go 中的名称列在其下方。默认：Bob Go。必填，最多 64 个字符。
Shipping cost：价格的计算方式。
缺少实时运费的原因会写入日志，绝不会显示给顾客。
Sort order：Bob Go 在结账时配送方式列表中的位置。整数。
Bob Go 账户
本部分说明您在 Bob Go 上需要做什么，并附有 Bob Go 账户、Sales channels 和 Rates at checkout 的链接。它还会显示 Bob Go 针对您的店铺域名的最后一次响应：connected、the WooCommerce channel is not installed on Bob Go (HTTP 404)、"Rates at checkout" is not enabled for this channel（HTTP 401 或 403），或者 request failed 加上错误代码，或 no connection。
Store domain：Bob Go 通过域名识别您的店铺。留空则使用您的店铺域名，该域名显示在字段说明中。只有当您在 Bob Go 上的渠道安装在其他地址时，才需输入其他域名，例如子文件夹中的店铺可填 example.co.za/shop。协议前缀和末尾的斜杠会被移除。
ZAR conversion rate：Bob Go 以南非兰特（ZAR）报价。如果您的店铺默认货币不是 ZAR，请输入 1 ZAR 等于多少您的货币，例如 0.05。运费将按此汇率换算，商品价格会以 ZAR 发送给 Bob Go。若要不在您的货币中使用 Bob Go 实时运费，请留空（固定价格仍然有效）。汇率必须大于 0。如果您的店铺货币是 ZAR，请留空。
Delivery dates：在结账时，在每项服务旁显示 Bob Go 提供的预计送达日期范围。该估算总会与订单一同保存，并在订单页面可见。
发货地址（始发地址）
每次运费请求都会将始发地址发送给 Bob Go。OpenCart 中的店铺地址为自由文本，因此只使用店铺的国家和地区（System > Settings > Store > Local）：如果店铺所在国家即为始发国家，则从店铺地区获取空缺的省份。请在此输入城市、邮政编码和街道。
Origin country：您发货所在的国家。默认：South Africa。Bob Go 仅在南非境内配送。
Origin province：一个南非省份，或 Store region (if in South Africa)。
Origin city / suburb：您发货所在的城市或郊区，例如 Johannesburg。
Origin postal code：您发货所在的邮政编码，例如 2001。
Origin street address：您发货所在的街道地址，例如 123 Main Street。
固定价格（当 Shipping cost 为 Fixed prices (below) 时使用，并且在 Bob Go 未返回运费时作为备用）
Price per country：每个国家一行：2 位国家代码、等号以及店铺默认货币的价格（不含税），例如 ZA=99.99。使用 * 表示其他所有国家，例如在下一行填写 *=199.99。格式不同的行在保存时会被删除，页面会在警告中列出这些行。
Flat price：上面没有对应行的国家所使用的价格。留空则对这些国家隐藏该配送方式。
Fixed price applies：Per order（默认）只收取一次价格。Per item (price × quantity) 则将价格乘以购物车中的商品数量。Bob Go 实时运费始终针对整个发货。
条件
Minimum weight (kg)：购物车重量低于此值时隐藏该配送方式。0 表示不限制（默认）。
Maximum weight (kg)：购物车重量高于此值时隐藏该配送方式。0 表示不限制（默认）。
Minimum order amount：仅当需要配送的商品小计（使用优惠券后，未含税）达到此金额时才显示该配送方式。留空则始终显示。
Free shipping：达到下方的订单金额时开启免运费。
Free shipping from：需要配送的商品小计（使用优惠券后，未含税），达到此金额即免运费。仅在 Free shipping 开启时使用。此时不会向 Bob Go 请求运费。
Tax class：运费的税类，或 No tax（默认）。Bob Go 的运费通常已包含增值税。在这种情况下请保持 No tax，以免对运费重复征税。
Geo zone：仅向此地理区域内的地址提供 Bob Go。All zones（默认）表示不限制。当 Ignore shipping zones 开启时不使用。地理区域在 System > Localisation > Geo Zones 中管理。
无配送区域时的可用性
Ignore shipping zones：开启时，不检查地理区域，并会对下方列出的国家提供该配送方式。
Countries：该模式下的目的地国家。留空则允许所有国家。仅在 Ignore shipping zones 开启时使用。
高级
Debug log：将运费计算和 Bob Go 请求写入 storage/logs/vfd_bobg_debug.log.php。该文件无法通过网页读取。顾客地址不会被记录。即使此选项关闭，Bob Go 错误仍会被记录。完成后请关闭日志。当文件达到 5 MB 时，它会被移动到 vfd_bobg_debug.old.log.php，并开始新的日志。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Remove data on uninstall：开启时，卸载扩展会删除 Bob Go 设置、已缓存的运费和日志。随订单保存的 Bob Go 服务会保留。关闭时（默认），所有内容都会保留，以便重新安装。
导入 / 导出
Export：点击 Download JSON，将设置保存为 JSON 文件。
Import：粘贴之前导出的 JSON，然后点击 Import，即可恢复设置，例如在另一家店铺中使用。这些值会像正常保存时一样进行检查。
结账时的工作方式
当 OpenCart 显示配送方式时，它会向扩展请求 Bob Go 运费。如果设置了 Geo zone（且 Ignore shipping zones 关闭），并且地址不在该区域内，则不会提供 Bob Go。只有 Requires Shipping 设为 Yes 的商品才会计算在内：其他商品不增加重量，也不计入订单金额。然后扩展检查目的地国家（若启用了 Ignore shipping zones）、购物车重量以及 Minimum order amount。订单金额是需要配送的商品价格，即使用优惠券折扣后、未含税的金额。礼品卡、奖励积分和店铺余额不计入在内。如果适用免运费，顾客会看到 Bob Go (free)（即您的 Method title），并且不会向 Bob Go 发送任何请求。
在实时运费模式下，扩展会向 Bob Go 发送您的店铺域名、始发和收货地址（含省份）以及购物车商品：以 ZAR 计的商品价格、重量和尺寸，以及作为 SKU 的商品型号。对于南非地址，OpenCart 地区会以省份代码发送（EC、FS、GP、KZN、LP、MP、NC、NW、WC）。只有在顾客输入城市或邮政编码之后，才会请求实时运费。当您店铺的货币不是 ZAR 时，ZAR 运费会按 ZAR conversion rate 换算。价格以您的默认货币计算，按其小数位数取整，并以顾客的货币显示，同时包含所选 Tax class 的税款。
在配送方式名称下，顾客会看到每项 Bob Go 服务对应的一个选项，包括其名称、价格，以及（若 Delivery dates 已开启）括号中的预计送达日期。顾客可像选择其他 OpenCart 配送选项一样选择某项服务。若使用固定价格，则只有一个带有配送方式名称的选项。
在 OpenCart 4 中，顾客在结账页面的配送方式区块中点击 Choose，并在 Shipping method options 窗口中选择一项 Bob Go 服务，例如 SkyNet - Overnight (by 17/10/2026)（附带其价格）。该方式的工作方式与 OpenCart 3 相同。
运费按每次完整请求缓存 1 小时，因此同一购物车不会再次触发新请求。失败的请求缓存 5 分钟，超时时间为 12 秒，因此 Bob Go 故障不会拖慢每次结账更新。请求失败绝不会中断结账：该配送方式会被隐藏，或在备用模式下使用固定价格。原因会写入日志。
本扩展仅显示运费。它不会创建发货单、运单或面单，不跟踪包裹，不与 Bob Go 同步订单，也不发送通知。请使用 Bob Go 控制台进行配送处理。它没有自提点或智能柜选择。Bob Go 仅在南非境内配送。
订单
所选服务名称会成为订单的配送方式，因此它会出现在订单邮件、Sales > Orders 以及顾客账户中。下单时，Bob Go 服务、其代码和配送预估也会随订单一起保存。之后对购物车或 Bob Go 价格的更改不会改变这些内容。在 OpenCart 4 中，结账只保留一个订单：如果顾客返回并使用另一项 Bob Go 服务再次确认订单，则已保存的服务会被更新；如果改用其他配送方式或固定价格，则该服务会被移除。
在管理后台，Sales > Orders 中的订单页面会显示一个 Bob Go 区块，包含 Bob Go service（名称和代码）以及 Estimated delivery。顾客在其账户的订单详情页面可以看到 Bob Go service 和 Estimated delivery。采用固定价格或免运费的订单没有 Bob Go 服务。
许可证密钥
本扩展需要一个来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox Bob Go 许可证区块位于 Extensions > Extensions > Shipping > VibeFox Bob Go > Edit 页面中设置的上方，是第一个区块。请将密钥输入 License key，然后点击 Activate。之后，该区块会显示被遮盖的密钥、状态（例如许可证的有效截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺移除该密钥）。其下方是 Product: opencart-shipping-bob-go 一行和 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 账户中释放该名额。
没有有效密钥时，Bob Go 不会在结账时显示给顾客，也不会计算任何运费。在同一浏览器中已登录后台的管理员用户，仍会在店铺中看到该方式，并标注 (unlicensed — visible to admins only)，以便您在购买密钥之前设置和测试本扩展。在 OpenCart 4 中，此预览不可用：店铺看不到后台登录状态，因此没有有效密钥时，该方式对所有人都隐藏。打开一次 Edit 页面后，后台 Dashboard 上会出现提醒。点击 × 可将其关闭，关闭后 7 天内不再显示。现有订单不受影响。
许可证到期后，扩展仍会继续运行，但更新和支持需要续费。当您打开后台 Dashboard 或 Edit 页面时，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载扩展时，始终会移除许可证密钥和许可证状态。
故障排除
Bob Go 未出现在结账页面：检查许可证是否有效以及 Enable Bob Go 是否开启。检查 Geo zone，或开启 Ignore shipping zones 并检查 Countries。检查重量限制和 Minimum order amount。在固定价格模式下，检查国家、* 或 Flat price 是否有价格。检查商品的 Requires Shipping 是否设为 Yes。
未显示 Bob Go 运费：打开扩展页面。Bob Go 账户部分显示 Bob Go 的最后一次响应。"The WooCommerce channel is not installed on Bob Go"（HTTP 404）表示店铺域名不是 Bob Go 上的销售渠道：请检查 Store domain。"Rates at checkout is not enabled"（HTTP 401）表示该渠道未开启此功能。同时确保顾客已输入城市或邮政编码，并且对于非 ZAR 店铺已设置 ZAR conversion rate。开启 Debug log，重新加载结账页面，然后查看 Log 字段。使用 Bob Go live rates, fixed prices if Bob Go returns no rates 时，在您修复问题期间，顾客仍会获得固定价格。
我的店铺不使用兰特：Bob Go 以 ZAR 报价。请输入 1 ZAR 等于多少您店铺的货币。若无此值，扩展不会向 Bob Go 请求运费。固定价格仍然有效。
页面提示南非没有地区：请在 System > Localisation > Zones 中添加南非的省份，否则 Bob Go 无法为南非地址获取省份。
运费被重复征税：Bob Go 运费通常已包含增值税。将 Tax class 设为 No tax。
更改后运费似乎过时：在扩展页面点击 Save。这会清除已缓存的 Bob Go 运费。您在 Bob Go 账户中的更改会在 1 小时缓存之后或保存设置时生效。
页面显示 "Warning: You do not have permission to modify VibeFox Bob Go!"：您的管理员用户组可能只能查看设置。请在 System > Users > User Groups 中为该组授予 extension/shipping/vfd_bob_go（OpenCart 3）或 extension/vfd_bob_go/shipping/vfd_bob_go（OpenCart 4）的修改权限。
开发人员：Bob Go API 地址可通过设置 vfd_bobg_api_url（用于测试）替换；设置页面中没有对应字段。
卸载
进入 Extensions > Extensions，选择类型 Shipping，然后点击 VibeFox Bob Go 旁边的 Uninstall（红色 − 按钮）。本扩展的许可证密钥和许可证状态总会被删除。OpenCart 总会重置 Enable Bob Go、Sort order、Tax class 和 Geo zone。已缓存的运费总会被删除。如果开启了 Remove data on uninstall，Bob Go 设置和日志也会被删除。如果关闭，其他设置会保留，并在您重新安装扩展时再次使用。随订单保存的 Bob Go 服务始终保留，现有订单保留其配送方式和费用。
在 OpenCart 4 中，要同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox Bob Go 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）删除已上传的安装包。
Bob Go 是其各自所有者的商标。本扩展与 Bob Go 无关联，也未获得 Bob Go 的认可或背书。