VibeFox Chilexpress for WooCommerce — 帮助
系统要求
WordPress: 5.8 或更高版本。
WooCommerce: 7.0 或更高版本，已安装并启用。未安装 WooCommerce 时插件无法启用。
PHP: 8.0 或更高版本。
Chilexpress API 密钥（仅用于实时运费）: 请在 Chilexpress 开发者门户（developers.wschilexpress.com）创建账户，并订阅两个产品：Rating (Cotizador) 和 Coverage (Coberturas / Georreferencia)。每个产品都有各自的订阅密钥。测试密钥仅适用于测试环境；生产密钥签发给与 Chilexpress 签订了客户合同的企业客户。您还需要发货所在 comuna 的 Chilexpress county 代码，例如 STGO。如果只使用固定价格，则无需 API 密钥。
VibeFox 许可证密钥: 在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 vfd_chilexpress 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Shipping > VibeFox Chilexpress，或在插件页面点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 填写价格表。若要使用实时运费，请输入两个订阅密钥、发货地的 origin county 代码；如果店铺货币不是 CLP，还需输入 CLP 汇率，然后选择运费来源（参见配置）。
6. 在 WooCommerce > Settings > Shipping > Shipping zones 中，将 VibeFox Chilexpress 添加到智利的配送区域；或者开启 Ignore shipping zones 并选择国家。
配置
所有设置都在一个页面中：WooCommerce > Settings > Shipping > VibeFox Chilexpress。它们适用于所有配送区域。将该方式添加到某个区域时，区域窗口中只有一个字段：
Title (zone): 此区域结账时该配送选项的名称。留空则使用全局的 Name。
设置页面顶部会列出存在的问题：已选择 API 运费，但缺少密钥、origin county 代码或 CLP 汇率；或价格表中没有智利或默认（* Default）的行。每次保存设置时，缓存的运费和 comuna 列表都会被清除。数字可以用小数点或逗号输入；无效数字不会被保存，并会显示错误。
常规
Enable/Disable: 一次性在所有区域启用或停用 Chilexpress 配送。
Name: 结账时显示给顾客的配送方式名称。Default: Chilexpress。
Tax status: Taxable 会在配送费上加收 WooCommerce 税费（若启用了税费），None 则不加。Chilexpress API 运费按报价原样使用。如果报价已包含 IVA，而您的店铺会在其上再加税，请选择 None。
运费
Rate source: 价格的来源。
实时运费仅适用于智利境内的目的地。其他国家始终使用固定价格。
Country prices: 目的国家表，包含 Price 列以及以店铺货币计的可选包裹尺寸价格。尺寸根据购物车重量确定：XS 为 1 千克以内，S 为 2 千克以内，M 为 3 千克以内，L 为 5 千克以内，XL 超过 5 千克。尺寸保持为 0 时使用 Price。点击 + Add country 添加一行，点击叉号删除一行。* Default 行适用于没有自己行的国家。没有行（也没有 *）的国家不提供固定价格。价格和尺寸价格都为 0 的行表示免运费。
Calculation type: Per order 只收取一次固定价格。Per item (fixed price x number of items) 则按购物车商品数量相乘。Chilexpress API 运费始终按整个包裹报价。
Chilexpress API（实时运费）
Test environment: 使用 Chilexpress 测试环境（qaservices.wschilexpress.com）。请配合测试密钥使用，并在正式店铺中关闭。
Rating API key: Rating (Cotizador) 产品的订阅密钥。
Coverage API key: Coverage (Coberturas / Georreferencia) 产品的订阅密钥。用于查找顾客 comuna 的 Chilexpress county 代码（结账时的城市字段）。
Origin county code: 发货所在 Chilexpress county（comuna）的代码，2–5 个字母，例如 STGO（Santiago Centro）、PROV（Providencia）、LCON（Las Condes）、VALP（Valparaíso）或 CONC（Concepción）。不是 county 代码的值会被拒绝并显示错误。
Service: 用于计算运费的 Chilexpress 服务。如果目的地不提供该服务，则使用报价最便宜的服务。
CLP exchange rate: Chilexpress 以智利比索报价。仅在店铺货币不是 CLP 时需要：1 CLP 以店铺货币计的价格，例如 0.001。未设置时不会使用 API 运费。
可用性
Min weight (kg): 方式显示所需的购物车最小重量。0 表示不限。
Max weight (kg): 购物车重量超过此值时隐藏该方式。Default: 25。0 表示不限。
Minimum subtotal: 仅当购物车小计（折扣后、不含税）不低于此金额时显示该方式。留空则始终显示。
Excluded shipping classes: 若购物车中任一商品属于这些 WooCommerce 配送类别，则隐藏该方式。
Ignore shipping zones: 即使未将该方式添加到配送区域，也为下列国家提供该方式。
Countries: 该模式下的目的国家。留空则使用店铺的所有配送国家。仅在开启 Ignore shipping zones 时使用此字段。
免费配送
Free shipping: 启用满额包邮门槛。
Free shipping from: 购物车小计达到此金额即免运费。仅在开启 Free shipping 时使用。此时不会发出 API 请求。
高级
Debug log: 在 WooCommerce > Status > Logs 中记录 API 请求和运费计算，来源为 vfd-chilexpress。即使此选项关闭，API 错误也始终会被记录。API 密钥从不记录。
Remove data on uninstall: 开启后，删除插件会移除其设置和区域方式。停用插件从不删除设置。现有订单的配送行始终保留。
结账时的工作方式
顾客输入配送地址时，WooCommerce 会向插件请求运费。插件首先检查条件：购物车重量、最低小计和排除的配送类别。如果适用满额包邮，顾客将获得免费运费，且不会向 Chilexpress 发送任何请求。
对于智利地址且运费来源为 API 时，插件从城市字段中获取地区和 comuna，并在该地区的 comuna 列表（Coverage API）中查找 Chilexpress county 代码。重音、空格和拼写变体会被忽略，因此 Ñuñoa 与 Nunoa 匹配，Santiago 与 Santiago Centro 匹配。直接在城市字段中输入的 county 代码也会被接受。随后插件向 Rating API 发送发货地和目的地的 county 代码、购物车重量（至少 0.1 千克）、包裹尺寸（最大商品的长和宽，高度叠加），以及以 CLP 计的购物车小计作为申报价值。Chilexpress 返回其服务；插件使用所选服务或最便宜的服务，并将比索金额转换为您店铺的货币。服务名称会以 Chilexpress service 保存在订单的配送行中。
运费缓存 1 小时，comuna 列表缓存 7 天。失败的请求会记住 5 分钟，因此缓慢或不可用的 API 不会拖慢每次结账刷新。API 超时时间为 10 秒。如果 Chilexpress 返回错误、没有带价格的服务或无法识别 comuna，顾客不会看到任何错误。在仅 API 模式下该方式会被隐藏，否则使用固定价格。原因会写入 WooCommerce 日志。
该方式适用于经典结账以及购物车和结账区块。它兼容 WooCommerce 高性能订单存储（HPOS）。
插件仅计算运费。它不会创建发货单或运输订单（OT）、打印面单、预约取件或跟踪包裹；请在您的 Chilexpress 账户中预订发货。顾客无法选择 Chilexpress 网点，也没有 comuna 选择器：顾客在标准城市字段中输入 comuna。国际发货使用固定价格。
许可证密钥
插件需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Shipping > VibeFox Chilexpress 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期至何时以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从此站点移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。
没有有效密钥时，Chilexpress 不会在结账时向顾客显示。已登录的店铺管理员仍会看到它，并标注 (unlicensed — visible to admins only)，方便您在购买密钥前完成设置和测试。插件页面和 WooCommerce 页面会显示提醒。现有订单不受影响。
许可证过期后，插件仍可继续工作，但更新和支持需要续费。状态会在后台自动重新检查。
故障排除
Chilexpress 未出现在结账页面: 请检查许可证是否有效，Enable/Disable 是否开启，以及该方式是否已添加到顾客所在国家的区域（或已开启 Ignore shipping zones 且允许该国家）。检查重量限制、Minimum subtotal 和 Excluded shipping classes。使用固定价格时，请检查该国家或 * Default 是否有一行。
未显示实时运费，改用固定价格: 首先查看设置页面顶部的警告。否则开启 Debug log，重新加载结账页面，并打开 WooCommerce > Status > Logs，来源 vfd-chilexpress。常见原因：Chilexpress 无法识别的 comuna（检查城市字段和地区）、使用了错误产品或环境的密钥，或目的地没有 Chilexpress 服务覆盖。
日志中出现 HTTP 401 或 403: 订阅密钥错误、未激活，或属于其他产品或环境。测试密钥仅在开启 Test environment 时有效。
在使用其他货币的店铺中未使用 API 运费: 请输入 CLP exchange rate。
API 运费含 IVA 还是不含？ 它们按 Chilexpress 的报价原样使用。如果您的店铺对配送费加税，且报价已包含 IVA，请将 Tax status 设为 None。
修改后运费看起来过时: 保存设置页面即可。这会清除缓存的运费和 comuna 列表。
许可证区块显示错误: 请按区块中的提示操作。例如，如果密钥已在其他域名上使用，请在 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now 以为新域名激活密钥。如果无法连接许可证服务器，插件会继续使用上次已知的状态运行。
卸载
停用插件会保留所有设置；它只会清除缓存的运费和 comuna 列表。要移除插件，请先停用，然后在 Plugins 页面删除。本插件的许可证密钥和许可证状态以及缓存始终会被删除。只有在 Remove data on uninstall 开启时，设置和区域方式才会被删除；否则它们会保留，以便日后重新安装。现有订单的配送行始终保留。
Chilexpress 是其各自所有者的商标。本插件与 Chilexpress 没有关联，也未获得 Chilexpress 的认可。