VibeFox Melhor Envio for OpenCart — 帮助
系统要求
OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP：8.0 或更高版本。
Melhor Envio 账户（仅用于实时报价）：实时报价需要访问令牌。在您的 Melhor Envio 账户中打开令牌页面（melhorenvio.com.br/painel/gerenciar/tokens），生成一个带有“shipping-calculate”权限的令牌。如需测试，请在 Melhor Envio 沙盒（sandbox.melhorenvio.com.br）中生成令牌。正式环境与沙盒的令牌不同。没有“连接”按钮：您需要将令牌粘贴到扩展的设置中。没有令牌时，该配送方式使用备用价格。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
下载文件是一个 zip 文件，内含两个 OpenCart 版本的安装包。请在您的电脑上解压。其中包含 README.txt、OpenCart 3 安装包 vfd_melhor_envio-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 vfd_melhor_envio.ocmod.zip。请只安装与您的 OpenCart 版本对应的安装包。两个版本的许可证密钥相同。
OpenCart 3
1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_melhor_envio-oc3-(version).ocmod.zip。本扩展不添加任何 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用 Installer，而是将本安装包中 upload 文件夹的内容复制到店铺的根目录。
2. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Melhor Envio，点击 Install（绿色的 + 按钮）。
3. 点击 Edit（铅笔按钮）打开设置页面。
4. 在 Edit 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥粘贴到 License key，然后点击 Activate（参见许可证密钥）。
5. 粘贴访问令牌、联系邮箱和发货 CEP。如果店铺的默认货币不是 BRL，请设置 BRL exchange rate。可选择填写备用价格表（例如针对巴西）或备用运费。开启 Enable Melhor Envio shipping 并点击 Save。
OpenCart 4
1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_melhor_envio.ocmod.zip。请不要重命名该文件：OpenCart 4 会从文件名获取扩展代码，重命名后的安装包无法使用。
2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色的 + 按钮）。
3. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Melhor Envio，点击 Install（绿色的 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按照 OpenCart 3 步骤 4 和 5 的方式输入许可证密钥和设置。两个版本的设置页面及其字段相同。
安装后，该配送方式处于关闭状态，直到您开启 Enable Melhor Envio shipping 并保存。如果您在卸载后重新安装本扩展，将重新使用您保留的设置。
配置
所有设置均位于扩展页面：Extensions > Extensions > Shipping > VibeFox Melhor Envio > Edit。各分区列在左侧。一个 Save 按钮可保存整个页面，无需重新加载。每次保存还会清除缓存的 Melhor Envio 报价和最后一次 API 错误。只有拥有本扩展修改权限的管理员用户才能保存设置。
页面顶部（以及每次保存后）的警告会提示配置不完整的情况：发货 CEP 为空或不是 8 位数字，缺少联系邮箱，缺少 BRL 汇率，没有令牌且没有备用价格（此时该配送方式永远不会显示），显示最后一次 Melhor Envio API 错误及其日期（当已保存令牌时），或者店铺没有单位为 “kg” 的重量类别或单位为 “cm” 的长度类别（此时单位按名称换算，未知单位分别按 kg 或 cm 计算）。如果 Name 为空、过长或包含字符 < > ; = # { }，数字字段中有不是 0 或更大数字的内容，Min weight 大于 Max weight，或 Default product size 不是长 x 宽 x 高的格式，页面会显示错误，并且不保存任何内容。
常规
设置适用于所有地理区域。您可以在 Availability 中将该方式限制在某个地理区域。价格始终来自本扩展。
Enable Melhor Envio shipping：在结账页显示或隐藏 Melhor Envio。默认：off。
Name：顾客在购物车和结账页看到的配送方式名称。默认：Melhor Envio。必填，最多 64 个字符。
Sort order：Melhor Envio 在结账页配送方式中的位置。整数。
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）。使用沙盒令牌。默认：off。
Contact e-mail：技术联系邮箱，会在每个请求的 User-Agent 标头中发送给 Melhor Envio，例如 tech@example.com。Melhor Envio 要求每个集成都提供此邮箱。无效的地址不会被保存，并会显示提示。
Origin CEP：包裹发出地的 CEP（8 位数字），例如 01310-100。OpenCart 没有店铺邮政编码，因此实时报价需要此字段。不是 8 位数字的 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)”。默认：on。
Declared value：在报价中申报商品价值（保险）。关闭时，报价不申报价值：更便宜，但包裹没有保险。默认：on。
BRL exchange rate：Melhor Envio 以巴西雷亚尔报价。仅当店铺的默认货币不是 BRL 时才需要：以您的默认货币输入 1 BRL 的价格，例如 0.17。不设置时，不会使用实时报价。该值必须大于 0。申报价值会以相同汇率换算为 BRL。如果您的默认货币是 BRL，此字段会说明直接使用 Melhor Envio 的价格。
Default product weight (kg)：用于没有重量的商品，既用于报价，也用于重量限制。必须大于 0。默认：0.3。
Default product size (cm)：长 x 宽 x 高，用于没有尺寸的商品。默认：16x11x5。
备用价格（以您店铺的默认货币计价）
当没有令牌、缺少目的地 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，Price 为 0 表示免运费。“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 (kg)：购物车重量低于此值时隐藏该方式。0 表示不限制（默认）。
Max weight (kg)：购物车重量高于此值时隐藏该方式。默认：30。0 表示不限制。留空表示 30 kg，或在 Ignore shipping zones 开启时不限制。
Minimum subtotal：仅当购物车小计（需要配送的商品，使用优惠券后，税前）至少达到此金额时才显示该方式。留空则始终显示。
Free shipping from：购物车小计达到此金额后免运费。使用“每项服务一个选项”时，只有最便宜的服务免费，较快的服务保持原价。留空则禁用此功能。
Tax class：在运费之上加收的税类，或 No tax（默认）。Melhor Envio 的价格是承运商的最终价格。如果不希望 OpenCart 对其加税，请选择 No tax。
Geo zone：仅向该地理区域内的地址提供 Melhor Envio。All zones（默认）表示不限制。地理区域在 System > Localisation > Geo Zones 中管理。当 Ignore shipping zones 开启时，不检查地理区域。
不使用配送区域时的可用性
通常，该方式会在 Availability 中选择的地理区域内提供（未选择时为所有区域）。
Ignore shipping zones：无论所选地理区域是什么，都为下方列出的国家提供该方式。此模式下不检查地理区域。
Countries：此模式下的目的国家。留空表示所有国家。此字段仅在 Ignore shipping zones 开启时使用。
高级
Debug log：将 API 请求和费率计算写入 storage/logs/vfd_menv_debug.log.php（在 OpenCart 4 中为 system/storage/logs/vfd_menv_debug.log.php）。该文件无法通过网页读取。即使此选项关闭，API 错误也始终会被记录。令牌绝不记录，顾客的 CEP 只记录前 5 位。当文件达到 5 MB 时，会被移动到 vfd_menv_debug.old.log.php，并开始新的日志。
Log：显示调试日志的大小和最新条目。点击 Clear log 可清空。
Remove data on uninstall：开启时，卸载本扩展会删除所有扩展设置和日志。关闭（默认）时，它们会被保留，以便重新安装。报价缓存始终会被删除。随订单保存的服务属于订单历史的一部分，会被保留。
导入 / 导出
Export：点击 Download JSON 将设置保存为 JSON 文件。访问令牌不会被导出。
Import：粘贴之前导出的 JSON，然后点击 Import 恢复设置，例如在另一家店铺中使用。这些值会像普通保存一样进行校验。已保存的访问令牌会被保留。
结账时的工作方式
OpenCart 显示配送方式时，会向本扩展请求 Melhor Envio 的价格。如果设置了 Geo zone 且地址不在该区域内，则不提供 Melhor Envio。开启 Ignore shipping zones 时不检查地理区域：只有当国家在 Countries 中（或 Countries 为空）时才提供 Melhor Envio。只有 Requires Shipping 设为 Yes 的商品才计入：其他商品不增加重量，也不计入小计。随后，本扩展检查购物车重量和最低小计。
对于巴西的收货地址（使用 8 位数字 CEP），本扩展会向 Melhor Envio 发送发货和收货 CEP，以及每件可配送商品的重量、尺寸、数量和申报价值；如果您设置了服务列表，也会一并发送。商品的 Model 会作为商品 ID 发送。出错或没有价格的服务会被跳过。报价会被换算为您的默认货币，按其小数位数取整，按价格排序，并以顾客的货币显示，同时包含所选 Tax class 的税费。如果适用免运费，最便宜的服务费用为 0。
使用 One option - the cheapest service 时，顾客只看到一个选项，例如 Melhor Envio (6-7 business days)。使用 One option per service 时，顾客会看到每项服务一个选项，例如 Melhor Envio: Correios SEDEX (1-2 business days)。只有开启 Delivery time 时才会添加配送时效。
每个报价缓存 1 小时，因此相同的购物车不会触发新的请求。失败的调用会记住 5 分钟，因此 API 中断不会使每次结账刷新都变慢。API 超时时间为 12 秒。
如果没有令牌、地址在巴西以外或尚无有效的 CEP、缺少 BRL 汇率，或者 Melhor Envio 返回错误或该路线没有任何服务，则使用备用价格：该国家的行（如果该国家没有行，则使用 * 行），否则使用备用运费。此类选项只使用 Name 中设置的名称。如果适用免运费，即使没有价格，该方式也会以免费形式显示。如果根本没有价格，则隐藏该方式。顾客永远看不到 API 错误，原因会写入日志。
在 OpenCart 4 中，顾客在结账页的配送方式区块中点击 Choose，并在 Shipping method options 窗口中选择一个 Melhor Envio 选项。选项和价格与 OpenCart 3 相同。
本扩展仅计算价格。它不购买或生成运单标签，不向 Melhor Envio 购物车添加发货单，不追踪包裹，不预约取件，也不发送发票（NF-e）数据。它不提供承运商网点（寄件点）的选择。请在您的 Melhor Envio 后台管理发货。Melhor Envio 仅在巴西境内配送。其他国家只使用备用价格。
订单
OpenCart 会将所选选项的名称保存为订单的配送方式，因此服务和配送时效会显示在订单邮件、顾客账户以及 Sales > Orders 中。
使用实时报价下单时，本扩展还会保存顾客在配送步骤中看到的 Melhor Envio 服务，无需重新请求。Sales > Orders 中的后台订单页面会显示一个 Melhor Envio 区块，包含 Melhor Envio service、Service ID 和 Delivery estimate，方便您知道应在 Melhor Envio 中购买哪项服务。顾客可在其账户的订单页面看到 Melhor Envio service 和 Delivery estimate。使用备用价格下的订单没有服务信息。现有订单不受影响。
在 OpenCart 4 中，Melhor Envio 区块显示在 History 上方。OpenCart 4 为结账保留一个订单，并在顾客每次重新确认时更新它：已保存的服务会随之更新；当顾客切换到其他配送方式或订单获得备用价格时，该服务会被移除。
许可证密钥
本扩展需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Melhor Envio 是扩展的 Extensions > Extensions > Shipping > VibeFox Melhor Envio > Edit 页面中位于设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以遮罩形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺移除密钥）。其下方是 Product: opencart-shipping-melhor-envio 一行，以及打开您 vibefox.net 账户的链接 Manage licenses and domains in your account。只有拥有本扩展 Modify 权限的管理员用户才能更改密钥。该区块的文字跟随后台语言显示（包括英语和俄语）。
如果密钥未被接受，该区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或带有日期的 License expired on。在店铺地址更改后，或在您的账户中释放了域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展将继续使用最后已知的状态运行。
一个密钥只能用于一个域名：即 OpenCart 配置中的店铺地址。从店铺中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
如果没有有效的密钥，Melhor Envio 配送方式不会在结账时显示给顾客，也不会计算费率。在后台同一浏览器中登录的管理员用户仍能在店铺中看到该配送方式，并标记为 (unlicensed — visible to admins only)，因此您可以在购买密钥之前完成设置和测试。在 OpenCart 4 中没有此预览功能：店铺无法识别后台登录状态，因此没有有效密钥时，该配送方式对所有人都隐藏。打开一次 Edit 页面后，后台 Dashboard 会出现提醒。点击 × 关闭，可隐藏 7 天。现有订单不受影响。
许可证到期后，扩展仍会继续运行，但更新和支持需要续费。当您打开后台 Dashboard 或 Edit 页面时会自动再次检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展总会删除许可证密钥和许可证状态。
故障排除
结账时没有显示 Melhor Envio：检查许可证是否有效，并且 Enable Melhor Envio shipping 已开启。检查 Geo zone，或开启 Ignore shipping zones 并检查 Countries。查看扩展页面顶部的警告、重量限制和 Minimum subtotal。如果没有令牌或报价，该方式需要备用价格：Fallback price table 中的一行，或一个 Fallback cost。检查商品的 Requires Shipping 是否设为 Yes。
只显示备用价格：开启 Debug log，重新加载结账页，并查看扩展页面上的 Log 字段。常见原因：没有令牌、发货 CEP 不是 8 位数字、默认货币不是 BRL 但未设置 BRL exchange rate、尚无目的地 CEP，或没有任何服务覆盖该路线。
日志或警告中出现 HTTP 401 或 403：Melhor Envio 拒绝了访问令牌。它可能错误、已过期或已被撤销，或属于另一个环境。请生成新的令牌，并确认 Sandbox 与之匹配。
Melhor Envio 价格上被加了税：将 Tax class 设为 No tax。
修改后报价看起来过时：点击扩展页面上的 Save。这会清除缓存的报价。
页面显示 "Warning: You do not have permission to modify VibeFox Melhor Envio!"：您的管理员用户组只能查看设置。请在 System > Users > User Groups 中为该用户组授予 extension/shipping/vfd_melhor_envio（OpenCart 3）或 extension/vfd_melhor_envio/shipping/vfd_melhor_envio（OpenCart 4）的修改权限。
开发者说明：Melhor Envio 报价地址可以通过设置 vfd_menv_api_url（用于测试）进行替换；该设置在设置页面中没有对应的字段。
卸载
进入 Extensions > Extensions，选择 Shipping 类型，然后点击 VibeFox Melhor Envio 旁边的 Uninstall（红色的 − 按钮）。本扩展的许可证密钥和许可证状态总会被删除。OpenCart 总会重置 Enable Melhor Envio shipping、Sort order、Tax class 和 Geo zone。报价缓存总会被删除。如果 Remove data on uninstall 已开启，其他设置和调试日志也会被删除。如果已关闭，它们会被保留，并在您重新安装本扩展时再次使用。随订单保存的服务总会被保留，现有订单会保留其配送方式和费用。
在 OpenCart 4 中，如需同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox Melhor Envio 旁边的 Uninstall（橙色的 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。
Melhor Envio 是其各自所有者的商标。本扩展与 Melhor Envio 没有关联，也未获得 Melhor Envio 的认可。