VibeFox Envioclick for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝安装在更旧的 PHP 版本上。
Envioclick 账户（仅用于实时运费）：在墨西哥或哥伦比亚开通、并具有 API 访问权限的 Envioclick 账户。API 密钥位于您的 Envioclick 账户中，路径为 Mi cuenta（右上角）> Información del API。如果您只使用固定价格，则不需要 Envioclick 账户。
User-Agent（仅墨西哥）：Envioclick Mexico 要求每个 API 请求都带有 User-Agent 值。请向 Envioclick 支持团队索取（soporte.tecnico@envioclick.com）。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox Envioclick，然后点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，于 License key 处输入您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。
4. 输入 API 密钥，选择 API 国家，填写 User-Agent（墨西哥）、发货地邮政编码或 DANE 代码以及发货地址。如果店铺的默认货币不是 MXN 或 COP，请输入货币换算汇率。对于哥伦比亚，如果页面提供，请点击 Add Colombian departments。
5. 可选：添加按国家设置的固定价格和备用运费，然后点击 Save。
安装时，模块会创建 Envioclick Shipping 承运商，其配送时间文本为 Courier delivery by the best Envioclick carrier。该承运商会分配给所有区域和所有客户群组。您可以在 Shipping > Carriers 中修改区域、客户群组、配送时间、徽标和尺寸限制。请不要在那里设置价格：价格始终来自模块。
配置
所有设置都在模块页面中：Modules > Module Manager > VibeFox Envioclick > Configure。每个部分都有各自的 Save 按钮，它会保存整个页面。每次保存也会清除缓存的 Envioclick 报价。数字字段既接受小数点，也接受逗号作为小数分隔符。
设置 API 密钥后，如果实时运费无法工作，页面顶部会显示警告：店铺货币不是 MXN 或 COP 却没有设置汇率、墨西哥没有 User-Agent、没有发货地邮政编码或 DANE 代码，或者哥伦比亚没有发货地址。如果店铺的重量或尺寸单位无法识别，页面也会发出警告；请在 International > Localization（Local units）中设置 kg、g、lb 或 oz，以及 cm、mm、m 或 in。保存时，模块会检查 Method title 是否为有效的承运商名称，数字字段是否包含非负数字，Currency conversion rate 是否大于 0，Minimum weight 是否不大于 Maximum weight，以及发货地代码在墨西哥是否为 5 位、在哥伦比亚是否为 8 位（或 5 位的市镇代码）。如果某项检查未通过，将显示错误，并且不保存任何内容。
常规
承运商的区域、客户群组和尺寸限制在 Shipping > Carriers 中设置（或使用下方的 Ignore shipping zones）。本页的设置适用于所有区域。
Enable Envioclick：开启或关闭承运商。这与 Shipping > Carriers 中的承运商状态使用同一个开关。
Method title：顾客在购物车和结账时看到的承运商名称。默认值：Envioclick Shipping。必填。
Carrier in the title：在结账时，于承运商名称下方显示实时运费的 Envioclick 承运商和预计配送时间，例如“Estafeta Express, 1 day”。无论此选项如何，承运商都会保存到订单中，并显示在订单页面上。默认值：开启。
Envioclick API（实时运费）
可选。没有 API 密钥时，仅使用固定价格。本部分提供 Envioclick 墨西哥和哥伦比亚 API 文档的链接。仅对 API 国家内的目的地请求实时运费。发往其他国家的货物使用固定价格。
API key：您的 Envioclick API 密钥，位于 Mi cuenta > Información del API。它在“Authorization”标头中发送。保存后，该字段保持为空，并显示 Saved — leave empty to keep it。只有在要更改时才输入新值。
Remove the saved API key：仅在已保存密钥时显示。选择 Yes 并保存即可删除密钥；之后仅使用固定价格。在 API key 中输入的密钥会替换已保存的密钥。
API country：您的 Envioclick 账户所在国家。
Colombian departments：仅适用于哥伦比亚。PrestaShop 默认没有哥伦比亚的省。没有省份时，只能识别在哥伦比亚唯一的城市名称；省份用于区分同名市镇。Add Colombian departments 按钮会将 33 个省添加为哥伦比亚的州（ISO 代码 ANT、DC 等），为哥伦比亚开启“Contains states”，并在哥伦比亚地址表单中添加省份字段。已存在的省不会重复添加。全部设置完成后，该字段会显示哥伦比亚地址拥有多少个省。
User-Agent（墨西哥）：Envioclick 支持团队提供的值（soporte.tecnico@envioclick.com），例如 EcUserAgent-2/123456。墨西哥必填；没有它，就不会为墨西哥请求实时运费。哥伦比亚可选。
承运商选择：Cheapest（默认）或 Fastest (then cheapest)。Envioclick 返回多家承运商的报价，顾客只获得一个运费。
网点自取运费：同时考虑 “Ocurre” 运费，即顾客在承运商网点取件。关闭时，仅使用送货上门的运费。从不使用货到付款（COD）服务。默认值：关闭。
货币换算汇率：Envioclick 以 MXN（墨西哥）或 COP（哥伦比亚）报价。如果您的店铺默认货币不同，请以店铺货币输入 1 MXN 或 1 COP 的价值，例如 0.05。申报的包裹价值也按同样方式换算。如果店铺货币是 MXN 或 COP，请留空。没有汇率时，其他货币下不使用实时运费。
发货地
用于实时运费。如果店铺位于 API 国家，空白字段会从 Shop Parameters > Contact > Stores 中的店铺地址获取。
Origin postcode / DANE code：墨西哥：5 位邮政编码。哥伦比亚：市镇的 8 位 DANE 代码，例如波哥大为 11001000；5 位市镇代码（11001）同样有效。
Origin address：取件地址的街道和门牌号。哥伦比亚必填，墨西哥可选。
固定价格
在没有实时运费时使用：没有 API 密钥、目的地在 API 国家之外、API 出错，或该路线没有承运商。
Price per country：一个表格，包含 2 位国家代码和以店铺默认货币计算的价格（不含税）。点击 Add row 添加国家，点击垃圾桶图标删除。对于没有单独行的所有国家，请使用 * 作为国家代码。
Fallback cost：在没有实时运费且表格中没有匹配行时使用。留空则在这种情况下隐藏该承运商。
Fixed price applies：Per order 只收取一次价格。Per item (price × quantity) 则按购物车中的商品数量相乘。Envioclick 实时运费始终按每个货件计算。
条件
Minimum weight：购物车重量低于此值时隐藏该承运商，单位为千克。0 表示无限制。
Maximum weight：购物车重量高于此值时隐藏该承运商，单位为千克。默认值：25。0 表示无限制。
Minimum order amount：仅当购物车小计（折扣后、税前）至少达到此金额时才显示该承运商。留空则始终显示。
Free shipping from：当购物车小计（折扣后、税前）达到此金额时免运费。此时不会向 Envioclick 发送请求。留空则从不提供免运费。
Tax：承运商的税务规则，或 No tax。Envioclick 报价已包含承运商的税费，因此请选择 No tax，以免对运费重复征税。
无配送区域时的可用性
通常，承运商会在 Shipping > Carriers 中分配给它的区域内提供。
Ignore shipping zones：即使承运商未分配到下列国家所在的区域，也为这些国家提供 Envioclick。开启后，承运商会分配给所有区域，包括以后创建的区域。关闭后，承运商会恢复其之前的区域。
Countries：该模式下的目的地国家。留空则使用您配送的所有国家（已启用的国家）。仅在开启 Ignore shipping zones 时使用。
高级
Debug log：将运费计算和 API 错误记录到模块文件夹中的 logs/vfd_evc_debug.log.php。该文件无法通过网页打开。API 密钥和顾客地址不会被记录。日志关闭时不写入任何内容。完成后请关闭。
Log：显示调试日志的大小和最新条目。点击 Clear log 可将其清空。
Remove data on uninstall：开启后，卸载模块会删除 Envioclick 设置、承运商、缓存的报价和日志。过去订单中保存的承运商会保留。关闭时，所有内容都会保留，以便重新安装。
结账时的工作流程
在配送步骤，PrestaShop 会向模块索取 Envioclick 价格。只有实物商品才计算在内：虚拟商品不增加重量，也不计入订单金额。模块首先检查条件：Ignore shipping zones 中的国家、购物车重量和最低订单金额。如果适用免运费，价格为 0，并且不会向 Envioclick 发送请求。
如果设置了 API 密钥，且目的地位于 API 国家内，模块会向 Envioclick 请求报价。在墨西哥，顾客输入 5 位邮政编码后即发出请求。在哥伦比亚，则在识别出省份和市镇后发出请求（重音和大小写不影响识别）。模块会选择最便宜或最快的报价（非货到付款），并将其换算为店铺的默认货币。随后，价格以顾客的购物车货币显示。
包裹始终为一个箱子：总重量换算为千克，最大商品的长度和宽度，高度则以能容纳所有商品总体积为准。没有尺寸的商品按 10 × 10 × 10 cm 计算。没有重量的购物车按 0.5 kg 发送。申报价值为购物车小计。
同一路线和同一包裹的每个报价缓存 1 小时。失败的请求缓存 10 分钟，以免不可用的 API 拖慢每次结账更新。API 超时时间为 10 秒。如果 Envioclick 返回错误或该路线没有承运商，顾客不会看到错误：会使用固定价格，或隐藏该承运商。原因会写入调试日志。
如果您在承运商已有订单后，在 Shipping > Carriers 中编辑该承运商，PrestaShop 会将其保存为新版本的承运商。模块会自动跟随新版本。
模块仅计算运费。它不生成运单或标签，不预约取件，也不追踪或取消货件。它只提供一个运费，而不是在承运商之间选择，并且不使用货到付款服务，也不提供多包裹报价。实时报价仅限国内。
订单
使用 Envioclick 承运商下单时，为其购物车计算的运费会与订单一同保存，之后不再变化。后台订单页面会显示 Envioclick shipping 区块，其中包含 Envioclick carrier、Estimated delivery，以及 Envioclick rate ID（针对实时运费）、Price source（Envioclick live rate、Fixed price per country、Fallback cost 或 Free shipping threshold），以及 Calculated price (excl. tax)。对于实时运费，顾客的订单页面会显示 Shipping carrier。请在您的 Envioclick 账户中创建运单。
使用固定价格下的订单没有 Envioclick 承运商。
许可证密钥
模块需要来自 vibefox.net 的 VibeFox 许可证密钥才能工作。许可证区块 License — VibeFox Envioclick 位于 Modules > Module Manager > VibeFox Envioclick > Configure 页面的最顶部，在设置上方。将密钥输入 License key 并点击 Activate。之后，该区块会显示已遮蔽的密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺移除密钥）。其下方是一行 Product: presta-shipping-envioclick 以及链接 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 账户中释放名额。
如果没有有效密钥，Envioclick 承运商不会在结账时向顾客显示，也不会计算运费。PrestaShop 前台无法识别您已登录后台，因此您自己也看不到该承运商：您可以在购买密钥前设置模块，但无法在结账时测试。Modules > Module Manager 的 Alerts 选项卡中会出现提醒。已有订单不受影响。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。在您使用后台期间，系统会自动重新检查状态：输入密钥后的前 14 天内每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时没有显示 Envioclick：请检查许可证是否有效，以及 Enable Envioclick 是否已开启。在 Shipping > Carriers 中，检查该承运商是否覆盖顾客所在国家的区域和顾客的群组，或开启 Ignore shipping zones 并检查 Countries。检查重量限制和 Minimum order amount。没有实时运费时，承运商需要该国家的固定价格、一个 * 行或一个 Fallback cost。商品也可能在商品页面中被限制只能使用某些承运商。
实时运费没有显示：请阅读模块页面顶部的警告，然后开启 Debug log，重新加载结账页面，并查看模块页面上的 Log 字段。常见原因：没有汇率（店铺货币不是 MXN 或 COP）、没有 User-Agent（墨西哥）、没有发货地邮政编码或 DANE 代码、顾客的邮政编码（墨西哥）或城市（哥伦比亚）尚未输入、目的地在 API 国家之外，或该路线没有承运商。
为什么需要汇率？Envioclick 仅以墨西哥或哥伦比亚比索返回价格。模块绝不会将比索金额显示为其他货币。
哥伦比亚：无法识别城市：请在模块页面点击 Add Colombian departments，以便顾客选择省份，并检查市镇名称是否输入正确。作为邮政编码输入的 8 位 DANE 代码同样有效。
运费被重复征税：Envioclick 报价已包含承运商的税费。请将 Tax 设置为 No tax。
更改后报价看起来过时：请在模块页面点击 Save。这会清除缓存的报价。
页面提示未找到 Envioclick 承运商：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块，以重新创建它。
卸载
进入 Modules > Module Manager，打开 VibeFox Envioclick 旁边的菜单，然后选择 Uninstall。许可证密钥和许可证状态始终会被删除。缓存的报价以及没有订单的购物车中保存的运费始终会被删除。如果 Remove data on uninstall 已开启，承运商会被删除（订单会保留其历史记录），设置和日志也会被删除。如果已关闭，承运商仅会被停用，所有设置都会保留。重新安装模块会让已保存的承运商恢复其之前的状态。两种情况下，已下订单的 Envioclick 数据都会保留。
Envioclick 是其各自所有者的商标。本模块与 Envioclick 无关，也未获得 Envioclick 的认可。