VibeFox Envioclick for OpenCart — 帮助
系统要求
OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP：8.0 或更高版本。
Envioclick 账户（仅用于实时费率）：在墨西哥或哥伦比亚注册的、具有 API 访问权限的 Envioclick 账户。API 密钥位于您的 Envioclick 账户中，路径为 Mi cuenta（右上角）> Información del API。如果只使用固定价格，则无需 Envioclick 账户。
User-Agent（仅墨西哥）：Envioclick 墨西哥要求每个 API 请求都带有 User-Agent 值。请向 Envioclick 支持团队索取（soporte.tecnico@envioclick.com）。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥仅适用于一个域名。
安装
下载文件是一个 zip 压缩包，内含适用于两个 OpenCart 版本的安装包。请解压到您的计算机上。压缩包包含 README.txt、OpenCart 3 安装包 vfd_envioclick-oc3-(version).ocmod.zip，以及 OpenCart 4 安装包 vfd_envioclick.ocmod.zip。请仅安装与您的 OpenCart 版本对应的安装包。两个版本使用相同的许可证密钥。
OpenCart 3
1. 进入后台，前往 Extensions > Installer，点击 Upload，然后选择文件 vfd_envioclick-oc3-(version).ocmod.zip。本扩展不会添加任何 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装器，直接将本安装包中 upload 文件夹的内容复制到店铺的根目录。
2. 前往 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Envioclick，点击 Install（绿色 + 按钮）。
3. 点击 Edit（铅笔按钮）打开设置页面。
4. 在 Edit 页面顶部许可证区块的 License key 中输入您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。
5. 输入 API 密钥，选择 API 国家，输入 User-Agent（墨西哥）、发货地邮政编码或 DANE 代码，以及发货地址。如果您的店铺默认货币不是 MXN 或 COP，请输入汇率。可选地，添加按国家设置的固定价格和备用费用。开启 Enable Envioclick 并点击 Save。
OpenCart 4
1. 进入后台，前往 Extensions > Installer，点击 Upload，然后选择文件 vfd_envioclick.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包将无法使用。
2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。
3. 前往 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Envioclick，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按照 OpenCart 3 的第 4 和第 5 步输入许可证密钥和设置。两个版本的设置页面及其字段相同。
安装后，该方式保持关闭状态，直到您开启 Enable Envioclick 并保存。如果卸载后重新安装扩展，将沿用您之前保留的 Envioclick 设置。
配置
所有设置都位于扩展页面：Extensions > Extensions > Shipping > VibeFox Envioclick > Edit。各分区列在左侧。页面底部的一个 Save 按钮可在不刷新页面的情况下保存整个页面。每次保存还会清除已缓存的 Envioclick 报价。数字字段既接受点号也接受逗号作为小数分隔符。只有对本扩展拥有修改权限的管理员用户才能保存设置。
General 分区会在实时费率无法根据已保存设置工作时显示警告：店铺货币不是 MXN 或 COP 却没有汇率；墨西哥缺少 User-Agent；缺少发货地邮政编码或 DANE 代码；或哥伦比亚缺少发货地址。如果无法识别店铺的重量或长度单位，也会发出警告；此时请在 System > Localisation > Weight Classes 中添加单位为 kg 的重量类别，或在 System > Localisation > Length Classes 中添加单位为 cm 的长度类别。保存时，扩展会检查：Method title 为 1 至 64 个字符；数字字段包含非负数；Currency conversion rate 大于 0；Minimum weight (kg) 不大于 Maximum weight (kg)；墨西哥的发货地代码为 5 位数字，哥伦比亚的为 8 位数字（或 5 位市镇代码）；Price per country 的每一行都有有效的国家和价格；Sort order 为整数。如果任一检查失败，则不会保存任何内容，页面会列出错误。
常规
顾客只会看到一个 Envioclick 费率，即最便宜或最快的承运商的费率。您可以在 Availability 中将该方式限制为某个地理区域或某些国家。
Enable Envioclick：在结账时显示或隐藏 Envioclick。默认：关闭。
Method title：在购物车和结账时显示给顾客的配送方式名称，最多 64 个字符。默认：Envioclick Shipping。必填。
Carrier in the title：将 Envioclick 承运商和实时费率的预计送达时间添加到标题中，例如 "Envioclick Shipping (Estafeta Express, 1 day)"。OpenCart 会将此标题与订单一起保存，因此它也会出现在订单邮件和订单页面中。无论如何，承运商都会保存到订单中。默认：开启。
Sort order：Envioclick 在结账时配送方式中的位置。一个整数。
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：开启并保存即可删除已保存的密钥；之后仅使用固定价格。在 API key 中输入的密钥会替换已保存的密钥。保存后，此开关会自动关闭。
API country：您的 Envioclick 账户所在的国家。
User-Agent (Mexico)：Envioclick 支持团队提供的值（soporte.tecnico@envioclick.com），例如 EcUserAgent-2/123456。墨西哥必须填写；没有它，墨西哥的实时费率将不会被请求。哥伦比亚可选。
Carrier choice：Cheapest（默认）或 Fastest (then cheapest)。Envioclick 会返回多家承运商的报价，顾客只会获得一个费率。
Branch pickup rates：同时考虑 "Ocurre" 费率，即顾客在承运商网点领取包裹的费率。关闭时，仅使用送货上门的费率。系统绝不会使用货到付款（COD）服务。默认：关闭。
Currency conversion rate：Envioclick 以墨西哥比索（MXN）或哥伦比亚比索（COP）报价。如果您的店铺默认货币不同，请以店铺货币输入 1 MXN 或 1 COP 的价值，例如 0.05。申报的包裹价值也以相同方式换算。如果店铺货币为 MXN 或 COP，请留空。未设置汇率时，不会以其他货币使用实时费率。
发货地
用于实时费率。OpenCart 没有店铺的邮政编码、城市或街道信息，因此请在此处输入。
Origin postcode / DANE code：墨西哥：5 位邮政编码。哥伦比亚：市镇的 8 位 DANE 代码，例如波哥大为 11001000；5 位市镇代码（11001）会在末尾补 000。
Origin address：取件地址的街道和门牌号。哥伦比亚必填，墨西哥可选。
固定价格
在没有实时费率时使用：没有 API 密钥、目的地不在 API 国家内、API 出错，或该路线没有承运商。
Price per country：以店铺默认货币（不含税）列出的国家和价格列表。点击 Add country 添加一行，点击 × 按钮删除一行。选择 * All other countries 可为所有没有单独行的国家设置一个通用价格。
Fallback cost：在没有实时费率且表格中没有任何行匹配时使用。若留空，则在这种情况下隐藏该方式。
Fixed price applies：Per order（默认）只收取一次价格。Per item (price × quantity) 则将价格乘以购物车中的商品数量。Envioclick 的实时费率始终按每个发货单计算。
条件
Minimum weight (kg)：购物车重量低于此值时隐藏该方式。0 表示无限制（默认）。
Maximum weight (kg)：购物车重量高于此值时隐藏该方式。默认：25。0 表示无限制。
Minimum order amount：仅当需要配送的商品小计（优惠券之后、税费之前）至少达到此金额时才显示该方式。留空则始终显示。
Free shipping from：当需要配送的商品小计（优惠券之后、税费之前）达到此金额时免运费。此时不会向 API 发送请求。留空则从不提供免运费。
Tax class：配送费的税率类别，或 No tax（默认）。Envioclick 的报价已包含承运商的税费，因此请选择 No tax，以避免对配送费重复征税。
可用范围
通常，该方式会提供给所选地理区域内的地址，或提供给所有地址。
Geo zone：仅向此地理区域内的地址提供 Envioclick。All zones（默认）表示无限制。地理区域在 System > Localisation > Geo Zones 中管理。开启 Ignore shipping zones 时不进行检查。
Ignore shipping zones：不检查地理区域；由下方的国家列表决定。默认：关闭。
Countries：该模式下的目的地国家。留空则允许所有国家。仅在开启 Ignore shipping zones 时使用。
高级
Debug log：将费率计算和 API 错误写入 storage/logs/vfd_evc_debug.log.php（OpenCart 4 中为 system/storage/logs/vfd_evc_debug.log.php）。该文件无法通过网页读取。API 密钥和顾客地址不会被记录。日志关闭时不会写入任何内容，包括 API 错误。使用完毕后请将其关闭。当文件达到 5 MB 时，它会被移至 vfd_evc_debug.old.log.php，并开始新的日志。
Log：显示调试日志的大小和最新条目。点击 Clear log 可将其清空。
Remove data on uninstall：开启后，卸载扩展会删除 Envioclick 设置、缓存的报价和日志。关闭时（默认），这些数据会保留，以便重新安装。已下单订单中的 Envioclick 数据始终会保留。
导入 / 导出
Export：点击 Download JSON 将设置保存为 JSON 文件。API 密钥不会被导出。
Import：粘贴之前导出的 JSON，然后点击 Import 即可恢复设置，例如在另一家店铺中使用。这些值会像普通保存一样进行检查。已保存的 API 密钥会保留。
结账时的工作方式
OpenCart 显示配送方式时，会向扩展请求 Envioclick 价格。如果设置了 Geo zone（且 Ignore shipping zones 处于关闭状态），而地址位于其之外，则不提供 Envioclick。只有 Requires Shipping 设为 Yes 的商品才会计算在内：其他商品不增加重量，也不计入订单金额。然后扩展会检查条件：Ignore shipping zones 中的国家、购物车重量以及最低订单金额。订单金额是需要配送的商品价格，在扣除优惠券折扣之后、税费之前。礼品卡、积分和店铺余额不计算在内。如果适用免运费，则价格为 0，并且不会向 Envioclick 发送任何请求。
如果已设置 API 密钥，且目的地位于 API 国家内，扩展会向 Envioclick 请求报价。在墨西哥，当顾客输入 5 位邮政编码后即发出请求。在哥伦比亚，当市镇通过邮政编码栏中的 8 位 DANE 代码，或通过省（即 OpenCart 地址中的地区）和城市识别后，即发出请求；在哥伦比亚全国范围内唯一的城市名称，即使不填省也能识别。大小写和重音符号不影响识别。扩展会选择不是货到付款的最便宜或最快报价，并将其换算为店铺默认货币。价格会按该货币的小数位数取整，并以顾客的货币显示，同时包含所选 Tax class 的税费。
包裹始终按一个箱子计算：总重量由商品的重量类别换算为 kg，箱子尺寸则由商品尺寸换算为 cm 后得出。没有尺寸的商品按 10 × 10 × 10 cm 计算。没有任何重量的购物车将按 0.5 kg 发送。申报价值为订单金额。
同一路线和同一包裹的每个报价都会缓存 1 小时。失败的请求会缓存 10 分钟，以免 API 不可用时拖慢每次结账更新。如果 Envioclick 返回错误或该路线没有承运商，顾客不会看到任何错误：系统会使用固定价格或备用费用，或者隐藏该方式。开启调试日志时，原因会写入该日志。
扩展仅计算费率。它不会创建运单或标签，不会申请取件，也不会跟踪或取消发货。它只提供一个费率，而不是让顾客在承运商之间选择，并且不使用货到付款服务，也不提供多包裹报价。实时报价仅适用于国内配送。
在 OpenCart 4 中，顾客在结账页面的配送方式区块中点击 Choose，然后在 Shipping method options 窗口中选择 Envioclick。该方式的工作方式与 OpenCart 3 相同。
订单
使用 Envioclick 下单时，结账时计算出的费率会与订单一起保存，并且不再变化。在 Sales > Orders 中，订单页面会显示 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)。即使该方式之后已被关闭，面板仍会显示。
在 OpenCart 4 中，结账过程只保留一个订单，并在顾客每次重新确认时更新该订单。已保存的费率随后会被结账的最新费率替换。如果顾客切换到其他配送方式，该订单将不再显示此面板。后台对订单所做的更改不会改变已保存的费率。
如果开启了 Carrier in the title，承运商会成为订单配送方式名称的一部分。如果关闭，则在扩展启用期间，新订单邮件和顾客账户中的订单页面会添加一行 Shipping carrier:，显示实时费率的承运商。请在您的 Envioclick 账户中创建运单。以固定价格下的订单没有 Envioclick 承运商。
许可证密钥
本扩展需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Envioclick 是 Extensions > Extensions > Shipping > VibeFox Envioclick > Edit 页面上的第一个区块，位于设置上方。请将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），并提供以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺中移除密钥）。其下方是 Product: opencart-shipping-envioclick 一行，以及打开您 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 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 Envioclick，也不会计算任何费率。在同一浏览器中登录后台的管理员用户，仍会在店铺中看到该方式，并标有 (unlicensed — visible to admins only)，以便您在购买密钥之前进行设置和测试。在 OpenCart 4 中此预览不可用：店铺无法看到后台登录状态，因此没有有效密钥时，该方式对所有人都隐藏。打开一次 Edit 页面后，后台的 Dashboard 上会出现提醒。点击 × 可将其隐藏 7 天。现有订单不受影响。
许可证到期后，扩展仍会继续工作，但更新和支持需要续订。当您打开后台的 Dashboard 或 Edit 页面时，系统会自动再次检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展时总是会删除许可证密钥和许可证状态。
故障排除
结账时不显示 Envioclick：请检查许可证是否有效，Enable Envioclick 是否已开启。检查 Geo zone（或 Ignore shipping zones 和 Countries）、重量限制以及 Minimum order amount。在没有实时费率的情况下，该方式需要为该国设置固定价格、一个 * All other countries 行，或一个 Fallback cost。检查商品的 Requires Shipping 是否设为 Yes。
实时费率不显示：请阅读 General 分区中的警告，然后开启 Debug log，重新加载结账页面，并查看扩展页面上的 Log 字段。常见原因：没有汇率（店铺货币不是 MXN 或 COP）、没有 User-Agent（墨西哥）、没有发货地邮政编码或 DANE 代码、尚未输入顾客的邮政编码（墨西哥）或城市（哥伦比亚）、目的地在 API 国家之外，或该路线没有承运商。
为什么需要汇率？Envioclick 仅以墨西哥比索或哥伦比亚比索返回价格。扩展绝不会将比索金额显示为其他货币。
哥伦比亚：无法识别城市：请检查顾客是否在地址中选择了省作为地区，并正确输入了市镇名称。将 8 位 DANE 代码作为邮政编码输入也可以。
配送费被重复征税：Envioclick 的报价已包含承运商的税费。请将 Tax class 设为 No tax。
修改后费率看起来过时：请在扩展页面点击 Save。这会清除缓存的报价。
页面显示 "Warning: You do not have permission to modify VibeFox Envioclick!"：您的管理员用户组可能只有查看设置的权限。请在 System > Users > User Groups 中，为该用户组授予 extension/shipping/vfd_envioclick（OpenCart 3）或 extension/vfd_envioclick/shipping/vfd_envioclick（OpenCart 4）的修改权限。
面向开发人员：可以通过设置 vfd_evc_api_url（用于测试）替换 Envioclick 报价 API 地址；设置页面中没有对应字段。
卸载
前往 Extensions > Extensions，选择类型 Shipping，然后点击 VibeFox Envioclick 旁边的 Uninstall（红色 − 按钮）。OpenCart 始终会重置 Enable Envioclick、Sort order、Tax class 和 Geo zone。缓存的报价始终会被删除。如果 Remove data on uninstall 已开启，Envioclick 设置和调试日志也会被删除。如果关闭，其他设置会保留，并在您重新安装扩展时继续使用。已下单订单中的 Envioclick 数据在两种情况下都会保留，订单也会保留其配送方式和费用。
若要在 OpenCart 4 上同时删除扩展文件，请在卸载后前往 Extensions > Installer，在已安装扩展列表中点击 VibeFox Envioclick 旁的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。
Envioclick 是其各自所有者的商标。本扩展与 Envioclick 无关联，也未获得 Envioclick 的认可。