VibeFox Mercado Envios for WooCommerce — 帮助
系统要求
WordPress：5.8 或更高版本。
WooCommerce：7.0 或更高版本，已安装并启用。没有 WooCommerce 时，插件无法激活。
PHP：8.0 或更高版本。
Mercado Pago 账户（仅用于实时运费）：实时运费来自您在阿根廷、巴西或墨西哥的 Mercado Pago 账户中的 Mercado Envios 运费计算器。该账户必须已启用 Mercado Envios。包裹将按该账户中设置的发货地址报价。您需要生产环境的 Access Token（以 APP_USR- 开头）：在 Mercado Pago 开发者面板中打开您的应用及其生产环境凭据。没有登录按钮：您需要将令牌粘贴到设置中。如果您只使用按国家设置的价格，则不需要 Mercado Pago 账户。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 vfd_mercado_envios 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Shipping > VibeFox Mercado Envios，或在插件页面中点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 如需实时运费，请粘贴 Access Token，选择 Mercado Envios 国家；如果店铺货币不是 ARS、BRL 或 MXN，还需填写汇率。可选填写 Country prices 和 Fallback cost（无实时运费时使用）。
6. 在 WooCommerce > Settings > Shipping > Shipping zones 中，将 VibeFox Mercado Envios 添加到某个配送区域；或者开启 Ignore shipping zones 并选择国家。
配置
所有设置都在同一页面中：WooCommerce > Settings > Shipping > VibeFox Mercado Envios。这些设置适用于所有配送区域。将该方式添加到某个区域时，区域窗口中只有一个字段：
Title (zone)：该选项在结账时显示的名称。留空则使用全局的 Name。
页面顶部的警告会显示配置问题：缺少汇率、没有访问令牌和价格，以及最近一次 Mercado Envios API 错误及其日期。每次保存设置时，缓存的运费都会被清除。
常规
Enable/Disable：同时在所有区域启用或禁用 Mercado Envios 配送。
Name：结账时向顾客显示的配送方式名称。默认：Mercado Envios。
Tax status：Mercado Envios 提供的是最终价格。None 按报价原样显示；Taxable 会在其上加上您的 WooCommerce 配送税。
Mercado Envios API（实时运费）（没有令牌时，仅使用下方的价格）
Access token：您的 Mercado Pago 生产环境 Access Token（APP_USR-...）。它仅发送给 Mercado Pago，且从不写入日志。
Mercado Envios country：您 Mercado Pago 账户所在国家：Argentina (ARS)（默认）、Brazil (BRL) 或 Mexico (MXN)。只会为该国家的目的地请求实时运费，并以该国货币报价。
Exchange rate：仅当店铺货币与 Mercado Envios 货币不同时需要：1 ARS、BRL 或 MXN 以店铺货币计的价格，例如 0.001。未设置时，不会使用实时运费。小数点和逗号都可以作为小数分隔符。
无实时运费时的价格
这些价格在没有访问令牌、目的地不在 Mercado Envios 国家范围内，以及 API 未返回运费时使用。
Country prices：以店铺货币计的价格。点击 + Add country 添加一行，点击叉号删除一行。选择 * All other countries 可用于所有没有单独一行的国家。Price 是该国家的价格。XS（最多 1 kg）、S（1-2 kg）、M（2-3 kg）、L（3-5 kg）和 XL（超过 5 kg）各列会在该购物车重量下替代它。空白或为 0 的列会使用 Price。非数字的值会在保存后提示并清除。没有任何价格的行会在保存时被删除。
Fallback cost：当 API 和 Country prices 都无法提供价格时使用。留空则在这种情况下隐藏该方式。
Calculation type：Per order 只收取一次价格。Per item (each item priced by its own weight x quantity) 会根据每件商品的重量在 Country prices（或 Fallback cost）中查找价格，并乘以数量。Mercado Envios 实时运费始终针对整个包裹。
可用性
Min weight (kg)：该方式显示所需的最低购物车重量。0 表示不限制。
Max weight (kg)：购物车重量超过此值时隐藏该方式。默认：25。0 表示不限制。
Minimum subtotal：仅当购物车小计不低于此金额时显示该方式。留空则始终显示。
Excluded shipping classes：当购物车中任一商品属于这些 WooCommerce 配送类别时，隐藏该方式。
Ignore shipping zones：即使未将该方式添加到配送区域，也为下方列出的国家提供该方式。
Countries：该模式下的目的国家。留空表示所有国家。仅在 Ignore shipping zones 开启时使用此字段。
免运费
Free shipping from：购物车小计达到此金额后，该方式免运费。此时不会向 Mercado Envios 发送请求。留空则禁用此功能。
高级
Debug log：将 API 请求和运费计算记录到 WooCommerce > Status > Logs（来源为 vfd-mercado-envios）。即使关闭此选项，错误也始终会被记录。访问令牌和顾客地址从不记录。
Remove data on uninstall：开启后，删除插件会移除所有插件设置和区域方式。停用插件永远不会删除设置。
结账时的工作流程
当顾客输入配送地址时，WooCommerce 会向插件请求运费。插件首先检查条件：购物车重量、最低小计和排除的配送类别。如果适用免运费，则该方式费用为 0，并且不会向 Mercado Envios 发送请求。
对于 Mercado Envios 国家内、邮编有效的目的地，插件会将购物车描述为一个包裹：商品中的最大宽度和长度，所有商品高度的总和，以及以克为单位的总重量。每条边和重量都会提高到该国 Mercado Envios 的最低标准，因此没有尺寸或重量的商品也能获得运费。购物车金额以 Mercado Envios 货币作为商品价格发送。Mercado Envios 返回的最便宜选项会换算为您的店铺货币，并显示在您的配送方式名称之下。
每个报价缓存 1 小时，因此相同的购物车不会触发新的请求。失败的报价 5 分钟内不会重试。如果无法连接 Mercado Pago 或其拒绝令牌，所有实时报价将暂停 5 分钟，以免结账页面在每次刷新时都等待 API。API 超时时间为 10 秒。
在以下情况下，将改用无实时运费的价格：没有令牌、目的地不在 Mercado Envios 国家范围内、邮编缺失或无效、缺少汇率、包裹超过该国 Mercado Envios 的重量上限（阿根廷 25 kg，巴西 15 kg，墨西哥 30 kg），或 Mercado Envios 对该地址返回错误或没有任何选项。使用该国家的行（或 * 行），否则使用备用运费。如果没有任何价格，则隐藏该方式。顾客永远不会看到 API 错误。
该方式适用于经典结账以及购物车和结账区块。它兼容 WooCommerce High-Performance Order Storage（HPOS）。
插件只计算运费。它不创建运单、不打印面单，也不追踪包裹。请在您的 Mercado Libre 或 Mercado Pago 账户中创建运单。它为每个方式显示一个运费，即最便宜的 Mercado Envios 选项，而不是在所有选项之间选择；并且没有自提点（网点）选择器。
订单
当订单使用实时运费下单时，服务名称和以天数表示的预计送达时间会以 Mercado Envios service 和 Estimated delivery 的形式保存在订单的配送明细中。现有订单保留其配送明细。
许可证密钥
插件需要使用从 vibefox.net 获取的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Shipping > VibeFox Mercado Envios 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期截止日期以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入另一个密钥，使用 Remove key 将其从本站点移除。Manage licenses and domains in your account 链接会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥并不会释放域名名额。请在您的 vibefox.net 账户中释放名额。
没有有效密钥时，结账页面不会向顾客显示 Mercado Envios。已登录的店铺管理员仍可看到该选项，并标有 (unlicensed — visible to admins only)，以便您在购买密钥前设置和测试插件。插件页面和 WooCommerce 页面上会显示提醒。现有订单不受影响。
许可证到期后，插件仍可继续工作，但更新和支持需要续费。状态会在后台自动重新检查。
故障排除
结账时不显示 Mercado Envios：请检查许可证是否有效、Enable/Disable 是否开启，以及该方式是否已添加到顾客所在国家的区域中（或 Ignore shipping zones 已开启且允许该国家）。请检查设置页面顶部的警告、重量限制、Minimum subtotal 和 Excluded shipping classes。该方式需要有价格：对于 Mercado Envios 国家内地址，需要有效的访问令牌，或设置 Country prices 或 Fallback cost。
实时运费不显示：开启 Debug log，重新加载结账页面，然后打开 WooCommerce > Status > Logs，来源选择 vfd-mercado-envios。常见原因：没有令牌、目的地不在 Mercado Envios 国家范围内、邮编缺失或无效、缺少 Exchange rate、包裹超过重量上限，或该地址没有 Mercado Envios 选项。
警告中出现 HTTP 401 或 403：访问令牌无效或已过期。请从 Mercado Pago 开发者面板重新复制生产环境 Access Token。
Mercado Envios 以其他货币回复：账户所在国家与 Mercado Envios country 不一致。请选择您 Mercado Pago 账户所在的国家。
价格使用哪种货币：Country prices 和 Fallback cost 以您的店铺货币计。实时运费以您 Mercado Pago 账户的货币返回；如果店铺使用其他货币，则会通过 Exchange rate 进行换算。
更改后运费看起来过时：保存设置页面。这将清除缓存的运费。
许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在其他域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now 为新域名激活密钥。如果无法连接许可证服务器，插件将继续使用最后已知的状态运行。
卸载
停用插件会保留所有设置，只清除运费缓存。要将其删除，请先停用，然后在 Plugins 页面中删除。该插件的许可证密钥和许可证状态、缓存的运费以及最近一次 API 错误始终会被移除。只有开启了 Remove data on uninstall 时，设置和区域方式才会被删除；否则它们会保留，以便日后重新安装时使用。现有订单保留其配送明细。
Mercado Envios 和 Mercado Pago 是各自所有者的商标。本插件与 Mercado Envios 或 Mercado Pago 无关联，也未获其认可。