VibeFox Loggi for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块会拒绝在更早的 PHP 版本上安装。
Loggi 账户（仅用于实时运费）：实时运费使用 Loggi GraphQL API，需要一个由 Loggi 为企业账户签发的 API 密钥。请咨询您的 Loggi 客户经理或 Loggi 集成支持（integracoes@loggi.com），另请参阅 docs.api.loggi.com 上的 Loggi API 文档。您需要三个值：Loggi 账户的电子邮件、API 密钥以及店铺的数字 ID。如果您的 Loggi 账户只有新版 Loggi REST 平台 API 的凭据（client ID 和 secret），则无法使用实时运费，将改用固定运费。如果您只使用固定运费，则无需 Loggi 账户。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 进入后台，前往 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox Loggi，然后点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥粘贴到 License key 中，然后点击 Activate（见“许可证密钥”）。
4. 输入 Loggi API 电子邮件、API 密钥、Shop ID 和取货地址；如果店铺默认货币不是 BRL，还需输入 BRL 汇率。添加固定运费作为安全备用（参见“配置”），然后点击 Save。
5. 在 Shipping > Carriers 中将巴西添加到 Loggi 承运商的配送区域，或者开启 Ignore shipping zones 并选择国家。
安装时，模块会创建 Loggi 承运商，配送时间文字为 Courier delivery in Brazil。该承运商分配到所有区域和所有客户组。您可以在 Shipping > Carriers 中修改区域、客户组、配送时间、徽标和尺寸限制。不要在那里设置价格：运费始终来自模块。
配置
所有设置都在模块页面：Modules > Module Manager > VibeFox Loggi > Configure。它们适用于承运商的所有区域。每个部分都有自己的 Save 按钮，会保存整个页面。每次保存也会清除缓存的 Loggi 运费。
页面顶部的警告提示设置不完整：没有 API 凭据（仅使用固定运费）、既没有 API 凭据也没有固定运费（承运商永远不会显示）、没有取货地址、没有 BRL 汇率，或店铺的重量或尺寸单位是模块无法识别的（此时按 kg 或 cm 计算；请在 International > Localization 中设置单位）。如果某个值无效，例如负数，页面会显示错误，且不会保存任何内容。
常规
Enable Loggi：开启或关闭承运商。这与 Shipping > Carriers 中的承运商状态使用同一开关。
Method title：顾客在购物车和结账时看到的承运商名称。默认：Loggi。必填，最多 64 个字符。
Loggi API（实时运费）（如仅使用固定运费，请将凭据留空）
API e-mail：您的 Loggi 账户电子邮件。API 密钥隶属于该账户。必须是有效的电子邮件地址。
API key：您的 Loggi API 密钥。它仅发送给 Loggi，绝不会被记录。保存后，该字段保持为空，并显示 Saved — leave empty to keep it; clear the API e-mail to remove it. 只有在需要更改时才输入新值。如果更改了 API e-mail，还须输入新电子邮件对应的 API 密钥，否则页面会显示错误且不会保存任何内容。要删除已保存的密钥，请清空 API e-mail 并保存。
Shop ID：您的店铺在 Loggi 后台的数字 ID（pk）。只接受正整数。其他值会被拒绝并显示错误。
Staging：使用 Loggi 的 Staging 环境和测试凭据。Staging 与生产环境的账户和密钥不同。默认：关闭。
Pickup address：Loggi 取件的地址，写在一行中：街道和门牌号、街区、城市、州和 CEP，例如 Rua Example, 123 - Bairro, São Paulo - SP, 01310-100。如果店铺地址位于巴西，且已填写地址和城市，可留空，以使用 Shop Parameters > Contact > Stores 中的店铺地址。没有取货地址时，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：承运商的税务规则，或 No tax。如果您的价格和 Loggi 运费已包含税费，请选择 No tax。
对于重量限制和重量栏，没有重量的商品按 0 kg 计算。
无配送区域时的可用性
Ignore shipping zones：无论匹配哪个区域，都为下列国家提供 Loggi。开启此选项并保存后，承运商会被添加到所有区域，之后创建的区域也会被添加。关闭此选项会移除这些添加的区域，使承运商恢复其自身的区域。
Countries：此模式下的目的国家。留空则允许店铺所有启用的国家。仅当 Ignore shipping zones 开启时才使用此字段。
高级
Debug log：将运费计算和 Loggi 请求写入模块文件夹中的 logs/vfd_lggi_debug.log.php。该文件无法通过网页打开。即使此选项关闭，API 错误也始终会被记录。API 密钥和顾客地址绝不会被记录。
Log：显示调试日志的大小和最新条目。点击 Clear log 可清空日志。
Remove data on uninstall：开启时，卸载模块会删除 Loggi 设置、承运商、缓存的运费和日志。关闭时，所有内容都会保留，以便重新安装。
结账时的工作方式
在配送步骤，PrestaShop 会向模块请求 Loggi 运费。只有实物商品计入：虚拟商品不增加重量，也不计入订单金额。模块首先检查条件：允许的国家（取决于 Ignore shipping zones）、购物车重量和最低订单金额。如果适用免运费，运费为 0，且不会向 Loggi 发送请求。
对于填写了完整 8 位 CEP 的巴西地址，模块会组装 Loggi 包裹：每件商品会旋转，使其最短边为高度，并且只要包裹不超过 55 × 55 × 55 cm 和 20 kg，商品就会堆叠在同一个包裹中。没有重量或尺寸的商品按每边 1 cm 计算，每个包裹至少为 100 g。Loggi 每次估算接受 2 个包裹，因此较大的购物车会分多次请求发送，并将总额相加。模块会将您的 Shop ID、取货地址、收货地址和包裹发送给 Loggi，并将 Loggi 的总额从 BRL 换算为店铺默认货币。然后，价格以顾客购物车的货币显示。
每个 Loggi 运费会按购物车、地址、账户和环境缓存 1 小时，因此同一购物车不会重复发起请求。失败的估算缓存 10 分钟。如果完全无法连接 Loggi，请求将暂停 2 分钟，以免结账页面每次刷新都等待 Loggi。API 超时时间为 10 秒。
在以下情况下，会改用固定运费：API 未配置；地址在巴西以外或尚无完整 CEP；缺少 BRL 汇率；没有取货地址；某件商品大于 Loggi 包裹；购物车需要超过 10 个包裹；或 Loggi 返回错误、被拒绝的包裹、超出服务范围的地址或零总额。如果也没有固定运费，承运商会被隐藏。顾客永远不会看到 API 错误。原因会写入调试日志。
如果您在承运商已有订单后，在 Shipping > Carriers 中编辑该承运商，PrestaShop 会将其保存为新的承运商版本。模块会自动跟随新版本。
模块仅计算运费。它不会创建 Loggi 订单或发货单，不打印面单，不在结账时显示送达时间，也不提供自提点或智能柜。请在 Loggi 后台创建发货单。Loggi 仅在巴西境内配送。其他国家请使用固定运费。
许可证密钥
本模块需要使用从 vibefox.net 获取的 VibeFox 许可证密钥。许可证区块 License — VibeFox Loggi 是 Modules > Module Manager > VibeFox Loggi > Configure 页面中位于设置上方的第一个区块。请将密钥粘贴到 License key 中，然后点击 Activate。此后，该区块会以遮蔽形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺移除密钥）。其下方有 Product: presta-shipping-loggi 一行和 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 账户中释放名额。
没有有效密钥时，结账时不会向顾客显示 Loggi 承运商，也不会计算运费。PrestaShop 前台无法知道您已登录后台，因此承运商对您也会隐藏：您可以在购买密钥前设置模块，但无法在结账时测试。Modules > Module Manager 中的 Alerts 选项卡会显示提醒。现有订单不受影响。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。在您使用后台期间，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时没有显示 Loggi：检查许可证是否有效，以及 Enable Loggi 是否已开启。在 Shipping > Carriers 中检查承运商是否覆盖顾客所在国家的区域和顾客组（或者 Ignore shipping zones 已开启且该国家被允许）。检查模块页面顶部的警告、重量限制和 Minimum order amount。如果顾客尚未填写完整 CEP，或 Loggi 未返回价格，承运商需要固定运费：该国家的一行、一个 * 行，或 Price for countries not in the table。您也可以在商品页面中将商品限制为特定承运商。
只显示固定运费：查看模块页面上的 Log 字段。错误始终会被记录。开启 Debug log 以记录每个步骤，然后刷新结账页面。常见原因：缺少 API 电子邮件、密钥或 Shop ID；没有取货地址；店铺货币不是 BRL 时缺少 BRL exchange rate；尚无完整的 8 位 CEP；商品大于 55 cm 或重于 20 kg；或地址超出 Loggi 服务范围。
日志中出现 HTTP 401 或 403：Loggi 拒绝了 API 电子邮件或密钥。请与 Loggi 核对，并检查 Staging 设置与凭据是否匹配：Staging 和生产环境的密钥不同。
我的店铺使用欧元或美元销售：Loggi 以 BRL 返回价格。请输入 BRL exchange rate（1 BRL 等于店铺默认货币的多少）。固定运费始终以店铺默认货币计价。
运费不准确：请填写商品的重量和尺寸。没有这些信息时，商品按每边 1 cm 计算，每个包裹至少按 100 g 计算。
Per item 不会乘以 Loggi 运费：这是设计如此。Loggi 实时运费覆盖整个购物车。Per item 仅适用于固定运费。
修改后运费看起来过时：点击模块页面上的 Save。这会清除缓存的 Loggi 运费。
页面提示未找到 Loggi 承运商：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块以重新创建。
卸载
进入 Modules > Module Manager，打开 VibeFox Loggi 旁边的菜单，选择 Uninstall。许可证密钥和许可证状态始终会被删除。缓存的 Loggi 运费始终会被删除。如果开启了 Remove data on uninstall，承运商会被删除（订单保留其历史记录），设置和日志也会被删除。如果关闭，承运商仅会被禁用，所有设置都会保留。重新安装模块后，已保存的承运商会恢复卸载前的状态。
Loggi 是其各自所有者的商标。本模块与 Loggi 无关联，也未获得 Loggi 的认可。