VibeFox Coordinadora for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝在更早的 PHP 版本上安装。
Coordinadora API 密钥（仅用于实时报价）：实时报价来自 Coordinadora Cotizador，通过 Coordinadora WooCommerce 服务获取，与官方 Coordinadora 插件使用的是同一服务。Coordinadora 将 API 密钥发放给拥有有效商业协议的客户。请咨询您的 Coordinadora 客户经理，或访问 wc.coordinadora.com。您还需要发货城市的 8 位 DANE 代码。没有密钥时，承运商仅使用固定价格。
商品：进行实时报价时，购物车中的每件商品都需要设置重量和尺寸（宽、高、深）。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或之后在模块列表中找到 VibeFox Coordinadora，再点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥粘贴到 License key 中，然后点击 Activate（见许可证密钥）。
4. 输入 API 密钥、发货城市的 DANE 代码，并且如果您的默认货币不是 COP，还需输入 COP 汇率。至少为哥伦比亚添加一个固定价格作为备用（见"配置"）。点击 Save。
5. 确保哥伦比亚在您的店铺中已启用，并且您的商品已设置重量和尺寸。
安装时，模块会创建 Coordinadora 承运商，其配送时间文本为 Courier delivery in Colombia。该承运商分配给所有区域和所有客户组。您可以在 Shipping > Carriers 中更改区域、客户组、配送时间、徽标和尺寸限制。请勿在那里设置价格：价格始终来自模块。
配置
所有设置都在模块页面上：Modules > Module Manager > VibeFox Coordinadora > Configure。它们适用于承运商的所有区域。每个部分都有自己的 Save 按钮，点击后会保存整个页面。每次保存也会清除缓存的 Coordinadora 报价。数字可以用小数点或逗号输入（9,99 = 9.99）。
当数字或表格价格无效或为负数、COP per 1 unit of store currency 为 0、Min weight 大于 Max weight，或 Name 超过 64 个字符时，页面会拒绝保存并显示错误。在您更正之前，不会保存任何内容。
当实时报价无法工作或承运商将被隐藏时，页面顶部会显示警告：Origin city (DANE code) 为空或无效；默认货币不是 COP 时缺少 COP per 1 unit of store currency；或没有哥伦比亚（或 *）的固定价格。如果没有 API 密钥且没有此类固定价格，承运商永远不会显示给哥伦比亚地址。如果模块无法识别店铺在 International > Localization（Local units）中的重量或尺寸单位，也会显示警告；此时商品重量将按 kg、尺寸按 cm 读取。
通用
Enable Coordinadora：开启或关闭承运商。这与 Shipping > Carriers 中的承运商状态使用同一开关。
Name：结账时显示给顾客的承运商名称。默认：Coordinadora。必填。
Tax：承运商的税务规则，或 No tax。选择规则后，PrestaShop 会在运费之上加收配送税。如果您的价格或 Coordinadora 报价已含税，请选择 No tax。
Coordinadora 实时运费
实时报价针对哥伦比亚境内的目的地请求。若只使用固定价格，请将密钥留空。
API key：Coordinadora 提供的 Coordinadora WooCommerce API 密钥。保存后，该字段保持为空，并显示 Saved — leave empty to keep it. 只有需要更改时才输入新值。密钥永远不会写入日志。
Remove the saved API key：仅在已保存密钥时显示。勾选并点击 Save 即可删除密钥；之后承运商只使用固定价格。
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 发送申报价值。留空则不使用实时报价。汇率必须大于 0。如果您的默认货币是 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 表示无限制。不能低于 Min weight。
Minimum order subtotal：仅当购物车小计（折扣后、税前）至少达到此金额时才显示承运商。留空则始终显示。
Free shipping：开启下方小计起的免费配送。
Free shipping from：购物车小计（折扣后、税前）达到此金额后运费免费。仅在 Free shipping 开启时使用。在这种情况下不会发出 API 请求。
Countries：仅为这些目的国家提供 Coordinadora。仅列出已启用的国家。留空则允许承运商区域内的所有国家。
高级
Debug log：将运费计算写入模块文件夹中的 logs/vfd_crd_debug.log.php。该文件无法通过网页打开。即使关闭此选项，API 错误和不完整的设置也始终会被记录。API 密钥和顾客地址永远不会被记录。
Log：显示调试日志的大小和最新条目。点击 Clear log 可清空。
Remove data on uninstall：开启时，卸载模块会删除 Coordinadora 设置、承运商、缓存的报价和日志。关闭时，所有内容都会保留，以便重新安装。
结账时的工作方式
在配送步骤，PrestaShop 向模块请求 Coordinadora 价格。只计算实物商品：虚拟商品不增加重量，也不计入报价。模块首先检查条件：允许的国家、购物车重量和最低订单小计。如果适用免运费，价格为 0，不会向 Coordinadora 发送请求。
对于有 API 密钥且位于哥伦比亚的地址，模块按以下顺序查找目的地城市的 DANE 代码：城市字段中的 DANE 代码（哥伦比亚省份和城市结账模块会写入，例如 MEDELLIN (ANT) (05001000)）、8 位邮政编码，或内置的省会城市及约 40 个最大城市列表。如果地址包含省份（州），则会对照该省检查列表中的城市。忽略重音符号和大小写。
随后，模块会向 Coordinadora 发送目的地 DANE 代码，以及每件商品的发货城市、重量（kg）、尺寸（cm）、数量和申报价值（COP）。申报价值为该商品行在税前、购物车折扣前的总额。店铺单位将自动换算。Coordinadora 返回 COP 价格，模块将其换算为您的默认货币，再换算为顾客的购物车货币。每个报价缓存 1 小时。失败的请求会记住 10 分钟，因此 Coordinadora 故障绝不会拖慢每次结账刷新。API 超时时间为 10 秒。
当实时报价不可用（API 错误、城市未知、商品缺少重量或尺寸、设置缺失）时，使用固定价格。如果没有固定价格，则为该购物车隐藏承运商。错误详情会记录到调试日志，绝不会显示给顾客。
如果您在承运商已有订单后，在 Shipping > Carriers 中编辑该承运商，PrestaShop 会将其保存为新的承运商版本。模块会自动跟随新版本。
模块仅计算运费。它不会创建运单或快递单（guías）、打印面单、预约取件（recogidas）、跟踪包裹、代收货款（recaudo），也不提供 Droop 取件点；请为此使用 Coordinadora 门户。国际目的地使用固定价格。
许可证密钥
模块需要使用来自 vibefox.net 的 VibeFox 许可证密钥。模块 Configure 页面上方的许可证区块 License — VibeFox Coordinadora 位于 Modules > Module Manager > VibeFox Coordinadora > Configure 中，位于设置上方。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从此店铺中移除密钥）。其下方是 Product: presta-shipping-coordinadora 一行，以及打开您 vibefox.net 账户的链接 Manage licenses and domains in your account。只有拥有该模块 Configure 权限的员工才能更改密钥。该区块的文本跟随后台语言（包括英文和俄文）。
如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或 License expired on 加某个日期。店铺地址更改后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，模块会继续使用最后已知的状态运行。
一个密钥只能用于一个域名：主店铺的域名，多店铺配置中同样如此。从店铺中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。
没有有效密钥时，Coordinadora 承运商不会显示给结账时的顾客，也不会计算运费。PrestaShop 前台无法得知您已登录后台，因此承运商对您也会隐藏：您可以在购买密钥前设置模块，但无法在结账时测试。Modules > Module Manager 的 Alerts 标签页会出现一条提醒。现有订单不受影响。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。在您使用后台期间，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
Coordinadora 未出现在结账页面：请检查许可证是否有效，以及 Enable Coordinadora 是否已开启。在 Shipping > Carriers 中，检查承运商是否覆盖顾客所在国家的区域以及顾客的客户组。检查 Countries、重量限制和 Minimum order subtotal。没有实时报价时，必须存在该国家或 * 的固定价格。商品还可以在商品页面中限制为特定承运商。
未显示实时运费，只显示固定价格：开启 Debug log，重新加载结账页面，并查看模块页面上的 Log 字段。常见原因：无法识别目的地城市、某件商品没有重量或尺寸、缺少发货城市的 DANE 代码或 COP 汇率，或 Coordinadora 返回了错误。
无法识别目的地城市：安装一个能将 DANE 代码写入城市字段的哥伦比亚省份和城市结账模块。开发者可以使用模块钩子 actionVfdCrdDaneCities 和 actionVfdCrdDestinationDane 映射更多城市，或使用 actionVfdCrdApiUrl 更改 API 地址。
报价是否含税？报价即 Coordinadora 给出的价格。设置 Tax 规则后，PrestaShop 会在其上加收配送税；如果报价已包含税款，请选择 No tax。
更改后报价看起来过时：在模块页面点击 Save。这会清除缓存的报价。
页面提示未找到 Coordinadora 承运商：该承运商已在 Shipping > Carriers 中删除。请在 Modules > Module Manager 中重置模块以重新创建。
卸载
进入 Modules > Module Manager，打开 VibeFox Coordinadora 旁边的菜单，选择 Uninstall。许可证密钥和许可证状态，以及缓存的报价，始终会被删除。如果 Remove data on uninstall 已开启，承运商会被删除（订单保留历史记录），设置和日志也会被删除。如果已关闭，承运商仅被停用，所有设置都会保留。重新安装模块或执行 Reset，会使已保存的承运商恢复其之前的状态：您关闭的承运商仍保持关闭。
Coordinadora 是其各自所有者的商标。本模块与 Coordinadora 没有关联，也未获得其认可。