VibeFox Coordinadora for WooCommerce — 帮助
系统要求
WordPress：5.8 或更高版本。
WooCommerce：5.0 或更高版本，已安装并启用。未安装时插件无法启用。
PHP：8.0 或更高版本。
Coordinadora API 密钥（仅用于实时报价）：实时报价来自 Coordinadora Cotizador，通过 Coordinadora WooCommerce 服务获取，与官方 Coordinadora 插件使用的是同一服务。Coordinadora 将 API 密钥发放给拥有有效商业协议的客户。请咨询您的 Coordinadora 客户经理，或访问 wc.coordinadora.com。您还需要发货城市的 8 位 DANE 代码。没有密钥时，该配送方式仅使用固定价格。
商品：要获取实时报价，购物车中的每件商品都需要设置重量和尺寸（长、宽、高）。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥仅适用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 vfd_coordinadora 文件夹上传至 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置页面：WooCommerce > Settings > Shipping > VibeFox Coordinadora，或在插件页面点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 输入 API 密钥、发货城市的 DANE 代码；如果店铺货币不是 COP，还需输入 COP 汇率。至少为哥伦比亚添加一个固定价格作为备用（参见「配置」）。
6. 在 WooCommerce > Settings > Shipping > Shipping zones 中，将 VibeFox Coordinadora 添加到覆盖哥伦比亚的配送区域；或开启 Ignore shipping zones 并选择国家。
7. 确保您的商品已设置重量和尺寸。
配置
所有设置位于同一页面：WooCommerce > Settings > Shipping > VibeFox Coordinadora。它们适用于所有配送区域。将该方式添加到某个区域时，区域窗口只有一个字段：
Title (zone)：该区域中向顾客显示的配送方式名称。留空则使用全局的 Name。
当实时报价无法工作或该方式会被隐藏时，设置页面顶部会显示警告：发货 DANE 代码缺失或无效、COP 汇率缺失，或没有哥伦比亚的固定价格。每次保存设置时，缓存的报价都会被清除。数字可以用小数点或逗号输入（9,99 = 9.99）。
常规
Enable/Disable：一次性在所有区域启用或禁用 Coordinadora。
Name：结账时向顾客显示的配送方式名称。默认：Coordinadora。区域的 Title 会覆盖此名称。
Tax status：Taxable 会在运费之上加收 WooCommerce 配送税，None 则不加收。如果您的价格或 Coordinadora 报价已包含税费，请选择 None。
Coordinadora 实时报价
实时报价针对哥伦比亚境内的目的地请求。将密钥留空则仅使用固定价格。
API key：您从 Coordinadora 获得的 WooCommerce API 密钥。该密钥绝不会写入日志。
Origin city (DANE code)：您发货城市的 8 位 DANE 代码，例如 11001000 Bogotá、05001000 Medellín、76001000 Cali 或 08001000 Barranquilla。也接受 5 位市镇代码，并会补齐为 8 位。
COP per 1 unit of store currency：Coordinadora 以哥伦比亚比索报价。如果您的店铺货币不是 COP，请填写 1 个单位本币可兑换的 COP 数额，例如 4300。该汇率也用于以 COP 发送申报价值。留空则不使用实时报价。如果您的店铺货币是 COP，请留空。
固定价格（在没有 API 密钥、目的地在哥伦比亚以外，以及实时报价不可用时作为备用使用）
Prices by country：一个国家表，包含 Price 列，以及以店铺货币计的可选包裹尺寸价格。尺寸根据购物车重量确定：XS 为 1 kg 以下，S 为 1–2 kg，M 为 2–3 kg，L 为 3–5 kg，XL 为 5 kg 以上。当尺寸列为 0 或为空时，使用 Price。点击 + Add country 添加一行，点击叉号删除一行。* All other countries 适用于没有自有行的国家。没有行（且不是 *）的国家不会获得固定价格。Price 为 0 且没有尺寸价格的行表示免运费。
Fixed price per：Order 只收取一次价格。Item (price × quantity) 则按购物车中的商品数量相乘。这仅适用于固定价格；Coordinadora 实时报价始终覆盖整个订单。
条件
Min weight (kg)：购物车重量低于此值时隐藏该方式。0 表示不限制。
Max weight (kg)：购物车重量高于此值时隐藏该方式。默认：25。0 表示不限制。
Minimum order subtotal：仅当购物车小计至少达到此金额时才显示该方式。留空则始终显示。
Excluded shipping classes：如果购物车中某件商品属于这些 WooCommerce 配送类别之一，则隐藏该方式。
Free shipping：开启以在下方小计达到一定金额时免运费。
Free shipping from：购物车小计达到此金额时运费免费。仅在 Free shipping 开启时使用。此时不会发出 API 请求。
无配送区域时的可用性
Ignore shipping zones：即使未添加到配送区域，也为下列国家提供该方式。
Countries：该模式下的目的国家。留空则使用店铺可配送的所有国家。此字段仅在 Ignore shipping zones 开启时使用。
高级
Debug log：将运费计算记录到 WooCommerce > Status > Logs，来源为 vfd-coordinadora。即使关闭此选项，API 错误仍会始终记录。API 密钥和顾客地址绝不会被记录。
Remove data on uninstall：开启后，删除插件会移除其设置、区域方式和缓存的报价。停用插件绝不会删除数据。
结账时的工作方式
当顾客输入配送地址时，WooCommerce 会向插件请求运费报价。插件首先检查条件：购物车重量、最低订单小计和排除的配送类别。如果适用免运费，顾客将获得免费报价，并且不会向 Coordinadora 发送请求。
对于有 API 密钥的哥伦比亚地址，插件按以下顺序查找目的地城市的 DANE 代码：城市字段中的 DANE 代码（哥伦比亚省和城市结账插件会写入该代码，例如 MEDELLIN (ANT) (05001000)）、8 位邮政编码，或内置的省会城市及约 40 个最大城市列表。列表中的城市会与所选省份进行核对。忽略重音符号和大小写。
随后，插件会向 Coordinadora 发送目的地 DANE 代码，以及每件商品的发货城市、重量（kg）、尺寸（cm）、数量和申报价值（COP）。店铺单位将自动换算。Coordinadora 返回以 COP 计的价格，插件再将其转换为您店铺的货币。每个报价缓存 1 小时。失败的请求会记住 10 分钟，因此 Coordinadora 的故障不会拖慢每次结账页面刷新。API 超时时间为 10 秒。
当实时报价不可用（API 错误、城市无法识别、商品缺少重量或尺寸、设置缺失）时，使用固定价格。如果没有固定价格，则隐藏该方式。错误详情会写入 WooCommerce 日志，绝不会显示给顾客。
该方式适用于经典结账以及购物车和结账区块。它兼容 WooCommerce 高性能订单存储（HPOS）。
插件仅计算运费。它不会创建运单或快递单（guías）、打印面单、预约取件（recogidas）、跟踪包裹、代收货款（recaudo）或提供 Droop 取件点；请使用 Coordinadora 门户处理这些事务。它不提供当日达报价，国际目的地使用固定价格。
许可证密钥
本插件需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Shipping > VibeFox Coordinadora 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期至何时以及您的域名。使用 Check now 重新检查状态，Change key 输入其他密钥，Remove key 将其从本站点移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。
一个密钥仅适用于一个域名。从站点移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，Coordinadora 不会在结账时向顾客显示。已登录的店铺管理员仍可看到，并标注 (unlicensed — visible to admins only)，以便您在购买密钥前设置和测试插件。插件页面和 WooCommerce 页面上会显示提醒。现有订单不受影响。
许可证过期后，插件仍可继续工作，但更新和支持需要续费。状态会在后台自动重新检查。
故障排除
结账时不显示 Coordinadora：请检查许可证是否有效、Enable/Disable 是否开启、该方式是否已添加到顾客所在国家的区域（或已开启 Ignore shipping zones 且允许该国家）。检查重量限制、Minimum order subtotal 和 Excluded shipping classes。在没有实时报价的情况下，该国家或 * 必须存在固定价格。
未显示实时报价，只显示固定价格：开启 Debug log，重新加载结账页面，然后打开 WooCommerce > Status > Logs，来源为 vfd-coordinadora。常见原因：无法识别目的地城市、商品缺少重量或尺寸、缺少发货 DANE 代码或 COP 汇率，或 Coordinadora 返回了错误。
无法识别目的地城市：安装一个能将 DANE 代码写入城市字段的哥伦比亚省和城市结账插件。开发者可以使用 vfd_crd_dane_cities 和 vfd_crd_destination_dane 过滤器映射更多城市。
运费是否含税？运费为 Coordinadora 报出的金额。将 Tax status 设为 Taxable 时，WooCommerce 会在其之上加收配送税；如果报价已包含税费，请选择 None。
更改后运费看起来过时：保存设置页面。这会清除缓存的报价。
许可证区块显示错误：按照区块中的提示操作。例如，如果该密钥已在其他域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now 为新域名激活密钥。如果无法连接许可证服务器，插件将继续使用最后已知的状态运行。
卸载
停用插件会保留所有设置；它只会清除缓存的报价。要删除插件，请先停用，然后在 Plugins 页面删除。本插件的许可证密钥和许可证状态以及缓存的报价总会被删除。只有开启了 Remove data on uninstall 时，设置和区域方式才会被删除；否则它们会保留，供以后重新安装时使用。现有订单会保留其运费行。
Coordinadora 是其各自所有者的商标。本插件与 Coordinadora 无关联，也未获得其认可。