VibeFox Mercado Envios for OpenCart — 帮助
系统要求
OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP：8.0 或更高版本。
Mercado Pago 账户（仅用于实时费率）：实时费率来自您在阿根廷、巴西或墨西哥的 Mercado Pago 账户中的 Mercado Envios 计算器。该账户必须已启用 Mercado Envios。包裹根据该账户中配置的发货地址报价。您需要生产环境访问令牌（以 APP_USR- 开头）：在 Mercado Pago Developers 中打开您的应用程序及其生产凭据。没有登录按钮：您需要将令牌粘贴到扩展设置中。如果只使用按国家的价格，则无需 Mercado Pago 账户。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
下载文件是一个 zip 文件，内含两个 OpenCart 版本的安装包。请在您的电脑上解压。其中包含 README.txt、OpenCart 3 安装包 vfd_mercado_envios-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 vfd_mercado_envios.ocmod.zip。请只安装与您的 OpenCart 版本对应的安装包。两个版本的许可证密钥相同。
OpenCart 3
1. 在后台依次进入 Extensions > Installer，点击 Upload，选择文件 vfd_mercado_envios-oc3-(version).ocmod.zip。该扩展不添加 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用 Installer，而是将软件包中 upload 文件夹的内容复制到商店的根目录。
2. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Mercado Envios，点击 Install（绿色的 + 按钮）。
3. 点击 Edit（铅笔按钮）打开设置页面。
4. 在 Edit 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入 License key 字段，然后点击 Activate（参见许可证密钥）。
5. 如需实时费率，请粘贴访问令牌，选择 Mercado Envios 国家，并且如果商店的默认货币不是 ARS、BRL 或 MXN，请设置汇率。可选填写 Country prices 和 Fallback cost（在没有实时费率时使用）。开启 Enable Mercado Envios shipping，然后点击 Save。
OpenCart 4
1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_mercado_envios.ocmod.zip。请不要重命名该文件：OpenCart 4 会从文件名获取扩展代码，重命名后的安装包无法使用。
2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色的 + 按钮）。
3. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Mercado Envios，点击 Install（绿色的 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按照 OpenCart 3 步骤 4 和 5 的方式输入许可证密钥和设置。两个版本的设置页面及其字段相同。
安装后，在您开启 Enable Mercado Envios shipping 并保存之前，该方式保持关闭。如果您卸载后重新安装该扩展，之前保留的设置将再次使用。
配置
所有设置都在扩展页面中：Extensions > Extensions > Shipping > VibeFox Mercado Envios > Edit。各部分列在左侧。点击一次 Save 即可保存整个页面，无需重新加载。每次保存还会清除缓存的 Mercado Envios 费率和最近一次 API 错误。只有对该扩展拥有修改权限的管理员用户才能保存设置。
General 部分中的警告（以及每次保存后）会显示配置问题：缺少汇率、没有访问令牌和价格（此时该方式永远不会显示）、最近一次 Mercado Envios API 错误及其日期，以及扩展无法识别的商店重量或长度单位（此时会按 kg 或 cm 解读）。如果 Name 为空或超过 64 个字符，Exchange rate 不是正数，其他数字字段不是 0 或更大的数字，或 Min weight 大于 Max weight，页面会显示错误，且不会保存任何内容。
常规
顾客只会看到一个 Mercado Envios 费率。您可以在 Availability 中将该方式限定为某个地理区域或某些国家。这些设置适用于所有区域。
Enable Mercado Envios shipping: 在结账时显示或隐藏 Mercado Envios。默认：关闭。
Name: 在购物车和结账时向顾客显示的配送方式名称。默认：Mercado Envios。必填，最多 64 个字符。
Tax class: 运费的税类，或 No tax（默认）。Mercado Envios 报出的是最终价格。No tax 按报价显示；选择税类后，会在此基础上加上您的运费税。
Sort order: Mercado Envios 在结账时的配送方式中的排列位置。整数。
Mercado Envios API（实时费率）（没有令牌时仅使用下面的价格）
Access token: 您的 Mercado Pago 生产环境访问令牌（APP_USR-...）。它仅发送至 api.mercadopago.com，且从不记录日志。保存后，该字段保持为空，并显示 Saved — leave empty to keep it. 仅在需要更改时才输入新值。
Remove the saved access token: 开启并保存即可删除已保存的令牌。此时仅使用下面的价格。在上方输入的令牌则会替换已保存的令牌。
Mercado Envios country: 您的 Mercado Pago 账户所在国家：Argentina (ARS)（默认）、Brazil (BRL) 或 Mexico (MXN)。实时费率仅针对该国的目的地请求，并以该国货币报价。
Exchange rate: 仅当商店默认货币与 Mercado Envios 货币不同时需要：1 ARS、BRL 或 MXN 以商店默认货币计的价格，例如 0.001。没有汇率，将不使用实时费率。必须为正数。小数点和逗号都可以作为小数分隔符。
无实时费率时的价格
当没有访问令牌、目的地位于 Mercado Envios 国家之外，或 API 未提供费率时（失败的请求 5 分钟后重试），将使用这些价格。价格以商店默认货币计，不含税。
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。Price 为 0 表示向该国家免运费。9.99 和 9,99 均可接受。非数字的值会在保存后提示并清除。保存时会删除没有任何价格的行。
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。留空表示 25 kg，0 表示无限制。
Minimum subtotal: 仅当需要配送的商品小计（使用优惠券后、税前）至少达到该金额时才显示该方式。留空则始终显示。
Geo zone: 仅为该地理区域内的地址提供 Mercado Envios。All zones（默认）表示无限制。开启 Ignore shipping zones 时不检查地理区域。地理区域在 System > Localisation > Geo Zones 中管理。
Ignore shipping zones: 无论选择哪个地理区域，都为下面列出的国家提供该方式。
Countries: 该模式下的目的国家。留空则使用商店所有已启用的国家。仅当开启 Ignore shipping zones 时才会使用此字段。
免运费
Free shipping from: 需要配送的商品小计（使用优惠券后、税前）达到该金额时，该方式免运费。这种情况下不会发出 API 请求。留空则禁用。
高级
Debug log: 将 API 请求和费率计算写入 storage/logs/vfd_mrcv_debug.log.php（在 OpenCart 4 中为 system/storage/logs/vfd_mrcv_debug.log.php）。该文件无法通过网页读取。即使关闭此选项，错误也始终会被记录。访问令牌和顾客地址从不记录。文件达到 5 MB 时，会移至 vfd_mrcv_debug.old.log.php，并开始新的日志。
Log: 显示调试日志的大小和最新条目。点击 Clear log 可清空。
Remove data on uninstall: 开启时，卸载扩展会删除设置和日志。关闭时（默认），它们会保留以便重新安装。缓存的费率始终会被删除。已下订单的 Mercado Envios 数据始终作为订单历史保留。
导入 / 导出
Export: 点击 Download JSON 将设置保存为 JSON 文件。访问令牌不会被导出。
Import: 粘贴之前导出的 JSON，然后点击 Import 恢复设置，例如在另一个商店中。这些值会像普通保存一样进行检查。已保存的访问令牌会保留。
结账时的工作方式
OpenCart 显示配送方式时，会向扩展请求 Mercado Envios 价格。如果设置了 Geo zone，且地址在其之外，则不提供 Mercado Envios（除非开启 Ignore shipping zones；此时由 Countries 决定）。只有将 Requires Shipping 设为 Yes 的商品才会计入：其他商品不增加重量，也不计入小计。然后扩展会检查购物车重量和最低小计。小计是需要配送的商品价格，在扣除优惠券折扣后、税前。礼品卡、奖励积分和商店余额不计入。如果适用免运费，价格为 0，并且不会向 Mercado Envios 发出请求。
对于 Mercado Envios 国家内、邮政编码有效的目的地（阿根廷为 4 位数字，也可以是如 C1425ABC 之类的 CPA；巴西为 8 位数字；墨西哥为 5 位数字），扩展会将购物车描述为一个包裹：商品中最大的宽度和长度、所有商品高度之和以及以克为单位的总重量。商品的重量和尺寸将从 OpenCart 的重量和长度单位转换而来。每条边和重量都会提高到该国 Mercado Envios 的最低要求，因此没有尺寸或重量的商品也能获得费率。购物车金额以 Mercado Envios 货币作为商品价格发送。Mercado Envios 返回的最便宜选项将换算为商店默认货币，按其小数位取整，并以顾客的货币显示，同时加上所选 Tax class 的税费。
每个报价最多缓存 1 小时（不超过 OpenCart 的缓存时长），因此同一购物车不会触发新请求。失败的报价 5 分钟内不会重复。如果无法连接 Mercado Pago、它拒绝令牌、限制请求或以其他货币回复，所有实时报价将暂停 5 分钟，以免结账在每次刷新时都等待 API。API 超时时间为 10 秒。
当没有令牌、目的地在 Mercado Envios 国家之外、邮政编码缺失或无效、缺少汇率、包裹超过该国 Mercado Envios 的重量上限（阿根廷 25 kg，巴西 15 kg，墨西哥 30 kg），或 Mercado Envios 对该地址返回错误或没有任何选项时，将改用不含实时费率的价格。使用该国家的行（或 * 行），否则使用备用费用。如果没有价格，该方式将被隐藏。顾客永远不会看到 API 错误。
在 OpenCart 4 中，顾客在结账页的配送方式区块中点击 Choose，并在 Shipping method options 窗口中选择 Mercado Envios。该方式的工作方式与 OpenCart 3 相同。
该扩展仅计算费率。它不创建运单、不打印标签、不跟踪包裹。请在您的 Mercado Libre 或 Mercado Pago 账户中创建运单。它显示一个价格，即最便宜的 Mercado Envios 选项，而不是在所有选项之间选择，并且没有自提点（代理点）选择器。
订单
当订单以 Mercado Envios 实时费率下单时，扩展会保存服务名称、以天为单位的预计送达时间以及实时费率。在 Sales > Orders 中，订单页面会显示一个 Mercado Envios 区块，包含 Mercado Envios service、Estimated delivery 和 Live rate (excl. tax)。即使之后禁用了该方式，该区块仍会显示。已注册的顾客会在其账户的订单页面中，于配送方式下方看到 Mercado Envios service 和 Estimated delivery，同样的行也会添加到新订单电子邮件中。使用表格价格或备用费用下的订单没有服务信息。已有订单不受之后费率变化的影响。
在 OpenCart 4 中，Mercado Envios 区块显示在 History 上方。OpenCart 4 为结账保留一个订单，并在顾客每次重新确认时更新它：已保存的服务会随之更新；当顾客切换到其他配送方式或订单获得表格价格或备用费用时，该服务会被移除。
许可证密钥
该扩展需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Mercado Envios 是 Extensions > Extensions > Shipping > VibeFox Mercado Envios > Edit 页面中位于设置上方的第一个区块。在 License key 中输入密钥，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期以及您的域名），并提供以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店移除密钥）。其下方是 Product: opencart-shipping-mercado-envios 一行，以及 Manage licenses and domains in your account 链接，该链接会打开您的 vibefox.net 账户。只有对该扩展拥有修改权限的管理员用户才能更改密钥。区块的文字跟随后台语言显示（包括英文和俄文）。
如果密钥未被接受，该区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或带有日期的 License expired on。在店铺地址更改后，或在您的账户中释放了域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展将继续使用最后已知的状态运行。
一个密钥只能用于一个域名：即 OpenCart 配置中的商店地址。从商店中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。
如果没有有效的密钥，Mercado Envios 配送方式不会在结账时显示给顾客，也不会计算费率。在后台同一浏览器中登录的管理员用户仍能在店铺中看到该方式，并标记为 (unlicensed — visible to admins only)，因此您可以在购买密钥之前完成设置和测试。在 OpenCart 4 中没有此预览功能：店铺无法识别后台登录状态，因此没有有效密钥时，该方式对所有人都隐藏。打开一次 Edit 页面后，后台 Dashboard 会出现提醒。点击 × 关闭，可隐藏 7 天。现有订单不受影响。
许可证到期后，扩展仍会继续运行，但更新和支持需要续费。当您打开后台 Dashboard 或 Edit 页面时会自动再次检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展总会删除许可证密钥和许可证状态。
故障排除
结账时没有显示 Mercado Envios：检查许可证是否有效，以及 Enable Mercado Envios shipping 是否已开启。检查 Geo zone，或开启 Ignore shipping zones 并检查 Countries。检查扩展页面上的警告、重量限制和 Minimum subtotal。该方式需要一个价格：对 Mercado Envios 国家地址有效的访问令牌，或 Country prices 或 Fallback cost。检查商品的 Requires Shipping 是否设为 Yes。
实时费率不显示：开启 Debug log，重新加载结账页面，并查看扩展页面上的 Log 字段。常见原因：没有令牌、目的地在 Mercado Envios 国家之外、邮政编码缺失或无效、缺少 Exchange rate、包裹超过重量上限，或该地址没有 Mercado Envios 选项。
警告中出现 HTTP 401 或 403：访问令牌无效或已过期。请从 Mercado Pago Developers 重新复制生产环境 Access Token。
Mercado Envios 以其他货币回复：账户所在国家与 Mercado Envios country 不符。请选择您的 Mercado Pago 账户所在国家。
价格使用哪种货币：Country prices、Fallback cost 和阈值均以商店默认货币计。实时费率以您 Mercado Pago 账户的货币返回，当商店使用其他默认货币时，将通过 Exchange rate 换算。
更改后费率看起来已过时：在扩展页面上点击 Save。这将清除缓存的费率。
页面显示 "Warning: You do not have permission to modify VibeFox Mercado Envios!"：您的管理员用户组可能只能查看设置。请在 System > Users > User Groups 中为该组授予对 extension/shipping/vfd_mercado_envios（OpenCart 3）或 extension/vfd_mercado_envios/shipping/vfd_mercado_envios（OpenCart 4） 的修改权限。
开发者：Mercado Envios API 地址可以通过设置 vfd_mrcv_api_url（用于测试）替换；设置页面上没有该字段。
卸载
进入 Extensions > Extensions，选择类型 Shipping，然后点击 VibeFox Mercado Envios 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会重置 Enable Mercado Envios shipping、Sort order、Tax class 和 Geo zone。缓存的费率和最近一次 API 错误始终会被删除。如果开启了 Remove data on uninstall，其他设置和调试日志也会被删除。如果关闭，它们会保留，并在您重新安装扩展时再次使用。已下订单的 Mercado Envios 数据始终保留，现有订单保留其配送方式和费用。
在 OpenCart 4 中，如需同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox Mercado Envios 旁边的 Uninstall（橙色的 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。
Mercado Envios 和 Mercado Pago 是各自所有者的商标。本扩展与 Mercado Envios 或 Mercado Pago 无关联，也未获其认可。