VibeFox Loggi for OpenCart — 帮助
系统要求
OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP：8.0 或更高版本。
Loggi 账户（仅用于实时价格）：实时价格使用 Loggi GraphQL API，需要 Loggi 为商业账户签发的 API 密钥。请向您的 Loggi 客户经理或 Loggi 集成支持（integracoes@loggi.com）索取；另请参阅 docs.api.loggi.com 上的 Loggi API 文档。您需要三个值：Loggi 账户的邮箱、API 密钥以及您店铺的数字 ID。如果您的 Loggi 账户只有新版 Loggi REST 平台 API 的凭据（客户端 ID 和密钥），则无法使用实时价格，将改用固定价格。如果您只使用固定价格，则无需 Loggi 账户。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
下载文件是一个 zip 压缩包，包含两个 OpenCart 版本的安装包。请将其解压到您的计算机上。压缩包中包括 README.txt、OpenCart 3 安装包 vfd_loggi-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 vfd_loggi.ocmod.zip。只需安装适用于您 OpenCart 版本的安装包。两个版本的许可证密钥相同。
OpenCart 3
1. 在后台进入 Extensions > Installer，点击 Upload，选择文件 vfd_loggi-oc3-(version).ocmod.zip。该扩展不添加任何 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用 Installer，而是将该安装包中 upload 文件夹的内容复制到商店的根目录。
2. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Loggi，点击 Install（绿色的 + 按钮）。
3. 点击 Edit（铅笔按钮）打开设置页面。
4. 将您的 VibeFox 许可证密钥粘贴到 Edit 页面顶部许可证区块中的 License key 字段，然后点击 Activate（参见许可证密钥）。
5. 输入 Loggi API 邮箱、API 密钥、店铺 ID 和取件地址；如果商店默认货币不是 BRL，还需输入 BRL 汇率。添加固定价格作为安全备用（参见 Configuration），开启 Enable Loggi，然后点击 Save。
OpenCart 4
1. 在后台进入 Extensions > Installer，点击 Upload，选择文件 vfd_loggi.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名中读取扩展代码，重命名后的安装包将无法工作。
2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色的 + 按钮）。
3. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Loggi，点击 Install（绿色的 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按照 OpenCart 3 的第 4 和第 5 步输入许可证密钥和设置。两个版本的设置页面及其字段相同。
安装时，该扩展会创建一个小表格，用于缓存 Loggi 价格。在您开启 Enable Loggi 并保存之前，该配送方式处于关闭状态。如果您卸载后重新安装该扩展，将重新使用您保留的 Loggi 设置。
设置
所有设置都在扩展页面中：Extensions > Extensions > Shipping > VibeFox Loggi > Edit。各分区列在左侧。它们适用于所有地理区域。页面底部的一个 Save 按钮可保存整个页面，无需重新加载。每次保存还会清除缓存的 Loggi 价格。如果某个值无效，例如负数、无效邮箱或不是数字的店铺 ID，页面会显示错误，且不会保存任何内容。只有对该扩展拥有修改权限的管理员用户才能保存设置。
设置上方的警告（每次保存后都会再次显示）提示配置不完整：没有 API 凭据（仅使用固定价格）、既没有 API 凭据也没有固定价格（该配送方式永远不会显示）、没有取件地址，或没有 BRL 汇率。如果商店没有单位为 kg 的重量等级，或没有单位为 cm 的长度等级，且默认等级的单位无法识别，还会出现另一条警告。此时，商品重量按 kg 计算，尺寸按 cm 计算。请在 System > Localisation > Weight Classes 和 Length Classes 中添加这些等级。
常规
Enable Loggi：在结账时显示或隐藏 Loggi。默认：关闭。
Method title：顾客在购物车和结账时看到的配送方式名称。默认：Loggi。必填，最多 64 个字符，且不能包含字符 < > ; = # { }。
Sort order：Loggi 在结账时的配送方式中的位置。整数。
Loggi API（实时价格）（保持凭据为空则仅使用固定价格）
API e-mail：您的 Loggi 账户邮箱。API 密钥属于该邮箱。必须是有效的邮箱地址。清空它也会清除已保存的 API 密钥。
API key：您的 Loggi API 密钥。它仅发送给 Loggi，绝不会写入日志。保存后，该字段保持为空，并显示 Saved — leave empty to keep it; clear the API e-mail to remove it. 只有在需要更改时才输入新值。如果您更改了 API e-mail，还需输入新邮箱对应的 API 密钥，否则页面会显示错误，且不会保存任何内容。
Shop ID：您的店铺在 Loggi 后台中的数字 ID（pk），例如 12345。其他值会被拒绝并显示错误。
Staging：使用 Loggi 测试环境（staging）和测试凭据。测试环境与正式环境的账户和密钥不同。默认：关闭。
Pickup address：Loggi 取件的地址，写在一行中：街道和门牌号、街区、城市、州和 CEP，例如 Rua Example, 123 - Bairro, São Paulo - SP, 01310-100。实时价格必填：OpenCart 中的商店地址为自由文本，因此绝不会用来代替。没有取件地址时，Loggi 无法估价，仅使用固定价格。
BRL exchange rate：Loggi 价格以巴西雷亚尔计。如果您商店的默认货币是 BRL，则不需要此字段，页面会说明这一点。否则请输入 1 BRL 等于您商店货币的金额，例如 0.16。没有此值则不使用实时价格。仅接受正数。小数点和逗号都可作为小数分隔符。
固定价格（以商店默认货币计，不含税）
固定价格在 Loggi API 未配置、目的地在巴西境外或没有完整 CEP 时使用，并且在 Loggi 未返回价格（API 不可用、密钥被拒绝、地址超出服务范围）时始终使用。
Price table：每个目的国家一行。点击 Add country 添加一行，点击删除按钮删除一行。选择 * All other countries 可用于所有没有单独行的国家。每行包含一个 Base price 和重量列：XS 最高 1 kg，S 最高 2 kg，M 最高 3 kg，L 最高 5 kg，XL 超过 5 kg。空的（或为 0 的）重量列使用基础价格。基础价格为 0 表示免运费。"9.99" 和 "9,99" 均可接受。保存时会删除空行，以及同一国家的第二行。
Price for countries not in the table：在没有 Loggi 实时价格且价格表中没有目的国家的行（也没有 * 行）时使用。在这种情况下留空可隐藏该配送方式。
Fixed price applies：固定价格的计算方式。Loggi 实时价格已涵盖整个购物车，因此从不相乘。
条件
Minimum weight (kg)：购物车重量低于此值时隐藏该配送方式。0 表示无限制（默认）。
Maximum weight (kg)：购物车重量高于此值时隐藏该配送方式。默认：30。0 表示无限制。Minimum weight 不能大于 Maximum weight。
Minimum order amount：仅当需要配送的商品小计（优惠券后、税前）达到此金额时才显示该配送方式。留空则始终显示。
Free shipping from：需要配送的商品小计（优惠券后、税前）达到此金额后，Loggi 配送免费。若不设免运费，请留空。
Tax class：运费的税类，或 No tax（默认）。如果您的价格和 Loggi 价格已包含税费，请选择 No tax。
Geo zone：仅向该地理区域内的地址提供 Loggi。All zones（默认）表示无限制。地理区域在 System > Localisation > Geo Zones 中管理。Ignore shipping zones 开启时不检查地理区域。
对于重量限制和重量列，没有重量的商品按 0 kg 计算。
国家
OpenCart 没有承运商区域：Geo zone 将该配送方式限制在某个地理区域的地址内。您也可以开启 Ignore shipping zones 并选择一个国家列表。
Ignore shipping zones：无论 Geo zone 为何，都为下列国家提供 Loggi。此模式下不检查地理区域。默认：关闭。
Countries：该模式下的目的国家。留空则允许商店中启用的所有国家。仅当 Ignore shipping zones 开启时才使用此字段。
高级
Debug log：将价格计算和 Loggi 请求写入 storage/logs/vfd_lggi_debug.log.php（在 OpenCart 4 中为 system/storage/logs/vfd_lggi_debug.log.php）。该文件无法通过网页读取。即使此选项关闭，API 错误也始终会被记录。API 密钥和顾客地址绝不会写入日志。当文件达到 5 MB 时，它会被移动到 vfd_lggi_debug.old.log.php，并开始新的日志。
Log：显示调试日志的大小和最新条目。点击 Clear log 可清空。
Remove data on uninstall：开启时，卸载扩展会删除 Loggi 设置和日志。关闭时（默认），设置会保留，以便重新安装。缓存的价格始终会被删除。
导入 / 导出
Export：点击 Download JSON 可将设置保存为 JSON 文件。API 密钥不会被导出。
Import：粘贴之前导出的 JSON，然后点击 Import 恢复设置，例如在另一家商店中。这些值会像普通保存一样进行检查。已保存的 API 密钥会被保留。
结账时的工作方式
当 OpenCart 显示配送方式时，它会向扩展请求 Loggi 的价格。如果设置了 Geo zone，Ignore shipping zones 关闭，并且地址不在该地理区域内，则不提供 Loggi。只有 Requires Shipping 设为 Yes 的商品才会计算在内：其他商品不增加重量，也不计入订单金额。然后扩展检查各项条件：允许的国家（使用 Ignore shipping zones 时）、购物车重量和最低订单金额。订单金额是需要配送的商品价格，扣除优惠券折扣后、税前计算。礼品卡、奖励积分和商店余额不计入。如果适用免运费，则价格为 0，且不会向 Loggi 发送请求。
对于填写了完整 8 位 CEP 的巴西地址，扩展会构建 Loggi 包裹：每件商品旋转，使其最短边为高度，只要包裹保持在 55 × 55 × 55 cm 和 20 kg 以内，商品就会堆叠在同一个包裹中。没有重量或尺寸的商品按每边 1 cm 计算，每个包裹至少为 100 g。Loggi 每次估价最多接受 2 个包裹，因此较大的购物车会分多次请求，并累加总价。扩展会向 Loggi 发送您的店铺 ID、取件地址、配送地址（街道、城市、州和 CEP）以及包裹，并将 Loggi 的总价从 BRL 换算为您商店的默认货币。价格会按该货币的小数位数取整，并以顾客的货币显示，同时加上所选 Tax class 的税费。
每个 Loggi 价格会按购物车、地址、账户和环境缓存 1 小时，因此相同的购物车不会触发新的请求。失败的估价缓存 10 分钟。如果完全无法连接 Loggi，请求将暂停 2 分钟，这样结账时就不必每次刷新都等待 Loggi。API 超时时间为 10 秒。
当 API 未配置、地址在巴西以外或尚无完整 CEP、缺少 BRL 汇率、没有取件地址、某件商品大于 Loggi 包裹、购物车需要超过 10 个包裹，或 Loggi 返回错误、被拒绝的包裹、超出服务范围的地址或零总价时，将改用固定价格。如果也没有固定价格，则隐藏该配送方式。顾客永远不会看到 API 错误。原因会写入调试日志。
在 OpenCart 4 中，顾客点击结账页面配送方式区块中的 Choose，并在 Shipping method options 窗口中选择 Loggi。该配送方式的工作方式与 OpenCart 3 相同。
该扩展仅计算价格。它不会创建 Loggi 订单或货件，不打印面单，不追踪包裹，不在结账时显示配送时间，也不提供自提点或储物柜。它不会向订单添加任何内容：订单与其他 OpenCart 配送方式一样，显示配送方式名称和运费。请在 Loggi 后台创建货件。Loggi 仅在巴西境内配送。对于其他国家，请使用固定价格。
许可证密钥
该扩展需要使用来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox Loggi 许可证区块是 Extensions > Extensions > Shipping > VibeFox Loggi > Edit 页面中位于设置上方的第一个区块。请将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以隐藏形式显示密钥、状态（例如许可证的有效期截止日期和您的域名），并提供以下按钮：Check now 用于再次检查状态，Change key 用于输入其他密钥，Remove key 用于从本店铺中移除密钥。其下方是 Product: opencart-shipping-loggi 一行，以及 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 账户中释放该名额。
没有有效的密钥时，Loggi 配送方式不会在结账时向顾客显示，也不会计算任何价格。在同一浏览器中登录后台的管理员用户仍能在商店中看到该配送方式，并标注 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试该扩展。在 OpenCart 4 中此预览不可用：商店无法看到后台登录状态，因此没有有效密钥时，所有人都看不到该配送方式。您打开过一次 Edit 页面后，后台 Dashboard 上会出现提醒。点击 × 可将其隐藏 7 天。现有订单不受影响。
许可证到期后，扩展仍会继续工作，但更新和支持需要续费。当您打开后台的 Dashboard 或 Edit 页面时，状态会自动重新检查：输入密钥后的前 14 天每天一次，之后每周一次。无需设置定时任务（cron）。卸载扩展时始终会删除许可证密钥和许可证状态。
故障排除
Loggi 未在结账时出现：检查许可证是否有效，以及 Enable Loggi 是否已开启。检查 Geo zone、Ignore shipping zones 和 Countries、扩展页面顶部的警告、重量限制以及 Minimum order amount。如果顾客尚未输入完整 CEP，或 Loggi 未返回价格，则该配送方式需要固定价格：为国家添加一行、添加一个 * 行，或设置 Price for countries not in the table。检查商品的 Requires Shipping 是否设为 Yes。
仅显示固定价格：查看扩展页面上的 Log 字段。错误始终会被记录。为每个步骤开启 Debug log，然后刷新结账页面。常见原因：缺少 API 邮箱、密钥或店铺 ID，没有取件地址，非 BRL 货币的商店没有 BRL exchange rate，尚无完整的 8 位 CEP，商品大于 55 cm 或重于 20 kg，或地址超出 Loggi 服务范围。
日志中出现 HTTP 401 或 403：Loggi 拒绝了 API 邮箱或密钥。请与 Loggi 核对，并确认 Staging 与凭据一致：测试环境和正式环境的密钥不同。
我的商店以欧元或美元销售：Loggi 以 BRL 返回结果。请输入 BRL exchange rate（1 BRL 等于您商店默认货币的金额）。固定价格始终使用商店默认货币。
价格不准确：请填写产品的重量和尺寸。若未填写，产品按每边 1 cm 计算，每个包裹至少按 100 g 计算。
Per item 不会使 Loggi 价格相乘：这是有意为之的设计。Loggi 实时价格已涵盖整个购物车。Per item 仅适用于固定价格。
修改后价格看起来过时：点击扩展页面上的 Save。这会清除缓存的 Loggi 价格。
页面显示 "Warning: You do not have permission to modify VibeFox Loggi!"：您的管理员用户组可能只能查看设置。请在 System > Users > User Groups 中为该组授予 extension/shipping/vfd_loggi（OpenCart 3）或 extension/vfd_loggi/shipping/vfd_loggi（OpenCart 4）的修改权限。
开发人员：可以通过设置 vfd_lggi_api_url（用于测试）替换 Loggi API 地址；该设置在设置页面上没有对应字段。
卸载
进入 Extensions > Extensions，选择类型 Shipping，然后点击 VibeFox Loggi 旁边的 Uninstall（红色 − 按钮）。本扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会重置 Enable Loggi、Sort order、Tax class 和 Geo zone。缓存的 Loggi 价格（及其表格）始终会被删除。如果 Remove data on uninstall 已开启，Loggi 设置和调试日志也会被删除。如果已关闭，其他设置会保留，并在您重新安装扩展时再次使用。现有订单保留其配送方式和运费。
在 OpenCart 4 中，如需同时删除扩展的文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox Loggi 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。
Loggi 是其各自所有者的商标。本扩展与 Loggi 无关，也未获得其认可或背书。