VibeFox Melhor Envio for WooCommerce — 帮助
系统要求
WordPress：5.8 或更高版本。
WooCommerce：7.0 或更高版本，已安装并启用。未安装 WooCommerce 时，插件无法启用。
PHP：8.0 或更高版本。
Melhor Envio 账户（仅用于实时报价）：实时报价需要访问令牌。请在您的 Melhor Envio 账户中打开令牌的访问权限页面（Integrações > Permissões de acesso，melhorenvio.com.br/painel/gerenciar/tokens），生成一个带有“shipping-calculate”权限的令牌。如需测试，请在 Melhor Envio 沙盒中生成令牌（sandbox.melhorenvio.com.br/painel/gerenciar/tokens）。正式环境和沙盒的令牌不同。令牌会过期。没有“连接”按钮：您需要将令牌粘贴到设置中。没有令牌时，该配送方式使用备用价格。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 vfd_melhor_envio 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Shipping > VibeFox Melhor Envio，或在插件页面中点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 粘贴访问令牌、联系邮箱和发货 CEP。如果您的商店货币不是 BRL，请设置 BRL exchange rate。您还可以选择填写备用价格表（例如针对巴西）或备用费用。
6. 在 WooCommerce > Settings > Shipping > Shipping zones 中为巴西添加一个配送区域，并将 VibeFox Melhor Envio 添加到该区域；或者开启 Ignore shipping zones 并选择国家。
配置
所有设置都在同一个页面：WooCommerce > Settings > Shipping > VibeFox Melhor Envio。这些设置适用于所有配送区域。将该方式添加到某个区域时，区域窗口中只有一个字段：
Title (zone)：该选项在结账时的名称。留空则使用全局的 Name。
页面顶部的警告会提示设置不完整的情况：发货 CEP 不是 8 位数字、缺少联系邮箱、缺少 BRL 汇率、Melhor Envio API 最近一次错误（含日期），或者既没有令牌也没有备用价格。每次保存设置时，缓存的报价都会被清除。
常规
Enable/Disable：一次性在所有区域中开启或关闭 Melhor Envio 配送。
Name：结账时显示给顾客的配送方式名称。默认：Melhor Envio。
Tax status：Taxable 会将 WooCommerce 税费计入配送费用，None 则不计入。
Melhor Envio API
Access token：下方所选环境的令牌。它绝不会被写入日志。
Sandbox：测试时使用 Melhor Envio 沙盒（sandbox.melhorenvio.com.br）。需配合沙盒令牌使用。默认：关闭。
Contact e-mail：技术联系邮箱，会随每次请求发送给 Melhor Envio。Melhor Envio 要求所有集成都提供该邮箱。
Origin CEP：包裹的发货 CEP（8 位数字），例如 01310-100。没有有效的发货 CEP，将不会请求任何报价。
Services：可选，用英文逗号分隔的 Melhor Envio 服务 ID，用于报价，例如 1 = Correios PAC，2 = Correios SEDEX，17 = Correios Mini Envios，3 = Jadlog .Package，4 = Jadlog .Com。留空则对您账户中的所有服务报价。
Quotes at checkout：报价的显示方式。
Delivery time：在名称旁显示 Melhor Envio 的配送时效估计，例如“(3-5 business days)”。默认：开启。
Declared value：在报价中申报商品价值（保险）。关闭时，报价不含申报价值：更便宜，但包裹没有保险。默认：开启。
BRL exchange rate：Melhor Envio 以巴西雷亚尔报价。只有当您的商店货币不是 BRL 时才需要设置：请输入 1 BRL 等于多少商店货币，例如 0.17。未设置时，不会使用实时报价。申报价值也会按相同汇率换算为 BRL。
Default product weight (kg)：用于没有重量的商品，同时用于报价和重量限制。默认：0.3。
Default product size (cm)：用于没有尺寸的商品的长 x 宽 x 高。默认：16x11x5。
Fallback prices（以您的商店货币计）
当没有令牌、缺少目的地 CEP，或 API 没有返回报价（出错、超时、无覆盖范围）时，使用备用价格。
Fallback price table：按国家和购物车重量设定的价格。点击 + Add country 添加一行，点击叉号删除一行。选择 * Any country 可用于没有单独一行的所有国家。每行都有 Price 和重量列：XS 为 1 kg 以下，S 为 1-2 kg，M 为 2-3 kg，L 为 3-5 kg，XL 为 5 kg 以上。某列为空或为 0 时使用 Price。“9.99”和“9,99”均可接受。保存后会提示不是数字的值，并忽略这些值。
Fallback cost：价格表中也没有价格时使用。留空则在这种情况下隐藏该配送方式。
Fallback calculation：Per order 只收取一次备用价格。Per item (each item priced by its own weight x quantity) 会按每件商品的重量（没有重量时使用默认重量）查找备用价格，再乘以其数量。这仅适用于备用价格。Melhor Envio 的报价已包含所有商品。
Availability
Min weight (kg)：购物车重量低于此值时隐藏该配送方式。0 表示不限制。
Max weight (kg)：购物车重量高于此值时隐藏该配送方式。默认：30。0 表示不限制。
Minimum subtotal：仅当购物车小计（折扣之后、税费之前）不低于此金额时才显示该配送方式。留空则始终显示。
Free shipping from：购物车小计达到此金额即免运费。使用每项服务一个选项时，只有最便宜的服务免费，更快的服务保持原价。留空则禁用。
Excluded shipping classes：如果购物车包含这些 WooCommerce 配送类别中的任何商品，则隐藏该配送方式。
Ignore shipping zones：即使未将该方式添加到配送区域，也可为下方列出的国家提供该方式。
Countries：该模式下的目的地国家。留空则适用于所有国家。仅当开启 Ignore shipping zones 时才会使用此字段。
高级
Debug log：将 API 请求和费率计算记录到 WooCommerce > Status > Logs（来源 vfd-melhor-envio）。即使此选项关闭，错误也始终会被记录。令牌和顾客地址绝不会被记录。
Remove data on uninstall：开启后，删除插件会移除所有插件设置和区域配送方式。停用插件从不会删除设置。
结账时的工作方式
当顾客输入配送地址时，WooCommerce 会向插件请求费率。插件首先检查条件：购物车重量、最低小计和排除的配送类别。
对于巴西的配送地址（CEP 为 8 位数字），插件会向 Melhor Envio 发送发货 CEP 和目的地 CEP，以及每件可配送商品的重量、尺寸、数量和申报价值；如果您设置了服务列表，还会一并发送。报价会换算为您的商店货币，并按价格排序。顾客会看到最便宜的服务，或每项服务一个选项；如果启用了配送时效，还会显示时效估计。若适用免运费，最便宜的服务费用为 0。
每个报价会按包裹、CEP 和环境缓存 1 小时，因此同一购物车不会触发新的请求。失败的请求会记住 5 分钟，这样 API 故障不会拖慢每次结账页面的刷新。API 超时时间为 12 秒。
如果没有令牌、地址位于巴西境外或尚无有效 CEP、缺少 BRL 汇率，或 Melhor Envio 返回错误或该路线没有可用服务，则使用备用价格：该国家的行（或 * 行），否则使用备用费用。若适用免运费，即使没有价格，该方式也会以免费形式显示。如果完全没有价格，该方式将被隐藏。顾客永远不会看到 API 错误。
该方式适用于经典结账，以及购物车和结账区块。它兼容 WooCommerce 高性能订单存储（HPOS）。
插件只计算价格。它不购买或生成运单，不会将发货添加到 Melhor Envio 购物车，不跟踪包裹，不安排取件，也不发送发票（NF-e）数据。它不提供 Jadlog、Azul 或 LATAM 网点（投递点）的选择，也不提供“亲启”和“回执”等附加服务。请在您的 Melhor Envio 后台管理发货。Melhor Envio 仅在巴西境内配送。其他国家只使用备用价格。
订单
当订单使用实时报价下单时，所选服务和配送时效估计会保存在订单的配送行中。它们会以 Melhor Envio service 和 Delivery estimate 的形式显示在订单页面和订单邮件中，方便您知道应在 Melhor Envio 中购买哪项服务。现有订单保留其配送行。
许可证密钥
插件需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Shipping > VibeFox Melhor Envio 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期截止日期以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将密钥从本站移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。将密钥从某个站点移除并不会释放该域名名额。请在您的 vibefox.net 账户中释放名额。
没有有效密钥时，Melhor Envio 不会在结账时显示给顾客。已登录的商店管理人员仍然可以看到该方式，并标有 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试插件。插件页面和 WooCommerce 页面上会出现提醒。现有订单不受影响。
许可证到期后，插件仍可继续工作，但更新和支持需要续费。状态会在后台自动重新检查。
故障排除
结账时未显示 Melhor Envio：请检查许可证是否有效、Enable/Disable 是否开启，以及该方式是否已添加到顾客所在国家的区域中（或已开启 Ignore shipping zones 且该国家已被允许）。请查看设置页面顶部的警告、重量限制、Minimum subtotal 和 Excluded shipping classes。没有令牌或报价时，该方式需要备用价格：在 Fallback price table 中添加一行，或设置 Fallback cost。
只显示备用价格：开启 Debug log，重新加载结账页面，然后打开 WooCommerce > Status > Logs，来源 vfd-melhor-envio。常见原因：没有令牌、发货 CEP 不是 8 位数字、商店货币不是 BRL 但未设置 BRL exchange rate、尚无目的地 CEP，或没有任何服务覆盖该路线。
日志或警告中出现 HTTP 401 或 403：Melhor Envio 拒绝了访问令牌。它可能错误、已过期或已被撤销，或属于另一个环境。请生成新令牌，并检查 Sandbox 设置是否与之匹配。
顾客看到的价格：使用一个选项时，显示 Melhor Envio 返回的最便宜服务。使用每项服务一个选项时，显示覆盖该路线的每项服务。Per item 仅适用于备用价格。
修改后报价看起来过时：请保存设置页面，这会清除缓存的报价。
许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在另一个域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now 为新域名激活密钥。如果无法连接许可证服务器，插件将沿用最后一次已知的状态继续工作。
卸载
停用插件会保留所有设置，只清除报价缓存。要彻底删除，请先停用，然后在 Plugins 页面中删除。该插件的许可证密钥、许可证状态和缓存的报价总会被移除。只有开启了 Remove data on uninstall 时，设置和区域配送方式才会被移除；否则它们会保留，供以后重新安装时使用。现有订单保留其配送行。
Melhor Envio 是其各自所有者的商标。本插件与 Melhor Envio 没有关联，也未获得其认可或背书。