VibeFox Melhor Envio for PrestaShop — 帮助
系统要求
PrestaShop:8.0 至 9.x。
PHP:8.0 或更高版本。在较旧的 PHP 版本上，模块会拒绝安装。
Melhor Envio 账户（仅用于实时报价）:实时报价需要访问令牌。在您的 Melhor Envio 账户中打开令牌页面（melhorenvio.com.br/painel/gerenciar/tokens），生成一个具有“shipping-calculate”权限的令牌。测试时，请在 Melhor Envio 沙盒中生成令牌（sandbox.melhorenvio.com.br/painel/gerenciar/tokens）。正式环境和沙盒的令牌不同。没有“连接”按钮：您需要将令牌粘贴到模块设置中。没有令牌时，承运商使用备用价格。
VibeFox 许可证密钥:在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox Melhor Envio，然后点击 Configure。
3. 在 Configure 页面顶部的许可证区块中的 License key 处粘贴您的 VibeFox 许可证密钥，然后点击 Activate（参见“许可证密钥”）。
4. 粘贴访问令牌、您的联系邮箱和发货地 CEP。如果您商店的默认货币不是 BRL，请设置 BRL exchange rate。可以选择填写备用价格表（例如针对巴西）或备用费用。点击 Save。
安装时，模块会创建 Melhor Envio 承运商，配送时间文字为 Delivery by the carriers of your Melhor Envio account。该承运商会分配给所有区域和所有顾客组。您可以在 Shipping > Carriers 中更改区域、顾客组、配送时间、Logo 和尺寸限制。请不要在那里设置价格：价格始终来自模块。
配置
所有设置都在模块页面中：Modules > Module Manager > VibeFox Melhor Envio > Configure。这些设置适用于承运商的每个区域。每个部分都有自己的 Save 按钮，点击后会保存整个页面。每次保存也会清除缓存的 Melhor Envio 报价和最近一次 API 错误。
页面顶部的警告会提示设置不完整：发货地 CEP 为空或不是 8 位数字、缺少联系邮箱、缺少 BRL 汇率、Melhor Envio 最近一次 API 错误（含日期）、没有令牌、没有备用价格（此时承运商将始终不显示），或者商店使用了模块无法识别的重量或尺寸单位（此时会被当作千克或厘米）。如果数字字段中的内容不是 0 或更大的数字，Min weight 大于 Max weight，或者 Default product size 不是长 x 宽 x 高的格式，页面会显示错误，且不会保存任何内容。
General
Enable Melhor Envio shipping:开启或关闭该承运商。这与 Shipping > Carriers 中承运商状态使用的是同一个开关。
Name:结账时顾客看到的承运商名称。默认：Melhor Envio。必填，最多 64 个字符。
Tax:承运商的税务规则，或 No tax。Melhor Envio 的价格是承运商的最终价格。如果不希望 PrestaShop 对其加税，请选择 No tax。
Melhor Envio API
Access token:下方所选环境的令牌。它以 Bearer 令牌的形式发送给 Melhor Envio。保存后，该字段保持为空，并显示 A token is saved — leave empty to keep it. 只有在需要更改时才输入新令牌。要删除已保存的令牌，请勾选 Remove the saved token 并保存。令牌绝不会写入日志。
Sandbox:测试时使用 Melhor Envio 沙盒（sandbox.melhorenvio.com.br）。需配合沙盒令牌使用。默认：关闭。
Contact e-mail:技术联系邮箱，会在每次请求的 User-Agent 标头中发送给 Melhor Envio。Melhor Envio 要求所有集成都提供该邮箱。无效地址不会被保存，并会有提示。
Origin CEP:包裹的发货地 CEP（8 位数字），例如 01310-100。保存格式为 00000-000。没有有效的发货地 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。未设置时，不会使用实时报价。该值必须大于 0。申报价值会按相同汇率换算为 BRL。如果您的默认货币是 BRL，该字段会显示 Store currency is BRL。
Default product weight:以千克为单位，用于没有重量的商品，同时用于报价和重量限制。必须大于 0。默认：0.3。
Default product size:长 x 宽 x 高，单位为厘米，用于没有尺寸的商品。默认：16x11x5。
备用价格（以您商店的默认货币计）
当没有令牌、缺少目的地 CEP，或 API 没有给出报价（出错、超时、无覆盖范围）时，使用备用价格。
Fallback price table:按国家和购物车重量划分的价格。点击 Add country 添加一行，点击垃圾桶图标删除一行。对于没有单独行的国家，请选择 * Default 作为国家。每行都有一个 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 的报价本身已包含所有商品。
可用性
Min weight:购物车重量低于此值时隐藏该承运商，单位为千克。0 表示无限制。
Max weight:购物车重量高于此值时隐藏该承运商，单位为千克。默认：30。0 表示无限制。字段为空时，在承运商的区域中为 30 kg；仅对不在这些区域内的 Ignore shipping zones 国家不设限制。
Minimum subtotal:仅当购物车小计（需要配送的商品，折扣之后、税费之前）不低于此金额时才显示该承运商。留空则始终显示。
Free shipping from:购物车小计达到此金额即免运费。使用“每项服务一个选项”时，只有最便宜的服务免运费，较快的服务保持原价。留空则禁用此功能。
Ignore shipping zones:即使承运商未分配到下方国家所在的区域，也为这些国家提供该承运商。开启时，承运商会关联到所有区域，包括未启用的区域和之后创建的区域。关闭后，承运商会恢复其自有区域。
Countries:该模式下的目的地国家。留空则适用于所有国家。仅当 Ignore shipping zones 开启时，此字段才会使用。
高级
Debug log:将 API 请求和运费计算写入模块文件夹中的 logs/vfd_menv_debug.log.php。该文件无法通过网页打开。即使此选项关闭，错误也始终会被记录。令牌绝不会写入日志，顾客的 CEP 会被缩短为前 5 位数字。
Log:显示调试日志的大小和最新记录。点击 Clear log 可将其清空。
Remove data on uninstall:开启时，卸载模块会删除所有模块设置、承运商和日志。关闭时，所有内容都会保留，以便重新安装。报价缓存始终会被删除。随订单保存的服务属于订单历史，会被保留。
结账时的工作方式
在配送步骤，PrestaShop 会向模块请求 Melhor Envio 的价格。只有需要配送的商品才会计入：虚拟商品不增加重量，也不计入小计。模块首先检查条件：Ignore shipping zones 的国家、购物车重量和最低小计。
对于巴西的配送地址，且 CEP 为 8 位数字，模块会向 Melhor Envio 发送发货地和目的地 CEP，以及每件可配送商品的重量、尺寸、数量和申报价值；如果您设置了服务列表，也会一并发送。报价会换算为您的默认货币，按价格排序，然后以顾客购物车的货币显示。如果适用免运费，最便宜的服务价格为 0。
使用 One option - the cheapest service 时，承运商显示最便宜服务的价格；如果启用了 Delivery time，承运商下方还会显示 Delivery estimate: 一行。使用 One option per service 时，顾客会在承运商下方看到 Choose a delivery service:，其中每项服务都有一个单选按钮，并显示其价格和配送时效估计。选择会立即保存，承运商价格和购物车摘要随之更新。如果该地址不再提供所选服务，顾客会看到 This service is not available for your address any more. Please choose another one.，并恢复之前的选择。
每个报价会按包裹、CEP、令牌和环境分别缓存 1 小时，因此同一购物车不会触发新的请求。失败的调用会记住 5 分钟，因此 API 故障不会拖慢每次结账页面刷新。API 超时时间为 12 秒。
如果没有令牌、地址在巴西境外或尚无有效的 CEP、缺少 BRL 汇率，或 Melhor Envio 返回错误或该路线没有服务，则使用备用价格：该国家的行（或 * 行），否则使用备用费用。如果适用免运费，即使没有价格，承运商也会以免费形式显示。如果根本没有价格，承运商会被隐藏。顾客永远不会看到 API 错误。
如果您在订单产生后，在 Shipping > Carriers 中编辑该承运商，PrestaShop 会将其保存为新的承运商版本。模块会自动跟随新版本。
模块只计算价格。它不购买或生成运单，不会将发货添加到 Melhor Envio 购物车，不跟踪包裹，不安排取件，也不发送发票（NF-e）数据。它不提供 Jadlog、Azul 或 LATAM 网点（投递点）的选择，也不提供“亲手交付”和“回执”等附加服务。请在您的 Melhor Envio 面板中管理发货。Melhor Envio 仅在巴西境内配送。其他国家只使用备用价格。
订单
当订单使用实时报价下单时，模块会将 Melhor Envio 服务及其配送时效估计与订单一同保存。后台订单页面会显示一个 Melhor Envio 区块，其中包含 Melhor Envio service（含服务 ID）和 Delivery estimate，方便您知道应在 Melhor Envio 中购买哪项服务。顾客在其账户的订单页面中也能看到相同的信息。这些信息会在订单确认邮件中添加在承运商名称之后。使用备用价格下单的订单没有服务信息。现有订单不受影响。
许可证密钥
模块需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Melhor Envio 是 Modules > Module Manager > VibeFox Melhor Envio > Configure 页面中的第一个区块，位于设置上方。将密钥粘贴到 License key 中，然后点击 Activate。此后，该区块会显示隐藏部分字符的密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺中移除密钥）。它们下方是 Product: presta-shipping-melhor-envio 一行和 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 账户中释放名额。
没有有效密钥时，结账时不会向顾客显示 Melhor Envio 承运商，也不会计算报价。PrestaShop 前台不知道您已登录后台，因此该承运商对您也会被隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 中的 Alerts 选项卡会显示提醒。现有订单不受影响。
许可证过期后，模块仍会继续运行，但更新和支持需要续期。您在后台工作时会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时没有显示 Melhor Envio:请检查许可证是否有效，以及 Enable Melhor Envio shipping 是否已开启。在 Shipping > Carriers 中，检查承运商是否覆盖顾客所在国家的区域和顾客组；或者开启 Ignore shipping zones 并检查 Countries。检查模块页面顶部的警告、重量限制和 Minimum subtotal。没有令牌或报价时，承运商需要备用价格：Fallback price table 中的一行，或 Fallback cost。此外，商品页面中也可能将商品限制为特定承运商。
只显示备用价格:开启 Debug log，重新加载结账页面，并查看模块页面上的 Log 字段。常见原因：没有令牌、发货地 CEP 不是 8 位数字、默认货币不是 BRL 却没有设置 BRL exchange rate、尚无目的地 CEP，或没有任何服务覆盖该路线。
日志或警告中出现 HTTP 401 或 403:Melhor Envio 拒绝了访问令牌。令牌错误、已过期或已被撤销，或者它属于另一个环境。请生成新令牌，并检查 Sandbox 设置是否与之匹配。
顾客看到“The service could not be saved. Please try again.”:选择未能到达商店，例如因为网络错误。顾客可以重新选择服务。顾客点击 Continue 时所选的服务也会被保存。
Melhor Envio 价格上被加了税:将 Tax 设为 No tax。
更改后报价看起来过时:在模块页面上点击 Save。这会清除缓存的报价。
页面提示找不到 Melhor Envio 承运商:该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块以重新创建。
卸载
进入 Modules > Module Manager，打开 VibeFox Melhor Envio 旁边的菜单，然后选择 Uninstall。许可证密钥和许可证状态始终会被删除。报价缓存始终会被删除。如果 Remove data on uninstall 已开启，承运商会被删除（订单保留历史记录），其自有区域会被恢复，设置、打开的购物车中的服务选择以及日志都会被删除。如果已关闭，承运商仅会被停用，所有设置都会保留。重新安装模块后，承运商会恢复到之前的状态。随订单保存的服务始终会被保留。
Melhor Envio 是其各自所有者的商标。本模块与 Melhor Envio 无关联，也未获得其认可。