VibeFox Envioclick for WooCommerce — 帮助
系统要求
WordPress：5.8 或更高版本。
WooCommerce：5.0 或更高版本，已安装并启用。没有它，插件无法激活。
PHP：8.0 或更高版本。
Envioclick 账户（仅用于实时运费）：在墨西哥或哥伦比亚的 Envioclick 账户，并具有 API 访问权限。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. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 vfd_envioclick 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Shipping > VibeFox Envioclick，或在 Plugins 页面点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 输入 API 密钥，选择 API 国家，输入 User-Agent（墨西哥）、发货邮政编码或 DANE 代码以及发货地址。如果您的店铺货币不是 MXN 或 COP，请输入汇率。
6. 可选：按国家添加固定价格，并设置备用运费。
7. 在 WooCommerce > Settings > Shipping > Shipping zones 中将 VibeFox Envioclick 添加到配送区域；或开启 Ignore shipping zones 并选择国家。
配置
所有设置都在同一页面：WooCommerce > Settings > Shipping > VibeFox Envioclick。它们适用于所有配送区域。将该方式添加到某个区域时，区域窗口只有一个字段：
Title (zone)：顾客在此区域看到的名称。留空则使用全局的 Method title。
设置了 API 密钥后，如果实时运费无法工作，插件会在页面顶部显示警告：店铺货币不是 MXN 或 COP 却没有设置汇率；墨西哥缺少 User-Agent；缺少发货邮政编码或 DANE 代码；或哥伦比亚缺少发货地址。每次保存设置时，缓存的报价都会被清除。数字字段同时接受小数点和逗号作为小数分隔符。
常规
Enable/Disable：一次性在所有区域启用或禁用该方式。默认：开启。
Method title：在购物车和结账时显示的配送方式名称。区域可以覆盖它。默认：Envioclick Shipping。
Carrier in the title：对于实时运费，在标题旁显示承运商和预计送达时间，例如“Envioclick Shipping (Estafeta Express, 1 day)”。无论是否开启，承运商都会保存到订单中，并显示在订单电子邮件里。默认：开启。
Envioclick API（实时运费）
可选。没有 API 密钥时，只使用固定价格。仅对 API 国家内的目的地请求实时运费。发往其他国家的货物使用固定价格。
API key：来自 Mi cuenta > Información del API 的 Envioclick API 密钥。
API country：您的 Envioclick 账户所在国家。
User-Agent (Mexico)：Envioclick 支持团队提供的值（soporte.tecnico@envioclick.com）。墨西哥必填；没有它则不会请求墨西哥的实时运费。哥伦比亚为可选。
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，请留空。没有汇率时，不会在其他货币中使用实时运费。
发货地
用于实时运费。如果店铺位于 API 国家，空白字段会从 WooCommerce > Settings > General 中的店铺地址获取。
Origin postcode / DANE code：墨西哥：5 位邮政编码。哥伦比亚：市镇的 8 位 DANE 代码，例如波哥大为 11001000。
Origin address：取件地址的街道和门牌号。哥伦比亚必填，墨西哥可选。
固定价格
在没有实时运费时使用：没有 API 密钥、目的地不在 API 国家、API 出错，或该路线没有承运商。
Price per country：以店铺货币表示的国家和价格表。点击 + Add country 添加一行，点击叉号删除一行。* Default 行适用于没有自己一行的所有国家。
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 发送请求。留空则从不提供免运费。
Excluded shipping classes：如果购物车包含属于这些 WooCommerce 配送类别的任何商品，则隐藏该方式。
Tax status：Taxable 会将 WooCommerce 税费加到运费上，None 则不加。Envioclick 报价已包含承运商的税费，因此请选择 None，以避免对运费重复收税。
无配送区域时的可用性
Ignore shipping zones：即使 Envioclick 未添加到配送区域，也为下方列出的国家提供该方式。
Countries：该模式的目的地国家。留空则使用您配送的所有国家。仅在开启 Ignore shipping zones 时使用。
高级
Debug log：将运费计算和 API 错误记录到 WooCommerce > Status > Logs，来源为 vfd_envioclick。API 密钥和顾客地址不会被记录。完成后请关闭。
Remove data on uninstall：开启后，删除插件会移除所有 Envioclick 设置、区域方式和缓存的报价。停用插件则不会删除任何设置。
结账时的工作方式
当顾客输入配送地址时，WooCommerce 会向插件请求运费。插件首先检查购物车重量、最低订单金额和排除的配送类别。如果适用免运费，则以零价格显示该方式，并且不会向 Envioclick 发送请求。
如果设置了 API 密钥且目的地位于 API 国家，插件会向 Envioclick 请求报价。在墨西哥，顾客输入 5 位邮政编码后即发出请求。在哥伦比亚，当省份和市镇被识别后发出请求（大小写和重音符号不影响识别，“Bogotá D.C.” 也可以）。插件会选择最便宜或最快的送货上门报价（非货到付款），并将其换算为您的店铺货币。
包裹始终为一个箱子：总重量换算为 kg，长度和宽度取最大商品的尺寸，高度则以能容纳所有商品总体积为准。没有尺寸的商品按 10 × 10 × 10 cm 计算。没有重量的购物车按 0.5 kg 发送。申报价值为购物车小计。
对于相同路线和包裹，每个报价缓存 1 小时。失败的请求缓存 10 分钟，这样不可用的 API 不会拖慢每次结账更新。API 超时时间为 10 秒。如果 Envioclick 返回错误或该路线没有承运商，顾客不会看到任何错误：会使用固定价格，或隐藏该方式。原因会写入调试日志。
该方式适用于经典结账以及购物车和结账区块。它兼容 WooCommerce 高性能订单存储（HPOS）。
插件仅计算运费。它不生成运单或标签，不预约取件，也不追踪或取消货件。它提供一个运费，而不是在承运商之间选择，不使用货到付款服务、额外保险或多包裹报价。实时报价仅限国内。
订单
使用 Envioclick 实时运费下单时，承运商和服务会保存到订单中。后台订单页面在收货地址下方显示 Envioclick carrier，并附上预计送达时间。顾客的订单页面和订单电子邮件（HTML 和纯文本）显示 Shipping carrier。报价的 Envioclick 运费 ID 作为隐藏数据与订单的运费行一起保存；订单页面上不显示。请在您的 Envioclick 账户中创建运单。
使用固定价格下的订单没有承运商。
许可证密钥
插件需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Shipping > VibeFox Envioclick 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期截止日期和您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从本站点移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。
没有有效密钥时，Envioclick 不会在结账时向顾客显示。已登录的店铺管理员仍能看到它，并标记为 (unlicensed — visible to admins only)，方便您在购买密钥之前设置和测试插件。插件页面和 WooCommerce 页面上会出现提醒。现有订单不受影响。
许可证到期后，插件仍会继续工作，但更新和支持需要续期。状态会在后台自动重新检查。
故障排除
Envioclick 未出现在结账页面：检查许可证是否有效，Enable/Disable 是否开启，该方式是否已添加到顾客所在国家的区域中（或 Ignore shipping zones 已开启且该国家被允许）。检查重量限制、Minimum order amount 和 Excluded shipping classes。没有实时运费时，该方式需要该国家的固定价格、* Default 行或 Fallback cost。
实时运费未出现：阅读设置页面顶部的警告，然后开启 Debug log，重新加载结账页面，并打开 WooCommerce > Status > Logs，来源 vfd_envioclick。常见原因：没有汇率（店铺货币不是 MXN 或 COP）、没有 User-Agent（墨西哥）、没有发货邮政编码或 DANE 代码、顾客的邮政编码（墨西哥）或城市（哥伦比亚）尚未输入、目的地在 API 国家之外，或该路线没有承运商。
为什么需要汇率？Envioclick 仅以墨西哥或哥伦比亚比索返回价格。插件绝不会把比索金额显示为其他货币。
哥伦比亚：无法识别城市：顾客必须选择省份并输入市镇名称。作为邮政编码输入的 8 位 DANE 代码也可以使用。开发者可以通过 vfd_evc_dane_code 过滤器提供 DANE 代码。
运费被重复征税：Envioclick 报价已包含承运商的税费。请将 Tax status 设为 None。
更改后报价看起来过时：保存设置页面。这会清除缓存的报价。
开发者过滤器：vfd_evc_quotation_request（请求体）、vfd_evc_api_url、vfd_evc_dane_code、vfd_evc_default_dimensions 和 vfd_evc_package_description。
许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在其他域名上使用，请在 vibefox.net 账户中释放名额，然后点击 Check now。如果站点地址已更改，请点击 Check now 为新域名激活密钥。如果无法访问许可证服务器，插件将继续使用最后已知的状态运行。
卸载
停用插件会保留所有设置和区域方式；只清除缓存的报价。要移除插件，请先停用，然后在 Plugins 页面删除。本插件的许可证密钥和许可证状态始终会被删除。只有开启了 Remove data on uninstall 时，设置、区域方式和缓存的报价才会被删除；否则会保留，以便日后重新安装。过去订单中保存的承运商会被保留，现有订单也会保留其运费行。
Envioclick 是其各自所有者的商标。本插件与 Envioclick 无关联，也未获得 Envioclick 的认可。