VibeFox Frenet for OpenCart — 帮助
系统要求
OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP：8.0 或更高版本。
Frenet 账户（仅用于实时报价）：在 Frenet 面板（painel.frenet.com.br）中创建免费账户，启用您使用的承运商，并复制您的 API 令牌。如果您只使用固定价格，则无需 Frenet 账户。
产品：请填写重量和尺寸，以获得准确的价格。未填写的产品将按 0.3 kg 和 16 × 11 × 2 cm（Correios 最小包装箱）计算报价。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
下载文件是一个 zip 压缩包，内含适用于两个 OpenCart 版本的安装包。请先将其解压到您的计算机上。压缩包包含 README.txt、OpenCart 3 安装包 vfd_frenet-oc3-(version).ocmod.zip 以及 OpenCart 4 安装包 vfd_frenet.ocmod.zip。请只安装与您的 OpenCart 版本对应的安装包。两个版本的许可证密钥相同。
OpenCart 3
1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_frenet-oc3-(version).ocmod.zip。该扩展不添加任何 OCMOD 修改，因此您无需刷新 Extensions > Modifications。您也可以不使用安装器，而是将本安装包中 upload 文件夹的内容复制到商店的根目录。
2. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Frenet，点击 Install（绿色的 + 按钮）。
3. 点击 Edit（铅笔按钮）打开设置页面。
4. 将您的 VibeFox 许可证密钥输入 Edit 页面顶部许可证区块中的 License key，然后点击 Activate（参见许可证密钥）。
5. 粘贴 API 令牌并输入发货 CEP。如果您的默认货币不是 BRL，请输入 BRL 汇率。您可以选择添加固定价格和备用费用。启用 Enable Frenet，然后点击 Save。
OpenCart 4
1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_frenet.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包将无法使用。
2. 安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。
3. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Frenet，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。
4. 请按照 OpenCart 3 第 4 步和第 5 步的方式输入许可证密钥和设置。两个版本的设置页面及其字段相同。
安装后，在您启用 Enable Frenet 并保存之前，该方式保持关闭。如果您卸载后重新安装该扩展，将重新使用您保留的 Frenet 设置。
配置
所有设置均位于扩展页面：Extensions > Extensions > Shipping > VibeFox Frenet > Edit。各分区列在左侧。页面底部的一个 Save 按钮可在不重新加载页面的情况下保存整个页面。每次保存也会清除缓存的 Frenet 报价。价格字段同时接受小数点和逗号作为小数分隔符。如果某个值有误，则不会保存任何内容，页面会显示原因，例如 Enter a valid method title (64 characters max, without < > ; = # { }).、"…" must be a number. 或 "…" must not be negative.。BRL exchange rate 为 0 或更小，以及 Minimum weight (kg) 大于 Maximum weight (kg)，也会被拒绝。只有具备该扩展修改权限的管理员用户才能保存设置。
在页面顶部以及每次保存后，扩展都会显示警告：没有 API 令牌（仅使用固定价格，如果也没有固定价格，则该方式从不显示）、没有发货 CEP、发货 CEP 不是 8 位数字，或默认货币不是 BRL 且没有汇率。如果您的商店没有单位为 kg 的重量类别，或没有单位为 cm 的长度类别，它也会发出警告。此时，商品重量和尺寸将按其类别的单位名称进行换算，无法识别的单位将按 kg 或 cm 处理。请检查 System > Localisation > Weight Classes 和 Length Classes。
常规
这些设置适用于所有地理区域。您可以在 Conditions 中将该方式限制为某个地理区域，或使用 Ignore shipping zones。价格始终来自本扩展。
Enable Frenet：在结账时显示或隐藏 Frenet。默认：关闭。
Method title：客户在购物车和结账时看到的配送方式名称。默认：Frenet。必填，最多 64 个字符，且不能包含字符 < > ; = # { }。
Sort order：Frenet 在结账时配送方式中的位置。一个整数。
Frenet 实时报价
Frenet 会比较您 Frenet 账户中启用的承运商（Correios、Jadlog、Loggi 及其他），并返回它们对购物车的报价。仅对巴西的、带完整 8 位 CEP 的地址请求实时报价。该分区包含一个指向 Frenet 面板的链接。
API token：您在 Frenet 面板中获得的 Frenet API 令牌。如果只使用固定价格，请将其留空。保存后，该字段保持为空，并显示 A token is saved — leave empty to keep it. 只有在要更改时才输入新值。要删除已保存的令牌，请勾选 Remove the saved token 并保存。
Origin CEP：包裹的发出地邮政编码（CEP），例如 01001-000。OpenCart 没有商店邮政编码，因此实时报价需要此字段。不足 8 位数字的 CEP 将按您输入的内容保存，页面会显示 Frenet: the origin CEP must have 8 digits.
Service to offer：Cheapest service（默认）或 Fastest service。Frenet 会返回多项服务，而该方式只显示一个价格。所选的承运商、服务和配送时间会与订单一同保存。
BRL exchange rate：Frenet 以巴西雷亚尔报价。如果您的默认货币不是 BRL，请输入 1 BRL 等于您默认货币的金额，例如 0.16。报价和订单的申报价值将按此汇率进行换算。没有该汇率，则不使用实时报价。当您的默认货币是 BRL 时，该字段会说明直接使用 Frenet 价格。
固定价格
在没有 API 令牌时、针对 Frenet 不服务的国家，以及 Frenet 未返回价格时（API 不可用、CEP 不在服务范围内）使用。
Price per country：一个表格，包含 Country、Price、XS、S、M、L 和 XL 列，价格以您的默认货币计，不含税。点击 Add country 添加一行。尺寸列取决于购物车重量：XS 为 1 kg 以下，S 为 2 kg 以下，M 为 3 kg 以下，L 为 5 kg 以下，XL 为 5 kg 以上。尺寸列为空时使用 Price。Price 为 0 表示该国家免运费。对于没有单独一行的所有其他国家，请使用 * Default (all other countries)。保存时，没有任何价格的行会被删除。
Fallback cost：当 Frenet 和表格都不提供价格时使用。留空则隐藏该方式。
Fixed price applies：Per order（默认）只收取一次价格。Per item (price × quantity) 则将价格乘以商品数量。这仅适用于固定价格和备用费用。Frenet 报价本身已涵盖整个购物车。
条件
Minimum weight (kg)：购物车重量低于此值时隐藏该方式。0 表示无限制。
Maximum weight (kg)：购物车重量高于此值时隐藏该方式。默认：30（字段为空时同样使用此值）。0 表示无限制。不能低于 Minimum weight (kg)。
Minimum order amount：仅当需要配送的商品小计（优惠券折扣后、税前）至少达到此金额时才显示该方式。留空则始终显示。
Free shipping from：免运费的起始小计（优惠券折扣后、税前）。留空则从不提供免运费。
Tax class：添加到运费上的税类，或 No tax。Frenet 价格是承运商的最终价格。如果不希望 OpenCart 对其加税，请选择 No tax。
Geo zone：仅向此地理区域内的地址提供 Frenet。All zones 表示无限制。与 Ignore shipping zones 一起使用时无效。地理区域在 System > Localisation > Geo Zones 中管理。
不使用配送区域时的可用性
通常，该方式会在 Conditions 中选定的地理区域内提供（如果未选择任何区域，则在所有区域提供）。
Ignore shipping zones：无论匹配哪个地理区域，都为下列国家提供 Frenet。此时不会检查 Conditions 中的 Geo zone。
Countries：该模式下的目的地国家，从您商店中已启用的国家中选择。留空则使用您配送的所有国家。仅在 Ignore shipping zones 开启时使用。
高级
Debug log：将每次报价请求和响应记录到 storage/logs/vfd_frn_debug.log.php（OpenCart 4 为 system/storage/logs/vfd_frn_debug.log.php）。该文件无法通过网页读取。API 错误始终会被记录。令牌绝不会被记录，客户的 CEP 会被缩短。使用完毕后请关闭。当文件达到 5 MB 时，它会被移动到 vfd_frn_debug.old.log.php，并开始新的日志。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Remove data on uninstall：开启时，卸载扩展会删除所有 Frenet 设置和日志。关闭时，所有内容都会保留，以便重新安装。缓存的报价始终会被删除。随订单保存的 Frenet 服务属于订单历史，会被保留。
导入 / 导出
Export：点击 Download JSON，将设置保存为 JSON 文件。API 令牌不会被导出。
Import：粘贴之前导出的 JSON，然后点击 Import，即可恢复设置，例如在另一家商店中。这些值会像正常保存一样进行检查。已保存的 API 令牌会被保留。
结账时的工作方式
OpenCart 显示配送方式时，会向扩展请求 Frenet 价格。如果设置了 Geo zone（并且 Ignore shipping zones 处于关闭状态），而地址不在该区域内，则不提供 Frenet。只有 Requires Shipping 设为 Yes 的商品会被计算：其他商品不增加重量，也不计入订单金额。然后，扩展会检查国家列表（如果 Ignore shipping zones 已开启）、购物车重量以及最低订单金额。订单金额是需要配送的商品在扣除优惠券折扣后、税前的价格。如果适用免运费，价格为 0，且不会向 Frenet 发出任何请求。
对于巴西带完整 8 位 CEP 的地址，并且在已设置 API 令牌和发货 CEP 的情况下，扩展会向 Frenet 发送发货和收货 CEP、每件购物车商品（以 kg 计的重量、以 cm 计的尺寸、数量、商品的 Model 及其分类）、以 BRL 计的订单金额，以及购物车的优惠券代码。在 CEP 不完整时不会发出请求。Frenet 会返回您已启用承运商的服务。出错或没有价格的服务会被跳过。扩展会选择最便宜或最快的服务，并将价格换算为您的默认货币。价格会按默认货币的小数位数进行舍入，并以客户的货币显示，同时附加所选 Tax class 的税费。
对于同一购物车和同一地址，每个响应都会缓存 1 小时。失败的请求，或没有任何已启用承运商服务的 CEP，会被记住 10 分钟。API 超时时间为 10 秒。在这些情况下，客户不会看到任何错误：会使用固定价格或备用费用；如果两者都没有，则隐藏该方式。原因会被写入日志。对于巴西以外的地址，仅使用固定价格。
在 OpenCart 4 上，客户在结账页面的配送方式区块中点击 Choose，并在“Shipping method options”窗口中选择 Frenet。该方式的工作方式与 OpenCart 3 相同。
扩展仅计算运费。它不创建发货单、不打印运单，也不跟踪包裹。每个购物车只显示一项 Frenet 服务，而不是多项，并且不提供取件点或储物柜。Frenet 仅提供巴西境内的报价；其他国家请使用固定价格。
订单
通过 Frenet 下单时，扩展会保存其运费的计算方式：即客户在配送步骤中看到的确切选项，而不会向 Frenet 发出新的请求。随后，Sales > Orders 中的订单页面会显示一个 Frenet 区块，其中包含以下几行：
Carrier：Frenet 承运商和服务，例如 Correios 或 Jadlog 的某项服务。实时报价时显示。
Delivery time：Frenet 返回的以工作日计的配送时间。实时报价时显示。
Price source：Live Frenet quote、Fixed price (price per country)、Fallback cost 或 Free shipping。
在 OpenCart 4 上，该区块显示在 History 上方。当客户再次确认订单时，OpenCart 4 会更新同一订单：已保存的 Frenet 数据也会随之更新；如果客户选择了其他配送方式，则会删除该订单的 Frenet 数据。
即使扩展已禁用，该区块仍会显示。卸载扩展时，这些数据会被保留，即使开启了 Remove data on uninstall 也是如此。
许可证密钥
本扩展需要配合一个来自 vibefox.net 的 VibeFox 许可证密钥使用。License — VibeFox Frenet 许可证区块位于 Extensions > Extensions > Shipping > VibeFox Frenet > Edit 页面的最顶部，位于设置上方。请将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），并提供以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（将密钥从本商店中移除）。其下方是 Product: opencart-shipping-frenet 一行，以及 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 账户中释放该名额。
如果没有有效的密钥，Frenet 将不会在结账时显示给客户，也不会计算费率。以同一浏览器登录后台的管理员用户仍会在商店中看到该方式，并标注 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试扩展。在 OpenCart 4 上，此预览功能不可用：商店无法看到后台登录状态，因此在没有有效密钥的情况下，该方式对所有人都隐藏。打开一次 Edit 页面后，后台 Dashboard 上会出现提醒。点击 × 可将其隐藏 7 天。现有订单不受影响。
许可证到期后，扩展仍可继续运行，但更新和支持需要续费。当您打开后台的 Dashboard 或 Edit 页面时，系统会自动再次检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载扩展时，许可证密钥和许可证状态始终会被删除。
故障排除
Frenet 没有出现在结账页面：请检查许可证是否有效，以及 Enable Frenet 是否已开启。检查 Geo zone，或 Ignore shipping zones 和 Countries、重量限制以及 Minimum order amount。查看扩展页面顶部的警告。常见原因：客户尚未输入完整的 8 位 CEP，且没有固定价格；或者 Frenet 未返回该路线的服务，也没有固定价格。请检查商品的 Requires Shipping 是否设为 Yes。
实时报价没有显示：开启 Debug log，刷新结账页面，然后查看扩展页面上的 Log 字段。它会显示原因：没有发货 CEP、没有 BRL 汇率、客户的 CEP 不完整、超出重量或金额限制，或显示被跳过服务的相关信息。
日志显示 API 令牌被拒绝（HTTP 401 或 403）：请从 Frenet 面板重新复制令牌，并粘贴到 API token 中。
日志显示 Frenet 未返回任何服务：请在 Frenet 面板中至少启用一个承运商。
我的商店以欧元或美元销售：Frenet 以 BRL 回复。请输入 BRL exchange rate（1 BRL 等于您默认货币的金额）。
在 Frenet 价格之上又收取了税费：Frenet 价格是承运商的最终价格。请将 Tax class 设为 No tax。
更改后的费率看起来过时了：在扩展页面点击 Save。这会清除缓存的 Frenet 报价。
页面显示 "Warning: You do not have permission to modify VibeFox Frenet!"：您的管理员用户组可能只能查看设置。请在 System > Users > User Groups 中，授予该用户组对 extension/shipping/vfd_frenet（OpenCart 3）或 extension/vfd_frenet/shipping/vfd_frenet（OpenCart 4）的修改权限。
面向开发人员：Frenet 报价地址可以通过设置 vfd_frn_api_url 进行替换（用于测试）；设置页面上没有该项的字段。
卸载
进入 Extensions > Extensions，选择 Shipping 类型，然后点击 VibeFox Frenet 旁边的 Uninstall（红色 − 按钮）。本扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会重置 Enable Frenet、Sort order、Tax class 和 Geo zone。缓存的报价始终会被删除。本扩展的 OpenCart 事件也会被移除（在 OpenCart 4 上，还包括保存新订单 Frenet 数据的事件），因此订单页面上不再显示 Frenet 区块。随订单保存的 Frenet 数据会被保留，并在重新安装后再次显示。如果开启了 Remove data on uninstall，Frenet 设置和调试日志也会被删除。如果关闭，其他设置会被保留，并在您重新安装该扩展时再次使用。现有订单会保留其配送方式和费用。
在 OpenCart 4 上，如需同时删除扩展的文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox Frenet 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。
Frenet 是其各自所有者的商标。本扩展与 Frenet 没有关联，也未获得 Frenet 的认可或背书。