VibeFox Instabee for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块无法在较旧的 PHP 版本上安装。
Budbee API 凭据（仅用于包裹柜选择）：API 密钥（key）和 API 私钥（secret）。Instabee 向签订配送协议的商家发放这些凭据。请咨询您的 Instabee 联系人，或使用 Instabee 商家门户。API 文档位于 developer.budbee.com。没有凭据时，承运商仍可按固定价格运作，但顾客无法选择包裹柜。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure，或稍后在模块列表中找到 VibeFox Instabee 并点击 Configure。
3. 在 Configure 页面顶部的许可证区块中的 License key 字段输入您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。
4. 填写 Prices 部分，并为包裹柜选择器填写您的 Budbee API key 和 API secret（参见配置）。点击 Save。
安装时，模块会创建 Instabee parcel box 承运商，配送时间文本为 Delivery to an Instabee parcel box。该承运商会分配给所有客户组，以及瑞典、芬兰、丹麦、荷兰和比利时的配送区域。您可以在 Shipping > Carriers 中修改配送区域、客户组、配送时间和图标。请勿在那里设置价格：价格始终由模块提供。
配置
所有设置都位于模块页面：Modules > Module Manager > VibeFox Instabee > Configure。每个部分都有各自的 Save 按钮，点击后会保存整个页面。
设置上方的警告会提示：仅填写了一个 API 凭据、没有任何 API 凭据、没有国家价格也没有备用运费、上一次 Budbee API 请求失败（会显示日期、时间和原因）、找不到 Instabee 承运商，以及店铺的重量单位无法识别（请在 International > Localization 的 Local units 中设置 kg、g、lb 或 oz）。每次保存设置时，缓存的包裹柜列表和上一次 API 错误都会被清除。如果方法名称或税务状态无效，或 Min weight (kg) 大于 Max weight (kg)，则不会保存任何内容，并会显示错误信息。
General
Enable/Disable：开启或关闭该承运商。这与 Shipping > Carriers 中的承运商状态是同一个开关。
Method name：结账时显示给顾客的承运商名称。默认值：Instabee parcel box。必填，最多 64 个字符。
Tax status：None 表示下方价格为最终价格。Taxable 并选择税务规则时，PrestaShop 会在下方价格之上加上该规则的运费税。
包裹柜选择器（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）。默认：关闭。
价格（部分标题会显示店铺的默认货币）
所有价格均以店铺默认货币计算，不含税。小数逗号和小数点均可接受（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。非数字的价格会被清空，并在警告中列出。重量会从店铺的重量单位换算为 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 中的某个值不是数字，则不会保存，保留之前的值，并且警告会指出该字段。
无配送区域时的可用性
通常，承运商会在 Shipping > Carriers 中与其关联的配送区域内提供。您也可以在此为指定国家列表启用该承运商。
Ignore shipping zones：即使承运商的区域未包含下列国家，也会在这些国家提供该承运商。承运商会关联到所有已启用的区域，包括之后创建的区域。关闭该选项后，承运商会恢复其原有的区域。
Countries：该模式下的目的国。留空则允许所有国家。此字段仅在 Ignore shipping zones 开启时使用。
高级
Debug log：将调试信息写入模块文件夹中的 logs/vfd_ibee_debug.log.php。该文件无法通过网页打开。即使此选项关闭，API 错误也始终会记录。API 密钥和顾客数据绝不会写入日志。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Remove data on uninstall：开启时，卸载模块会删除设置和承运商。关闭时，卸载只会关闭承运商。订单中保存的包裹柜始终保留。
结账时的运作方式
在配送步骤，PrestaShop 会向模块请求 Instabee 价格。只有实物商品才计入：虚拟商品不增加重量，也不计入订单金额。模块会检查条件：购物车重量和最低订单金额，以及在开启 Ignore shipping zones 时允许的国家。如果购物车小计达到 Free shipping from，价格为 0。否则，价格取自目标国家的 Country prices 行、* 行或 Fallback cost。如果没有价格，承运商将被隐藏。
当顾客选择 Instabee 承运商且已配置 API 凭据时，在瑞典、芬兰、丹麦、荷兰和比利时，承运商下方会出现 Parcel box 区块。该区块会按距离排序列出收货地址邮政编码附近的包裹柜，并显示名称、地址和距离。顾客可以输入其他邮政编码，然后点击 Search（或按 Enter 键）。在输入邮政编码之前，该区块会要求输入。如果找不到包裹柜，会提示顾客尝试其他邮政编码或选择其他配送方式。对于其他国家，承运商会在没有包裹柜的情况下提供。
包裹柜为必选项。只有当所选包裹柜在该邮政编码的 Budbee 列表中时，才会保存到购物车。顾客在配送步骤点击 Continue 时，模块会在服务器端再次检查包裹柜。否则，顾客会看到 Please choose an Instabee parcel box. 包裹柜名称取自 Budbee 列表，而非浏览器。如果顾客更改了收货国家或地址的邮政编码，之前的选择会被清除。
模块仅向 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. 此时订单会被标记，您可在预订配送时选择包裹柜。此前选择的包裹柜若此时无法验证，会被保留并标记为未验证。
该选择器适用于 Classic 和 Hummingbird 主题。如果承运商在产生订单后于 Shipping > Carriers 中被编辑，PrestaShop 会将其保存为新版本的承运商。模块会自动跟随新版本。
本模块不计算实时运费，不预订运单，不打印面单，不提供物流单号或追踪邮件，不提供 Budbee Home 配送时段，也不显示地图。请在您的 Instabee / Budbee 商家工具中为所选包裹柜预订包裹。
取件点
创建订单时，包裹柜会再次检查并保存到订单中。此后，前台无法更改。包裹柜显示在以下位置：
后台订单页面：一个 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.
订单确认页面和客户账户中的订单详情：Instabee parcel box: 包含包裹柜名称和地址。
订单邮件：包裹柜会添加到发送给顾客的订单确认邮件中的承运商名称之后。发送给店铺的新订单邮件（来自 PrestaShop 的 Mail alerts 模块）也会显示包裹柜 ID。如果因 API 不可用而未选择包裹柜，只有发给店铺的邮件会提及此事。
许可证密钥
本模块需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Instabee 是 Modules > Module Manager > VibeFox Instabee > Configure 页面上的第一个区块，位于设置上方。请将密钥输入 License key，然后点击 Activate。之后，该区块会以隐藏方式显示密钥、状态（例如许可证有效期截止日期和您的域名），并提供以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从此店铺移除密钥）。其下方是 Product: presta-shipping-instabee 一行，以及 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 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 Instabee 承运商，也不会计算任何运费。PrestaShop 前台无法得知您已登录后台，因此承运商对您也是隐藏的：您可以在购买密钥之前设置模块，但无法在结账时进行测试。Modules > Module Manager 的 Alerts 选项卡中会显示提醒。现有订单不受影响。
许可证到期后，模块仍会继续运行，但更新和支持需要续订。在后台工作时，状态会自动重新检查：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时不显示 Instabee：请检查许可证是否有效，以及 Enable/Disable 是否开启。在 Shipping > Carriers 中，检查承运商是否覆盖顾客所在国家的区域和顾客所属的客户组，或者 Ignore shipping zones 是否开启且该国家在允许列表中。检查该国家是否有价格，或是否存在 * 行或 Fallback cost。检查重量限制和 Minimum order amount。设置上方的警告会提示未配置价格的情况。也可以在商品页面上将商品限制为特定承运商。开启 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。这会清除缓存的包裹柜列表。
页面提示找不到 Instabee 承运商：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块以重新创建。同样适用于 The settings were saved, but the carrier could not be updated. 消息。重置会保留承运商的状态：已关闭的承运商仍保持关闭。
卸载
进入 Modules > Module Manager，打开 VibeFox Instabee 旁边的菜单，选择 Uninstall。许可证密钥和许可证状态始终会被删除。缓存的包裹柜列表始终会被删除。如果 Remove data on uninstall 已开启，承运商将被删除（订单保留其历史记录），同时删除设置、日志，以及从未转化为订单的购物车中所选的包裹柜。如果该选项关闭，则仅关闭承运商，所有设置都会保留。重新安装模块后，已保存的承运商会恢复其原有状态。订单中保存的包裹柜始终保留。
Instabee 和 Budbee 是其各自所有者的商标。本模块与 Instabee 或 Budbee 无关，也未获其认可。