VibeFox Frenet for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块无法安装在更旧的 PHP 版本上。
Frenet 账户（仅用于实时报价）：在 Frenet 面板（painel.frenet.com.br）中创建免费账户，启用您使用的承运商，然后复制您的 API 令牌。如果您只使用固定价格，则无需 Frenet 账户。
商品：填写重量和尺寸以获得准确的价格。未填写的商品将按 0.3 kg 和 16 × 11 × 2 cm（Correios 最小包装箱）报价。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox Frenet，然后点击 Configure。
3. 将您的 VibeFox 许可证密钥粘贴到 Configure 页面顶部许可证区块中的 License key，然后点击 Activate（参见许可证密钥）。
4. 粘贴 API 令牌并输入始发 CEP。如果您的默认货币不是 BRL，请输入 BRL 汇率。可选择添加固定价格和备用运费。点击 Save。
安装时，模块会创建 Frenet 承运商，其配送时间文本为 Delivery by the carriers of your Frenet account。该承运商会分配给所有区域和所有客户组。您可以在 Shipping > Carriers 中修改区域、客户组、配送时间、徽标和尺寸限制。请不要在那里设置价格：价格始终来自模块。
配置
所有设置都位于模块页面：Modules > Module Manager > VibeFox Frenet > Configure。它们适用于承运商的每个区域。每个部分都有各自的 Save 按钮，点击后会保存整个页面。每次保存还会清除缓存的 Frenet 报价。价格字段同时接受小数点和逗号作为小数分隔符；非数字的值会被拒绝，并显示消息 "…" must be a number. 负数金额和重量、值为 0 或更小的 BRL exchange rate，以及大于 Maximum weight 的 Minimum weight 同样会被拒绝。出现错误时，不会保存任何内容。
页面顶部，模块会显示以下警告：没有 API 令牌（仅使用固定价格；如果也没有固定价格，则从不显示该承运商）、没有 8 位数字的始发 CEP，或者默认货币不是 BRL 且未设置汇率。如果您店铺的重量或尺寸单位不被模块识别，也会发出警告；此类单位会按 kg 或 cm 处理。请在 International > Localization（Local units）中设置标准单位（kg、g、lb 或 oz；cm、mm、m 或 in）。
常规
Enable Frenet：开启或关闭承运商。这与 Shipping > Carriers 中的承运商状态是同一个开关。
Method title：在购物车和结账时显示的承运商名称。默认值：Frenet。必填，最多 64 个字符。
Frenet 实时报价
Frenet 会比较您 Frenet 账户中已启用的承运商，并返回它们对购物车的报价。仅当地址位于巴西且 CEP 为完整的 8 位数字时，才会请求实时报价。该部分包含一个指向 Frenet 面板的链接。
API token：您在 Frenet 面板中获取的 Frenet API 令牌。留空则仅使用固定价格。保存后，该字段保持为空，并显示 A token is saved — leave empty to keep it. 只有在需要更改时才输入新值。要删除已保存的令牌，请勾选 Remove the saved token 并保存。
Origin CEP：包裹的发货 CEP（邮政编码），例如 00000-000。如果店铺地址位于巴西，留空则使用 Shop Parameters > Contact > Stores 中的店铺邮编。不足 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 时，该字段显示 Not needed (shop currency is BRL)。
固定价格
在没有 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。保存时会删除没有任何价格的行。
Fallback cost：在 Frenet 和表格都无法提供价格时使用。留空则隐藏该承运商。
Fixed price applies：Per order 只收取一次价格。Per item (price × quantity) 则按商品数量相乘。这仅适用于固定价格和备用运费。Frenet 报价已经涵盖整个购物车。
条件
Minimum weight：购物车重量低于此值时隐藏该承运商，单位为 kg。0 表示不限制。
Maximum weight：购物车重量高于此值时隐藏该承运商，单位为 kg。默认值：30（字段为空时也使用此值）。0 表示不限制。不能低于 Minimum weight。
Minimum order amount：仅当购物车小计（折扣后、税前）至少达到此金额时才显示该承运商。留空则始终显示。
Free shipping from：购物车小计（折扣后、税前）达到此金额时免运费。留空则从不提供免运费。
Tax：承运商的税务规则，或 No tax。Frenet 价格是承运商的最终价格。如果 PrestaShop 不应在其上加税，请选择 No tax。
商品重量和尺寸会从店铺单位换算为 kg 和 cm。
无配送区域时的可用性
通常，承运商只会在 Shipping > Carriers 中分配给它的区域内提供。
Ignore shipping zones：无论匹配哪个区域，都为下列国家提供 Frenet。保存时，承运商会添加到所有区域，之后创建的区域也会自动添加。再次关闭该选项时，承运商会恢复其之前拥有的区域。
Countries：该模式下的目的国家，从您店铺的启用国家中选择。留空则使用您配送的所有国家。仅在 Ignore shipping zones 开启时使用。
高级
Debug log：将每次报价请求和响应记录到模块文件夹中的 logs/vfd_frn_debug.log.php。该文件无法通过网页打开。API 错误始终会被记录。令牌永远不会被记录，客户的 CEP 会被缩短。完成后请关闭。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Remove data on uninstall：开启时，卸载模块会删除所有 Frenet 设置、承运商和日志。关闭时，所有内容都会保留，以便重新安装。缓存的报价始终会被删除。随订单保存的 Frenet 服务属于订单历史，会被保留。
结账时的工作方式
在配送步骤，PrestaShop 会向模块请求 Frenet 价格。只计算实物商品：虚拟商品不增加重量，也不计入订单金额。在客户输入地址之前，模块会使用店铺为访客估计的国家。模块首先检查国家列表（当 Ignore shipping zones 开启时）、购物车重量和最低订单金额。如果适用免运费，价格为 0，并且不会向 Frenet 发送请求。
对于巴西地址且 CEP 为完整的 8 位数字，模块会向 Frenet 发送始发和目的 CEP、购物车中的每个商品（重量单位 kg、尺寸单位 cm、数量、商品编号和分类）、以 BRL 计的订单金额，以及购物车中的第一个优惠券代码。在 CEP 不完整时不会发出请求。Frenet 会返回您已启用承运商的服务。出现错误或没有价格的服务会被跳过。模块选择最便宜或最快的服务，并将价格换算为您的默认货币。之后，价格以客户购物车的货币显示。
每个响应会针对相同的购物车和地址缓存 1 小时。失败的请求，或没有任何已启用承运商可服务的 CEP，会被记录 10 分钟。API 超时时间为 10 秒。在这些情况下，客户不会看到错误：使用固定价格或备用运费，如果都没有，则隐藏该承运商。原因会被写入日志。对于巴西以外的地址，只使用固定价格。
如果承运商已有订单后，您在 Shipping > Carriers 中对其进行了编辑，PrestaShop 会将其保存为新的承运商版本。模块会自动跟随新版本。
模块仅计算运费，不创建发货单、不打印面单、不跟踪包裹。每个购物车只显示一项 Frenet 服务，不会显示多项，也不提供自提点或智能储物柜。Frenet 仅提供巴西境内的报价；其他国家请使用固定价格。
订单
使用 Frenet 承运商下单时，模块会保存其运费的计算方式。后台订单页面随后会显示一个 Frenet 区块，其中包含以下行：
Carrier：Frenet 承运商及服务，例如 Correios 或 Jadlog 的服务。针对实时报价显示。
Delivery time：Frenet 返回的工作日配送时间。针对实时报价显示。
Price source：Live Frenet quote、Fixed price (price per country)、Fallback cost 或 Free shipping。
即使卸载模块，这些数据也会被保留，Remove data on uninstall 同样如此。
许可证密钥
模块需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Frenet 是 Modules > Module Manager > VibeFox Frenet > Configure 中位于设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从此店铺中移除密钥）。它们下方有一行 Product: presta-shipping-frenet，以及一个链接 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 账户中释放该名额。
没有有效的密钥时，结账时不会向客户显示 Frenet 承运商，也不会计算任何费率。PrestaShop 前台无法得知您已登录后台，因此承运商对您也会隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 的 Alerts 选项卡中会出现提醒。现有订单不受影响。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。在您使用后台期间，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载或重置模块时，许可证密钥和许可证状态总会被删除。
故障排除
结账时没有显示 Frenet：请检查许可证是否有效，以及 Enable Frenet 是否已开启。在 Shipping > Carriers 中，检查该承运商是否覆盖客户所在国家的区域和客户组，或者 Ignore shipping zones 是否已开启且该国家是允许的。请查看模块页面顶部的警告、重量限制和 Minimum order amount。常见原因：客户尚未输入完整的 8 位数字 CEP，而且没有固定价格；或者 Frenet 对该路线没有返回任何服务，也没有固定价格。此外，商品页面上也可能将商品限定为某些承运商。
实时报价未显示：请开启 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 设置为 No tax。
修改后费率看起来过时：请在模块页面点击 Save。这会清除缓存的 Frenet 报价。
页面提示未找到 Frenet 承运商：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块以重新创建。在此之前，保存时会显示 The settings were saved, but the carrier could not be updated.
卸载
进入 Modules > Module Manager，打开 VibeFox Frenet 旁边的菜单，然后选择 Uninstall。许可证密钥和许可证状态始终会被删除。缓存的报价始终会被删除。如果 Remove data on uninstall 已开启，承运商将被删除（订单保留历史记录），设置和日志也会被删除。如果已关闭，承运商仅会被禁用，所有设置都会保留。重新安装模块或执行 Reset 时，已保存的承运商会恢复为之前的状态：您曾关闭的承运商将保持关闭。现有订单会保留 Frenet 承运商以及订单页面上的 Frenet 区块。
Frenet 是其各自所有者的商标。本模块与 Frenet 没有关联，也未获得 Frenet 的认可。