VibeFox Instabee for OpenCart — 帮助
系统要求
OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP：8.0 或更高版本。
Budbee API 凭据（仅用于包裹柜选择）：一个 API 密钥和一个 API 密文。Instabee 会将其发放给签订配送协议的商家。请联系您的 Instabee 联系人，或使用 Instabee 商家门户。API 文档位于 developer.budbee.com。没有凭据时，该配送方式仍可按固定运费工作，但顾客无法选择包裹柜。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只适用于一个域名。
安装
下载文件是一个 zip 压缩包，内含两个 OpenCart 版本的安装包。请先解压到您的电脑上。其中包含 README.txt、OpenCart 3 安装包 vfd_instabee-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 vfd_instabee.ocmod.zip。只安装与您的 OpenCart 版本相符的安装包。两个版本使用相同的许可证密钥。
OpenCart 3
1. 在后台进入 Extensions > Installer，点击 Upload，选择文件 vfd_instabee-oc3-(version).ocmod.zip。本扩展不添加任何 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装器，直接将本安装包中 upload 文件夹的内容复制到商店的根目录。
2. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Instabee，点击 Install（绿色 + 按钮）。
3. 点击 Edit（铅笔按钮）打开设置页面。
4. 在 Edit 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入 License key，然后点击 Activate（参见“许可证密钥”）。
5. 填写 Prices 部分；若要使用包裹柜选择器，还需填写您的 Budbee API key 和 API secret（参见“配置”）。开启 Enable/Disable 并点击 Save。
OpenCart 4
1. 在后台进入 Extensions > Installer，点击 Upload，选择文件 vfd_instabee.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包将无法使用。
2. 安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。
3. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Instabee，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按照 OpenCart 3 步骤 4 和 5 的方法输入许可证密钥和设置。两个版本的设置页面及其字段相同。
安装后，该方式保持关闭，直到您开启 Enable/Disable 并保存。如果您在卸载后重新安装扩展，之前保留的 Instabee 设置将再次生效。
配置
所有设置都在扩展页面中：Extensions > Extensions > Shipping > VibeFox Instabee > Edit。各部分列在左侧。点击一次 Save 即可保存整个页面，无需刷新。每次保存还会清除缓存的包裹柜列表和最近一次 API 错误。只有对本扩展拥有修改权限的管理员用户才能保存设置。
设置上方的提示会告诉您：是否只填写了一项 API 凭据、是否完全没有 API 凭据、是否没有国家价格和备用费用、最近一次 Budbee API 请求是否失败（附日期、时间和原因），以及商店是否没有单位为 kg 的重量等级且默认重量等级的单位无法识别（此时重量将按 kg 处理；请在 System > Localisation > Weight Classes 中添加 kg 重量等级）。
如果 Method name 为空或过长，Min weight (kg) 大于 Max weight (kg)，Sort order 不是整数，或者税务类别或地理区域不存在，则不会保存任何内容，并显示错误。
常规
Enable/Disable：在结账时显示或隐藏 Instabee。默认：off。
Method name：结账时显示给顾客的配送方式名称。默认：Instabee parcel box。必填，最多 64 个字符。
Tax class：None (the prices are final)（默认）表示下方价格即为最终价格。选择税务类别后，会在下方价格之上加收该类别的配送税。
Sort order：Instabee 在结账时配送方式中的排列位置。整数。
包裹柜选择器（Budbee API）
配置 API 凭据后，顾客在结账时会选择邮政编码附近的包裹柜，该包裹柜会保存在订单中。两个字段都必须填写。两者都设置之前，选择器保持关闭。
API key：您的 Budbee API 密钥（HTTP Basic 用户名）。
API secret：您的 Budbee API 密文（HTTP Basic 密码）。它绝不会写入日志。
保存后，两个字段都会保持为空，并显示 Saved - leave empty to keep it. 只有需要更改时才输入新值。若要删除已保存的凭据，请勾选 Remove the saved API key and secret 并保存。如果没有保存任何凭据，页面会显示 No credentials saved.
Test environment：使用 Budbee 测试环境 API（api.staging.budbee.com）。仅在使用 Instabee 提供的测试凭据时开启。正式商店应保持关闭（api.budbee.com）。默认：off。
价格（章节标题会显示商店的默认货币）
所有价格均以商店默认货币表示，不含税。小数逗号和小数点均可接受（49,90 = 49.90）。价格会以顾客的货币显示。
Calculation type：价格的计算方式。
Country prices：包含 Country、Price、XS ≤1 kg、S ≤2 kg、M ≤3 kg、L ≤5 kg 和 XL >5 kg 列的表格。点击 Add country 添加一行，点击 × 按钮删除一行。选择 * Any other country 可为没有单独行的所有国家设置一行。空白或为 0 的分段将使用 Price 列。Price 为 0 表示免运费。如果该国家的行对购物车重量没有价格，则使用 * 行，然后是 Fallback cost。保存时，不是 0 或更大数字的价格会被清除，国家未知的行会被删除，并且警告会列出这些内容。商品重量会从其 OpenCart 重量等级换算为 kg。
Fallback cost：当目的地国家的行和 * 行都不能提供价格时使用。留空则对这些国家隐藏该方式。
条件
Min weight (kg)：低于此购物车重量时隐藏该方式。默认：0（无限制）。
Max weight (kg)：高于此购物车重量时隐藏该方式。包裹柜最多可容纳约 20 kg。默认：20。0 表示无限制。不能小于 Min weight (kg)。
Minimum order amount：仅当需要配送的商品小计（优惠券折扣后、税前）达到此金额时才显示该方式。留空则始终显示。
Free shipping from：需要配送的商品小计（优惠券折扣后、税前）达到此金额时，该方式免费。留空则永不免费。
如果这些字段或 Fallback cost 中的值不是 0 或更大的数字，则不会保存，之前的值保持不变，并且警告会指出该字段。
可用性
Geo zone：仅向此地理区域内的地址提供 Instabee。All zones（默认）表示所有地区。开启 Ignore shipping zones 时不检查地理区域。地理区域在 System > Localisation > Geo Zones 中管理。
Ignore shipping zones：开启时，不检查 Geo zone，并且该方式将提供给下方列出的国家。关闭时（默认），仅应用 Geo zone。
Countries：该模式下的目的地国家。留空则允许所有国家。仅当 Ignore shipping zones 开启时使用此字段。
高级
Debug log：将调试信息写入 storage/logs/vfd_ibee_debug.log.php（OpenCart 4 中为 system/storage/logs/vfd_ibee_debug.log.php）。该文件无法通过网页读取。API 错误以及在 API 正常工作时未选择包裹柜而下的订单，即使此选项关闭也始终会被记录。API 密钥和顾客数据绝不会被记录。文件达到 5 MB 时，会被移至 vfd_ibee_debug.old.log.php，并开始新的日志。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Remove data on uninstall：开启时，卸载扩展会删除设置、缓存的包裹柜列表、日志以及未完成结账的包裹柜。关闭时（默认），设置会保留，以便重新安装。订单中保存的包裹柜始终保留。
导入 / 导出
Export：点击 Download JSON，将设置保存为 JSON 文件。API 密钥和密文不会被导出。
Import：粘贴之前导出的 JSON，然后点击 Import，即可恢复设置，例如在另一个商店中使用。这些值的检查方式与正常保存相同。已保存的 API 密钥和密文会被保留。
结账时的工作方式
OpenCart 显示配送方式时，会向扩展请求 Instabee 的价格。开启 Ignore shipping zones 时，只有在允许该国家的情况下才提供 Instabee（不检查地理区域）。否则，如果设置了 Geo zone 且地址不在其中，则不提供 Instabee。只有 Requires Shipping 设为 Yes 的商品才会计入：其他商品不增加重量，也不计入订单金额。订单金额是需要配送的商品的价格，扣除优惠券折扣后、税前。扩展会检查购物车重量和最低订单金额。如果小计达到 Free shipping from，价格为 0。否则，价格取自目的地国家的 Country prices 行、* 行或 Fallback cost。如果没有价格，则隐藏该方式。价格以您的默认货币计算，按其小数位数取整，并以顾客的货币显示，同时包含所选 Tax class 的税款。
当顾客在配送方式步骤中选择 Instabee，且已设置 API 凭据时，在该方式下方会为瑞典、芬兰、丹麦、荷兰和比利时显示 Parcel box 区块。该区块列出收货地址邮政编码附近的包裹柜，按距离排序，并显示名称、地址和距离。顾客可以输入其他邮政编码并点击 Search（或按 Enter）。在输入邮政编码之前，该区块会提示输入。如果找不到包裹柜，会请顾客尝试其他邮政编码或选择其他配送方式。对于其他国家，该方式会在没有包裹柜的情况下提供。
必须选择包裹柜。只有当所选包裹柜存在于该邮政编码的 Budbee 列表中时，才会为结账保存。未点击 Search 而直接输入的邮政编码不会被使用。顾客在配送方式步骤中点击 Continue 时，扩展会在服务器端再次检查包裹柜。否则，顾客会看到 Please choose an Instabee parcel box. 包裹柜名称取自 Budbee 列表，而非浏览器。如果顾客更改了配送国家或地址的邮政编码，之前的选择将被清除。
在 OpenCart 4 中，顾客在结账页面的配送方式区块中点击 Choose，并在 Shipping method options 窗口中选择 Instabee。Parcel box 区块会出现在该窗口中 Instabee 选项的下方，工作方式相同。窗口中的 Continue 按钮在未从列表中选择包裹柜时不会继续，并显示相同的提示。
扩展只会向 Budbee 发送目的地国家和邮政编码，绝不会发送姓名、地址、电子邮件或订单数据。包裹柜列表按邮政编码缓存 12 小时，没有包裹柜的邮政编码缓存 1 小时，失败的请求缓存 5 分钟，因此缓慢或故障的 API 不会拖慢每次结账页面的刷新。结账页面本身从不等待 Budbee：选中该方式后，列表会在后台加载。API 超时时间为 10 秒。
如果无法连接 Budbee API，顾客会看到 Parcel boxes cannot be loaded right now. You can place the order without choosing a box - the shop will assign one. 订单随后会被标记，您在预订配送时再选择包裹柜。此前已选择、但此时无法验证的包裹柜会被保留，并标记为未验证。
扩展不计算实时运费，不预订配送，不打印面单，不提供追踪号或追踪电子邮件，不提供 Budbee Home 送货时段，也不显示地图。请在您的 Instabee / Budbee 商家工具中，为所选包裹柜预订该包裹。
取件点
创建订单时，包裹柜会再检查一次，并保存到订单中。此后，前台无法更改它。在 OpenCart 4 中，结账时会保留一个订单，顾客每次重新确认时都会更新该订单，订单中的包裹柜也会随之更新。如果顾客将该订单改为其他配送方式，其包裹柜会被移除。包裹柜显示在以下位置：
订单的配送方式：包裹柜会添加到方式名称中，例如 Instabee parcel box:（方式名称），后面跟着包裹柜名称和地址。此文本会出现在后台和顾客账户中的订单页面上，以及订单电子邮件和发票中。
管理员订单页面（Sales > Orders）：一个 Instabee parcel box 面板，包含包裹柜名称、地址和 Box ID。如果结账时无法验证包裹柜，则会标记为 not verified (Budbee API was unavailable at checkout)。如果因 API 不可用而未选择包裹柜，面板会显示 Not chosen - the Budbee API was unavailable at checkout. Choose the box when you book the shipment. 该面板为只读，即使该方式已关闭也会显示。在 OpenCart 4 中，该面板显示在 History 上方。
发送给商店的新订单电子邮件：包裹柜名称及其 ID，或 Instabee parcel box: not chosen (Budbee API unavailable at checkout).
许可证密钥
本扩展使用来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox Instabee 许可证区块是 Extensions > Extensions > Shipping > VibeFox Instabee > Edit 页面中位于设置上方的第一个区块。将密钥输入 License key 并点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入另一个密钥）和 Remove key（将密钥从本商店中移除）。其下方有一行 Product: opencart-shipping-instabee 和链接 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 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 Instabee 配送方式，也不会计算运费。在同一浏览器中登录后台的管理员用户仍可在商店中看到该方式，并标有 (unlicensed — visible to admins only)，因此您可以在购买密钥前设置和测试扩展。在 OpenCart 4 中此预览不可用：商店看不到后台登录状态，因此没有有效密钥时，该方式对所有人都隐藏。打开一次 Edit 页面后，后台 Dashboard 会出现提醒。点击 × 可将其隐藏 7 天。现有订单不受影响。
许可证到期后，扩展仍会继续运行，但更新和支持需要续费。打开管理后台的 Dashboard 或 Edit 页面时，系统会自动再次检查状态：输入密钥后的前 14 天每天检查一次，之后每周检查一次。无需 cron 任务。卸载扩展时，许可证密钥和许可证状态始终会被删除。
故障排除
Instabee 在结账时未出现：请检查许可证是否有效，以及 Enable/Disable 是否已开启。检查 Geo zone；如果开启了 Ignore shipping zones，则检查 Countries 中是否允许该国家。检查该国家是否有价格，或是否存在 * 行或 Fallback cost。检查重量限制和 Minimum order amount，并确认商品的 Requires Shipping 设为 Yes。设置上方的警告会提示未配置价格。开启 Debug log，即可在 Log 字段中查看原因。
顾客看不到包裹柜列表：只有在 API key 和 API secret 都已设置、顾客所在国家为瑞典、芬兰、丹麦、荷兰或比利时，并且已输入邮政编码后，列表才会出现。最近一次 API 错误会显示在设置上方。详细信息位于扩展页面的 Log 字段中。开启 Debug log 可查看更多细节。
日志中出现 HTTP 401 或 403：Budbee 拒绝了 API 密钥或密文。请检查它们，并确认 Test environment 与您的凭据相符（只有在开启测试环境时才使用测试凭据）。
某个邮政编码没有包裹柜：Budbee 不为该邮政编码提供服务。顾客可以搜索其他邮政编码，或选择其他配送方式。
顾客无法从配送方式步骤继续：除非无法连接 Budbee API，否则必须从列表中选择包裹柜。不在所搜索邮政编码列表中的包裹柜不会被保存，顾客会看到 This parcel box is not in the Budbee list for the postal code. Please choose the parcel box again.
修改后仍显示旧的包裹柜列表：请在扩展页面点击 Save。这会清除缓存的包裹柜列表。
页面显示“Warning: You do not have permission to modify VibeFox Instabee!”：您的管理员用户组可能只能查看设置。请在 System > Users > User Groups 中为该组授予 extension/shipping/vfd_instabee（OpenCart 3）或 extension/vfd_instabee/shipping/vfd_instabee（OpenCart 4）的修改权限。
卸载
进入 Extensions > Extensions，选择类型 Shipping，然后点击 VibeFox Instabee 旁边的 Uninstall（红色 − 按钮）。本扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会重置 Enable/Disable、Sort order、Tax class 和 Geo zone。缓存的包裹柜列表始终会被删除。如果开启了 Remove data on uninstall，设置、日志以及在从未形成订单的结账中选择的包裹柜也会被删除。如果关闭，其他设置会保留，并在您重新安装扩展时再次使用。订单中保存的包裹柜始终保留，现有订单保留其配送方式和费用。
在 OpenCart 4 中，如需同时删除扩展文件，请在卸载后进入 Extensions > Installer，点击已安装扩展列表中 VibeFox Instabee 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。
Instabee 和 Budbee 是其各自所有者的商标。本扩展与 Instabee 或 Budbee 无关联，也未获得其认可。