VibeFox Mercado Envios for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝在较旧的 PHP 版本上安装。
Mercado Pago 账户（仅用于实时运费）：实时运费来自您位于阿根廷、巴西或墨西哥的 Mercado Pago 账户中的 Mercado Envios 运费计算器。该账户必须已启用 Mercado Envios。包裹按该账户中设置的发货地址计算运费。您需要生产环境 Access Token（以 APP_USR- 开头）：请在 Mercado Pago 开发者面板中打开您的应用及其生产凭据。没有登录按钮：您需要将令牌粘贴到模块设置中。如果您只使用按国家设置的价格，则无需 Mercado Pago 账户。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者之后在模块列表中找到 VibeFox Mercado Envios，然后点击 Configure。
3. 在 Configure 页面顶部许可证区块的 License key 中输入您的 VibeFox 许可证密钥，然后点击 Activate（参见“许可证密钥”）。
4. 如需实时运费，请粘贴 Access Token，选择 Mercado Envios 国家；如果您店铺的默认货币不是 ARS、BRL 或 MXN，还需设置汇率。您可以选择填写 Country prices 和 Fallback cost（在没有实时运费时使用）。点击 Save。
安装时，模块会创建 Mercado Envios 承运商，其配送时间文本为 Mercado Envios delivery。该承运商会分配给所有区域和所有客户组，且不设置税务规则。您可以在 Shipping > Carriers 中修改区域、客户组、配送时间、Logo 和尺寸限制。请不要在那里设置价格：价格始终来自模块。
配置
所有设置都在模块页面：Modules > Module Manager > VibeFox Mercado Envios > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。每次保存也会清除缓存的 Mercado Envios 运费和最近一次 API 错误。
页面顶部的警告会显示配置问题：缺少汇率、没有 Access Token 也没有价格、带日期的最近一次 Mercado Envios API 错误，以及模块无法识别的店铺重量或尺寸单位（此时按 kg 或 cm 处理）。如果承运商已被删除，General 部分会显示：The Mercado Envios carrier was not found — reset the module to create it again.
General
在 Shipping > Carriers 中为 Mercado Envios 承运商添加客户所在的区域，或者使用下方的 Ignore shipping zones。这些设置适用于每个区域。
Enable Mercado Envios shipping：开启或关闭承运商。这与 Shipping > Carriers 中的承运商状态是同一个开关。
Name：结账时向顾客显示的承运商名称。默认：Mercado Envios。必填，最多 64 个字符。
Tax：承运商的税务规则，或 No tax（默认）。Mercado Envios 给出的是最终价格。No tax 按报价原样显示；税务规则则会在其上加上您的运费税。
Mercado Envios API（实时运费）（没有令牌时，只使用下方的价格）
Access token：您的 Mercado Pago 生产环境 Access Token（APP_USR-...）。它只会发送到 api.mercadopago.com，并且从不写入日志。保存后，该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。若要停止使用实时运费，请勾选 Remove the saved access token (only the prices below are used then) 并保存。
Mercado Envios country：您的 Mercado Pago 账户所属国家：Argentina (ARS)（默认）、Brazil (BRL) 或 Mexico (MXN)。只有目的地位于该国时才会请求实时运费，并以该国货币报价。
Exchange rate：仅当店铺默认货币与 Mercado Envios 货币不同时才需要：以您的默认货币表示的 1 ARS、BRL 或 MXN 的价格，例如 0.001。未设置时不会使用实时运费。必须为正数。小数点和逗号都可以作为小数分隔符。
无实时运费时的价格
这些价格在以下情况使用：没有 Access Token、目的地不在 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。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 kg，0 表示没有限制。保存时会拒绝大于 Max weight 的 Min weight。
Minimum subtotal：仅当购物车小计（折扣后、税前）至少达到此金额时才显示承运商。留空则始终显示。
Ignore shipping zones：无需设置其区域，即可为下方列出的国家提供该承运商。保存时，承运商会被添加到所有区域，之后创建的区域也会自动添加。关闭此选项会删除它添加的区域，承运商保留其自有区域。
Countries：该模式下的目的国家。留空表示店铺所有启用的国家。仅当 Ignore shipping zones 开启时使用此字段。
免运费
Free shipping from：购物车小计（折扣后、税前）达到此金额后，该承运商免运费。此时不会发出 API 请求。留空则禁用。
高级
Debug log：将 API 请求和运费计算写入模块文件夹中的 logs/vfd_mrcv_debug.log.php。该文件无法通过网页打开。即使关闭此选项，错误仍会始终记录。Access Token 和顾客地址从不写入日志。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Remove data on uninstall：开启后，卸载模块会删除设置、承运商、缓存的运费和日志。关闭后，所有内容都会保留，以便重新安装。
结账时的工作方式
在配送步骤，PrestaShop 会向模块请求 Mercado Envios 价格。只有实体商品计入：虚拟商品不增加重量，也不计入小计。模块首先检查条件：允许的国家（使用 Ignore shipping zones 时）、购物车重量和最低小计。如果适用免运费，价格为 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 错误。
如果您在承运商已有订单后，在 Shipping > Carriers 中编辑它，PrestaShop 会将其保存为新的承运商版本。模块会自动跟随新版本。
模块仅计算运费。它不创建运单、不打印面单，也不跟踪包裹。请在您的 Mercado Libre 或 Mercado Pago 账户中创建运单。它只显示一个价格，即最便宜的 Mercado Envios 选项，而不是在所有选项之间选择，并且没有自提点（网点）选择器。
订单
当订单使用实时 Mercado Envios 运费下单时，模块会保存服务名称、以天计的预计送达时间以及实时运费。在后台，订单页面会显示一个 Mercado Envios 区块，包含 Mercado Envios service、Estimated delivery 和 Live rate (excl. tax)。顾客可以在其账户的订单详情页面上看到 Mercado Envios service 和 Estimated delivery。已有订单不受之后运费变化的影响。
许可证密钥
该模块需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Mercado Envios 位于 Modules > Module Manager > VibeFox Mercado Envios > Configure 页面中设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会显示被遮蔽的密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从此店铺中移除密钥）。它们下方是 Product: presta-shipping-mercado-envios 一行和 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 账户中释放该名额。
没有有效密钥时，Mercado Envios 承运商不会在结账时向顾客显示，也不会计算任何运费。PrestaShop 前台无法得知您已登录后台，因此该承运商对您也会隐藏：您可以在购买密钥前设置模块，但无法在结账时测试。Modules > Module Manager 中的 Alerts 选项卡会显示提醒。已有订单不受影响。
许可证到期后，模块仍会继续工作，但更新和支持需要续费。您在后台工作时，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块总会删除许可证密钥和许可证状态。
故障排查
Mercado Envios 没有出现在结账页面：请检查许可证是否有效，以及 Enable Mercado Envios shipping 是否已开启。在 Shipping > Carriers 中，检查承运商是否覆盖顾客所在国家的区域以及顾客所在的客户组（或开启 Ignore shipping zones 并检查 Countries）。检查模块页面顶部的警告、重量限制和 Minimum subtotal。承运商需要有价格：对于 Mercado Envios 国家内的地址，需要有效的 Access Token，或者设置 Country prices 或 Fallback cost。此外，商品页面也可能将商品限制为特定承运商。
实时运费没有出现：开启 Debug log，重新加载结账页面，然后查看模块页面上的 Log 字段。常见原因：没有令牌、目的地不在 Mercado Envios 国家、邮编缺失或无效、缺少 Exchange rate、包裹超过重量限制，或该地址没有 Mercado Envios 选项。
警告中出现 HTTP 401 或 403：Access Token 无效或已过期。请从 Mercado Pago 开发者面板重新复制生产环境 Access Token。
Mercado Envios 以其他货币回复：账户所在国家与 Mercado Envios country 不符。请选择您 Mercado Pago 账户所在的国家。
价格使用哪种货币：Country prices、Fallback cost 和阈值都以店铺默认货币表示。实时运费以您 Mercado Pago 账户的货币返回，当店铺使用其他默认货币时，会通过 Exchange rate 进行换算。
修改后运费看起来过时：在模块页面上点击 Save。这会清除缓存的运费。
页面提示找不到 Mercado Envios 承运商：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块，以重新创建它。
卸载
进入 Modules > Module Manager，打开 VibeFox Mercado Envios 旁边的菜单，然后选择 Uninstall。许可证密钥和许可证状态始终会被删除。缓存的运费始终会被删除。如果 Remove data on uninstall 已开启，承运商会被删除（订单保留其历史记录），并且设置、日志以及订单中保存的服务数据也会被删除。如果已关闭，承运商仅会被禁用，所有设置和订单服务数据都会保留。重新安装模块后，承运商会恢复卸载前的状态。
Mercado Envios 和 Mercado Pago 是其各自所有者的商标。本模块与 Mercado Envios 或 Mercado Pago 无关联，也未获得它们的认可或背书。