VibeFox Loggi for WooCommerce — 帮助
系统要求
WordPress：5.8 或更高版本。
WooCommerce：5.0 或更高版本，已安装并启用。未安装时插件无法启用。
PHP：8.0 或更高版本。
Loggi 账户（仅实时运费需要）：实时运费使用 Loggi GraphQL API，所需的 API 密钥由 Loggi 为企业账户签发。请联系您的 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. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件并点击 Install Now。您也可以通过 FTP 将 vfd_loggi 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Shipping > VibeFox Loggi，或在插件页面点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 输入 Loggi API 电子邮件、API 密钥、Shop ID 和取货地址；如果店铺货币不是 BRL，还需输入 BRL 汇率。添加固定运费作为安全备用（参见配置）。
6. 在 WooCommerce > Settings > Shipping > Shipping zones 中，将 VibeFox Loggi 添加到巴西的配送区域，或开启 Ignore shipping zones 并选择国家。
配置
所有设置都在同一页面：WooCommerce > Settings > Shipping > VibeFox Loggi。这些设置适用于所有配送区域。将该方式添加到某个区域时，区域窗口只有一个字段：
Title (zone)：顾客在该区域看到的名称。留空则使用全局的 Method title。
页面顶部的警告提示设置不完整：没有 API 凭据、没有取货地址或没有 BRL 汇率。每次保存设置时，缓存的 Loggi 运费都会被清除。
常规
Enable/Disable：一次性在所有区域启用或禁用此方式。
Method title：在购物车和结账页面显示的配送方式名称。区域可以覆盖此名称。默认值：Loggi。
Loggi API（实时运费）（留空凭据则仅使用固定运费）
API e-mail：您的 Loggi 账户电子邮件。API 密钥属于该账户。
API key：您的 Loggi API 密钥。它仅发送给 Loggi，且从不记录到日志中。
Shop ID：您的店铺在 Loggi 控制台中的数字 ID（pk）。只接受正数。输入其他值会被拒绝并显示错误，同时保留已保存的值。
Staging：使用带测试凭据的 Loggi Staging 环境。Staging 与生产环境的账户和密钥不同。默认值：关闭。
Pickup address：Loggi 取件的地址，写成一行：街道和门牌号、街区、城市、州和 CEP，例如 Rua Example, 123 - Bairro, São Paulo - SP, 01310-100。如果店铺地址位于巴西，可留空以使用 WooCommerce > Settings > General 中的店铺地址。没有取货地址时，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 order amount：仅当购物车小计（折扣后、税前）达到此金额时才显示该方式。留空则始终显示。
Free shipping from：购物车小计（折扣后、税前）达到此金额后，Loggi 配送免费。留空则不提供免运费。
Excluded shipping classes：购物车中包含以下任一 WooCommerce 配送类别的商品时，隐藏该方式。
Tax status：Taxable 会将 WooCommerce 税费加到运费上，None 则不加。如果您的价格和 Loggi 价格已包含税费，请选择 None。
无配送区域时的可用性
Ignore shipping zones：即使该方式未添加到任何配送区域，也为下方指定的国家提供 Loggi。
Countries：该模式下的目的国家。留空则使用您配送的所有国家。此字段仅在开启 Ignore shipping zones 时使用。
高级
Debug log：将每次运费计算和每个 Loggi 请求记录到 WooCommerce > Status > Logs（来源 vfd-loggi）。即使此选项关闭，API 错误也始终会被记录。API 密钥和顾客地址从不记录。
Remove data on uninstall：开启后，删除插件会移除所有 Loggi 设置和区域方式。仅停用插件从不删除设置。
结账时的工作方式
顾客输入配送地址时，WooCommerce 会向插件请求运费。插件首先检查条件：配送国家、购物车重量、最低订单金额和排除的配送类别。如果适用免运费，顾客将免费看到该方式，并且不会向 Loggi 发送请求。
对于填写了完整 8 位 CEP 的巴西地址，插件会构建 Loggi 包裹：每件商品旋转，使其最短边为高度，只要包裹保持在 55 × 55 × 55 cm 和 20 kg 以内，商品就会堆叠进同一个包裹。没有重量或尺寸的商品按每边 1 cm 计算，每个包裹至少重 100 g。Loggi 每次估价接受 2 个包裹，因此较大的购物车会分多次请求，并将总额相加。插件会向 Loggi 发送您的 Shop ID、取货地址、配送地址和包裹，将 Loggi 总额从 BRL 换算为店铺货币后显示。
每个 Loggi 运费会按购物车、地址、账户和环境缓存 1 小时，因此相同购物车不会触发新请求。失败的估价缓存 10 分钟。如果完全无法连接 Loggi，请求将暂停 2 分钟，以免结账页面在每次刷新时都等待 Loggi。API 超时时间为 10 秒。
当 API 未配置、地址在巴西以外或尚无完整 CEP、缺少 BRL 汇率、商品大于 Loggi 包裹、购物车需要超过 10 个包裹，或 Loggi 返回错误、被拒绝的包裹、超出服务范围的地址或零总额时，将改用固定运费。如果也没有固定运费，则隐藏该方式。顾客绝不会看到 API 错误。原因会写入日志。
该方式适用于经典结账以及购物车和结账区块，并兼容 WooCommerce 高性能订单存储（HPOS）。
插件只计算运费。它不会创建 Loggi 订单或发货单，不打印面单，不跟踪包裹，不在结账时显示送达时间，也不提供自提点或智能柜。请在 Loggi 控制台中创建发货单。Loggi 仅在巴西境内配送。其他国家请使用固定运费。
许可证密钥
插件需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Shipping > VibeFox Loggi 的顶部。将密钥粘贴到 License key 中并点击 Activate。区块会显示状态，例如许可证有效期至何时以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从本站点移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。
没有有效密钥时，Loggi 不会在结账时显示给顾客。已登录的店铺管理员仍可看到它，并标注 (unlicensed — visible to admins only)，以便您在购买密钥前设置和测试插件。插件页面和 WooCommerce 页面会显示提醒。现有订单不受影响。
许可证到期后，插件仍会继续工作，但更新和支持需要续费。状态会在后台自动重新检查。
故障排除
Loggi 未在结账时显示：检查许可证是否有效、Enable/Disable 是否开启、该方式是否已添加到顾客所在国家的区域（或已开启 Ignore shipping zones 且允许该国家）。查看设置页面顶部的警告、重量限制、Minimum order amount 和 Excluded shipping classes。如果顾客尚未输入完整 CEP，或 Loggi 未返回价格，则该方式需要固定运费：为该国家添加一行、添加 * 行，或设置 Price for countries not in the table。
只显示固定运费：打开 WooCommerce > Status > Logs，来源 vfd-loggi。错误始终会被记录。开启 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 仅适用于固定运费。
更改后价格看起来过时：保存设置页面。这会清除缓存的 Loggi 运费。
许可证区块显示错误：按照区块中的提示操作。例如，如果密钥已在其他域名上使用，请在 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now 以便为新域名激活密钥。如果无法连接许可证服务器，插件将继续使用上次已知的状态运行。
卸载
停用插件会保留所有设置。只会清除缓存的 Loggi 运费。要移除插件，请先停用，然后在 Plugins 页面删除。本插件的许可证密钥和许可证状态以及缓存的运费始终会被删除。只有开启了 Remove data on uninstall 时，设置和区域方式才会被删除。否则，它们会保留，以便日后重新安装。现有订单会保留其配送行。
Loggi 是其各自所有者的商标。本插件与 Loggi 无关联，也未获得 Loggi 的认可。