VibeFox Coordinadora for OpenCart — 帮助
系统要求
OpenCart: 3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP: 8.0 或更高版本。
Coordinadora API 密钥（仅用于实时报价）：实时报价来自 Coordinadora Cotizador，通过 Coordinadora 的 WooCommerce 服务获取，与 Coordinadora 官方插件使用的服务相同。Coordinadora 向有有效商务协议的客户签发 API 密钥。请咨询您的 Coordinadora 客户经理，或访问 wc.coordinadora.com。您还需要发货城市的 8 位 DANE 代码。没有密钥时，该方式仅使用固定价格。
商品：要获取实时报价，购物车中的每件商品都需要重量和三个尺寸（长、宽、高）。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
下载文件是一个 zip 压缩包，内含两个 OpenCart 版本的安装包。请解压到您的电脑上。其中包含 README.txt、OpenCart 3 安装包 vfd_coordinadora-oc3-(version).ocmod.zip 以及 OpenCart 4 安装包 vfd_coordinadora.ocmod.zip。只安装与您的 OpenCart 版本对应的安装包。两个版本使用相同的许可证密钥。
OpenCart 3
1. 在后台进入 Extensions > Installer，点击 Upload，选择文件 vfd_coordinadora-oc3-(version).ocmod.zip。本扩展不添加 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用 Installer，而是将本安装包中 upload 文件夹的内容复制到店铺的根目录。
2. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Coordinadora，点击 Install（绿色 + 按钮）。
3. 点击 Edit（铅笔按钮）打开设置页面。
4. 在 Edit 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入 License key，然后点击 Activate（参见许可证密钥）。
5. 输入 API 密钥、发货城市的 DANE 代码；若店铺默认币种不是 COP，还需输入 COP 汇率。至少为哥伦比亚添加一个固定价格作为备用（见配置）。开启 Enable Coordinadora 并点击 Save。
6. 确保您的商品有重量和尺寸。
OpenCart 4
1. 在后台进入 Extensions > Installer，点击 Upload，选择文件 vfd_coordinadora.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包将无法使用。
2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。
3. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Coordinadora，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按照 OpenCart 3 的第 4 至第 6 步输入许可证密钥和设置。两个版本的设置页面及其字段相同。
安装后，在您开启 Enable Coordinadora 并保存之前，该方式保持关闭。如果您卸载后再次安装扩展，将重新使用您保留的 Coordinadora 设置。
配置
所有设置都位于扩展页面：Extensions > Extensions > Shipping > VibeFox Coordinadora > Edit。这些设置适用于所有地理区域；您可以在 Conditions 中将该方式限制到某个地理区域和若干国家。各个部分列在左侧。页面底部的一个 Save 按钮可在不重新加载页面的情况下保存整个页面。保存后您会看到 Settings saved. Cached Coordinadora rates were cleared. 数字可以用小数点或逗号输入（9,99 = 9.99）。只有拥有本扩展修改权限的管理员用户才能保存设置。
如果 Name 为空或超过 64 个字符，某个数字或表格价格无效或为负数，COP per 1 unit of store currency 为 0，Min weight (kg) 大于 Max weight (kg)，或 Sort order 不是整数，则不会保存任何内容，页面会列出错误。
当实时报价无法工作或该方式会被隐藏时，页面会在设置上方显示警告：Origin city (DANE code) 为空或无效；当默认币种不是 COP 时，缺少 COP per 1 unit of store currency；没有哥伦比亚（或 *）的固定价格；没有 API 密钥且没有哥伦比亚的固定价格，因此该方式永远不会显示给哥伦比亚地址。如果店铺没有以 kg 为单位的重量类别或以 cm 为单位的长度类别，并且其默认单位不被扩展识别，也会出现警告；此时商品重量按 kg、尺寸按 cm 读取（请在 System > Localisation 中使用 kg、g、lb 或 oz 以及 cm、mm、m 或 in）。每次保存后警告都会更新。
通用
Enable Coordinadora:在结账时显示或隐藏 Coordinadora。默认：关闭。
Name:结账时显示给顾客的配送方式名称。默认：Coordinadora。必填，最多 64 个字符。
Sort order:Coordinadora 在结账配送方式中的位置。一个整数。
Coordinadora 实时报价
实时报价仅针对哥伦比亚境内的目的地请求。若只使用固定价格，请将密钥留空。
API key:您的 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 表示无限制。
Minimum order subtotal:仅当需配送商品的小计（扣除优惠券后，不含税）不低于此金额时显示该方式。留空则始终显示。
Free shipping:开启下方小计起的免运费。
Free shipping from:免运费起始的小计（扣除优惠券后，不含税）。仅在 Free shipping 开启时使用。此时不会向 API 发出请求。
Tax class:运费的税类，或 No tax（默认）。选择税类后，OpenCart 会在费率之上加收运费税。如果您的价格或 Coordinadora 报价已包含税费，请选择 No tax。
Geo zone:仅对该地理区域内的地址提供 Coordinadora。All zones（默认）表示无限制。地理区域在 System > Localisation > Geo Zones 中管理。
Countries:仅对这些目的国家提供 Coordinadora。留空则允许所有国家。此限制与 Geo zone 同时生效。
高级
Debug log:将运费计算写入 storage/logs/vfd_crd_debug.log.php（OpenCart 4 上为 system/storage/logs/vfd_crd_debug.log.php）。该文件无法通过网页读取。即使此选项关闭，API 错误和不完整的设置也始终会被记录。API 密钥和顾客地址从不记录。文件达到 5 MB 时，会被移至 vfd_crd_debug.old.log.php，并开始新的日志。
Log:显示调试日志的大小和最新条目。点击 Clear log 可清空。
Remove data on uninstall:开启后，卸载扩展会删除 Coordinadora 设置、缓存的报价和日志。关闭时（默认），所有内容都会保留，以便重新安装。
导入 / 导出
Export:点击 Download JSON，将设置保存为 JSON 文件。API 密钥不会被导出。
Import:粘贴之前导出的 JSON，然后点击 Import，即可恢复设置，例如在另一家店铺中使用。这些值的检查方式与普通保存相同。已保存的 API 密钥会被保留。
结账时的工作方式
OpenCart 显示配送方式时，会向扩展请求 Coordinadora 价格。如果设置了 Geo zone 且地址不在其中，则不提供 Coordinadora。只有 Requires Shipping 设为 Yes 的商品才会计入：其他商品不增加重量，也不计入报价。小计是需配送商品的价格，扣除优惠券折扣后、不含税。礼品卡、奖励积分和店铺余额不计入。扩展会先检查条件：允许的国家、购物车重量和订单最低小计。如果适用免运费，价格为 0，并且不会向 Coordinadora 发出任何请求。
对于配有 API 密钥的哥伦比亚地址，扩展会按以下顺序查找目的城市的 DANE 代码：城市字段中的 DANE 代码（哥伦比亚省份和城市结账模块会写入，例如 MEDELLIN (ANT) (05001000)）、8 位邮政编码，或内置的省会及约 40 个大城市列表。如果地址有地区（省），则会将列表中的城市与其核对。重音符号和大小写会被忽略。
然后，扩展会向 Coordinadora 发送目的地 DANE 代码，以及每件商品的发货城市、重量（kg）、尺寸（cm）、数量和申报价值（COP）。申报价值是扣除优惠券折扣后、不含税的商品行总额。商品的重量和长度类别会自动换算。Coordinadora 以 COP 返回价格，扩展会将其换算为您的默认币种，按该币种的小数位数取整，并以顾客的币种显示，同时附加所选 Tax class 的税费。每个报价缓存 1 小时。失败的请求会被记住 10 分钟，因此 Coordinadora 的故障永远不会拖慢每次结账页面刷新。API 超时时间为 10 秒。
当实时报价不可用时（API 错误、城市未知、商品缺少重量或尺寸、设置不完整），使用固定价格。如果没有固定价格，则该方式对此购物车隐藏。错误详情会写入调试日志，绝不会显示给顾客。
扩展只计算运费。它不创建运单或 guías，不打印面单，不预约取件（recogidas），不跟踪包裹，不代收货款（recaudo），也不提供 Droop 取件点；这些请使用 Coordinadora 门户。它不会向订单添加任何内容：订单显示配送方式名称和运费，与其他任何 OpenCart 配送方式相同。国际目的地使用固定价格。
在 OpenCart 4 上，顾客在结账页面的配送方式区块中点击 Choose，然后在 Shipping method options 窗口中选择 Coordinadora。该方式的工作方式与 OpenCart 3 相同。
许可证密钥
本扩展需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Coordinadora 是 Extensions > Extensions > Shipping > VibeFox Coordinadora > Edit 页面的第一个区块，位于设置上方。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会显示被遮蔽的密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺移除密钥）。它们下方有一行 Product: opencart-shipping-coordinadora，以及打开您 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 账户中释放该名额。
没有有效密钥时，Coordinadora 不会在结账时显示给顾客，也不会计算任何运费。以同一浏览器登录后台的管理员用户仍可在店铺中看到该方式，并标有 (unlicensed — visible to admins only)，因此您可以在购买密钥前设置和测试扩展。在 OpenCart 4 上，此预览不可用：店铺看不到后台的登录状态，因此没有有效密钥时，该方式对所有人都隐藏。打开一次 Edit 页面后，后台的 Dashboard 上会出现一条提醒。点击 × 可将其隐藏 7 天。现有订单不受影响。
许可证过期后，扩展仍会继续工作，但更新和支持需要续订。当您打开后台的 Dashboard 或 Edit 页面时，系统会自动再次检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载扩展时总会删除许可证密钥和许可证状态。
故障排除
Coordinadora 没有出现在结账页面：请检查许可证是否有效以及 Enable Coordinadora 是否开启。请查看扩展页面顶部的警告、Geo zone、Countries、重量限制以及 Minimum order subtotal。没有实时报价时，该国家或 * 必须存在固定价格。请确认商品的 Requires Shipping 设为 Yes。
未显示实时报价，只显示固定价格：开启 Debug log，刷新结账页面，并查看扩展页面上的 Log 字段。常见原因：目的城市无法识别、商品缺少重量或尺寸、缺少发货地 DANE 代码或 COP 汇率，或 Coordinadora 返回了错误。
目的城市无法识别：安装一个将 DANE 代码写入城市字段的哥伦比亚省份和城市结账模块。开发者可以通过 OpenCart 事件 vfd_coordinadora/dane_cities、vfd_coordinadora/destination_dane 和 vfd_coordinadora/api_url 映射更多城市或更改 API 地址；API 地址也可以通过设置 vfd_crd_api_url（用于测试）替换，该设置在设置页面上没有字段。
报价是否含税？报价即 Coordinadora 给出的价格。设置了 Tax class 后，OpenCart 会在其之上加收运费税；如果报价已含税，请选择 No tax。
更改后报价似乎过时：在扩展页面点击 Save。这会清除缓存的报价。
页面显示 "Warning: You do not have permission to modify VibeFox Coordinadora!"：您的管理员用户组可能只有查看设置的权限。请在 System > Users > User Groups 中为该用户组授予 extension/shipping/vfd_coordinadora（OpenCart 3）或 extension/vfd_coordinadora/shipping/vfd_coordinadora（OpenCart 4）的修改权限。
卸载
进入 Extensions > Extensions，选择类型 Shipping，然后点击 VibeFox Coordinadora 旁边的 Uninstall（红色 − 按钮）。本扩展的许可证密钥和许可证状态总会被删除。OpenCart 总会重置 Enable Coordinadora、Sort order、Tax class 和 Geo zone。缓存的报价总会被删除。如果 Remove data on uninstall 开启，Coordinadora 设置和日志也会被删除。如果关闭，其他设置会保留，并在您重新安装扩展时再次使用。现有订单保留其配送方式和运费。
在 OpenCart 4 上，要同时删除扩展的文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox Coordinadora 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）删除已上传的安装包。
Coordinadora 是其各自所有者的商标。本扩展与 Coordinadora 没有关联，也未获得 Coordinadora 的认可。