VibeFox Cargoson for OpenCart — 帮助
系统要求
OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP：8.0 或更高版本。
Cargoson 账户（仅用于实时价格）：实时价格使用 Cargoson 运费报价 API。运费报价需要带 API 访问权限的 Cargoson 订阅（撰写本文时为 Advanced 套餐或更高）。API 密钥在您的 Cargoson 账户中签发；如果您的套餐不显示 API 设置，请联系 Cargoson 支持。价格来自与该账户相连的承运商和价格表。如果只使用固定价格，则无需 Cargoson 账户。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
下载包是一个 zip 文件，内含适用于两种 OpenCart 版本的安装包。请解压到您的计算机上。其中包括 README.txt、适用于 OpenCart 3 的安装包 vfd_cargoson-oc3-（版本）.ocmod.zip，以及适用于 OpenCart 4 的安装包 vfd_cargoson.ocmod.zip。只安装适用于您 OpenCart 版本的安装包。两种版本使用相同的许可证密钥。
OpenCart 3
1. 在后台进入 Extensions > Installer，点击 Upload，选择文件 vfd_cargoson-oc3-（版本）.ocmod.zip。本扩展不添加 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用 Installer，而是将本安装包中 upload 文件夹的内容复制到商店的根目录中。
2. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Cargoson，点击 Install（绿色的 + 按钮）。
3. 点击 Edit（铅笔按钮）打开设置页面。
4. 在 Edit 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入 License key，然后点击 Activate（参见许可证密钥）。
5. 选择运费的计算方式，并填写相应部分：固定价格，以及对于实时价格，填写 API 密钥和揽收邮政编码（参见配置）。开启 Enable Cargoson 并点击 Save。
OpenCart 4
1. 在后台进入 Extensions > Installer，点击 Upload，选择文件 vfd_cargoson.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包将无法使用。
2. 安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色的 + 按钮）。
3. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Cargoson，点击 Install（绿色的 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按照 OpenCart 3 的第 4 和第 5 步输入许可证密钥并设置。两个版本的设置页面及其字段相同。
安装后，在您开启 Enable Cargoson 并保存之前，该配送方式处于关闭状态。如果您在卸载后重新安装扩展，之前保留的 Cargoson 设置将再次生效。
配置
所有设置都位于扩展页面：Extensions > Extensions > Shipping > VibeFox Cargoson > Edit。各部分列在左侧。点击页面底部的一个 Save 按钮即可保存整个页面，无需重新加载。保存后，您会看到 Settings saved. Cached Cargoson prices were cleared. 小数可以用点或逗号输入。如果 Method title 为空或超过 64 个字符，数字字段包含文本或负数，Currency conversion rate 为 0，Minimum weight (kg) 大于 Maximum weight (kg)，Price currency 不是 3 位字母代码，价格表中某行的国家或价格无效，或 Sort order 不是整数，则不会保存任何内容，页面会列出错误。如果扩展无法识别商店的重量单位，保存后的警告会说明产品重量将按千克处理；请在 System > Localisation > Weight Classes 中添加单位为 kg 的重量类别。只有拥有本扩展修改权限的管理员用户才能保存设置。
常规
顾客只会看到一个 Cargoson 费率。您可以在 Availability 中将该方式限制在某个地理区域或某些国家。
Enable Cargoson：在结账时显示或隐藏 Cargoson。默认：关闭。
Method title：顾客在购物车和结账时看到的配送方式名称，最多 64 个字符。默认：Cargoson。必填。
Shipping cost：价格的计算方式。
实时价格缺失的原因会写入调试日志，且绝不会显示给顾客。
Sort order：Cargoson 在结账时配送方式中的排列位置。一个整数。
Cargoson API（仅实时价格需要）
API key：您 Cargoson 账户中的 API 密钥。它只会发送给 Cargoson，绝不会显示给顾客，也不会写入日志。保存后，该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。
Remove the saved API key：开启并保存即可删除已保存的密钥。
Carrier：使用哪些价格。顾客只会看到一个费率。
Package type code：随价格查询一起发送的 Cargoson 包裹类型。默认：CLL。Cargoson API 示例使用 EUR（EUR 托盘）和 FIN（FIN 托盘）。对于包裹，请使用您 Cargoson 账户的包裹代码。订单会按购物车的总重量作为一个包裹发送。
Price currency：您 Cargoson 账户中价格的货币，使用 3 位字母代码。默认：EUR。API 返回的金额不含货币代码。
Currency conversion rate：仅当价格货币与商店默认货币不同时需要：Cargoson 货币的 1 个单位 = 您默认货币的 X 个单位。留空则拒绝此类价格，确保顾客绝不会以错误的货币付费。
发货地址（揽收地址）（用于实时价格）
Collection country：您发货所在的国家。第一个选项 Store country 使用您商店所在的国家。
Collection postcode：您发货所在的邮政编码。实时价格需要此项。OpenCart 中的商店地址是自由文本，因此绝不会从中获取邮政编码：请在此处输入。
发送给 Cargoson 的揽收日期为商店时区的当天；若为周末，则为下一个星期一。
固定价格（当 Shipping cost 为 Fixed prices 时使用，并作为实时价格的备用）
Price per country and size：一个由行组成的列表，每行包含 Country、Price，以及按购物车重量划分的价格（以商店默认货币计，不含税）：XS 至 1 kg，S 至 2 kg，M 至 3 kg，L 至 5 kg，XL 超过 5 kg。尺寸价格为空或为 0 时使用 Price 列；Price 为空表示该尺寸没有固定费率。点击 Add country 添加一行。选择 * All other countries 可为所有没有自己行的国家设置价格。没有行的国家（当不存在 * 行时）没有固定费率，因此该方式会对其隐藏。价格必须为大于或等于 0 的数字。空行会被忽略。
Fixed price applies：Per order（默认）只收取一次价格。Per item (price × quantity) 则按购物车中的商品数量相乘。Cargoson 实时价格始终按每次发货计算。
条件
Minimum weight (kg)：购物车重量低于此值时隐藏该方式。0 表示无限制（默认）。
Maximum weight (kg)：购物车重量高于此值时隐藏该方式。默认：25。0 表示无限制。
Minimum order amount：仅当需要配送的商品小计（使用优惠券之后，不含税）达到此金额时才显示该方式。留空则始终显示。
Free shipping：开启后，在下方金额起免运费。
Free shipping from：需要配送的商品小计（使用优惠券之后，不含税）达到此金额时，配送免费。仅在 Free shipping 开启时使用。
Tax class：运费的税类，或 No tax（默认）。Cargoson 中的承运商价格通常不含增值税。如果您的价格已含税，请选择 No tax。
可用性
Geo zone：仅向此地理区域内的地址提供 Cargoson。All zones（默认）表示不限制。地理区域在 System > Localisation > Geo Zones 中管理。
Ignore shipping zones：不检查地理区域；由下方的国家列表决定。
Countries：该模式的目的地国家。留空则允许所有国家。仅在 Ignore shipping zones 开启时使用此字段。
高级
Debug log：将每次运费计算记录到 storage/logs/vfd_cgs_debug.log.php。该文件无法通过网页读取。API 错误和被拒绝的价格始终会被记录，即使此选项关闭。API 密钥和顾客邮政编码绝不会被记录。当文件达到 5 MB 时，它会被移动到 vfd_cgs_debug.old.log.php，并开始新的日志。
Log：显示调试日志的大小和最新条目。点击 Clear log 可清空日志。
Remove data on uninstall：开启后，卸载扩展会删除 Cargoson 设置、缓存的价格和日志。关闭（默认）时，它们会保留，以便重新安装。已下订单的 Cargoson 报价始终保留。
导入 / 导出
Export：点击 Download JSON，将设置保存为 JSON 文件。API 密钥不会被导出。
Import：粘贴之前导出的 JSON，并点击 Import 以恢复设置，例如在另一家店铺中。这些值会像正常保存时一样进行检查。已保存的 API 密钥会被保留。
结账时的工作方式
当 OpenCart 显示配送方式时，它会向扩展请求 Cargoson 价格。如果设置了 Geo zone（且 Ignore shipping zones 关闭），而地址在该区域之外，则不会提供 Cargoson。只有 Requires Shipping 设为 Yes 的商品才会计算在内：其他商品不增加重量，也不计入订单金额。商品重量会从其重量类别换算为千克。随后扩展检查条件：允许的国家、购物车重量和最低订单金额。订单金额是需要配送的商品的价格，在扣除优惠券折扣之后、税费之前。礼品卡、奖励积分和商店余额不计入在内。如果适用免运费，价格为 0，并且不会向 Cargoson 发送请求。
在固定模式下，价格取自表格。在实时模式下，扩展会向 Cargoson 发送揽收日期、揽收国家和邮政编码、配送国家和邮政编码，以及一个包裹（包含包裹类型代码和购物车的总重量，至少 0.1 kg）。只有当配送地址有邮政编码时才会请求实时价格。Cargoson 会返回您承运商的价格；扩展选择最便宜的一个（若已选择承运商，则从该承运商中选择），并在需要时将其转换为您的默认货币。价格以您的默认货币计算，按其小数位数取整，并以顾客的货币显示，并含有所选 Tax class 的税费。
每个响应缓存 1 小时，因此相同的购物车不会触发新的请求。失败的请求缓存 10 分钟，因此结账时不会在每次刷新时都等待 Cargoson。API 超时时间为 10 秒。如果 Cargoson 返回错误、该路线没有价格，或返回的是没有换算汇率的其他货币价格，顾客不会看到任何错误：该方式会被隐藏，或在备用模式下使用固定价格。
扩展仅计算运费。它不会在 Cargoson 中创建发货或预订，不打印面单，也不跟踪包裹；顾客无法选择包裹柜或取件点。购物车会按总重量作为一个包裹报价；不发送包裹尺寸。只显示最低的一个价格，而不是承运商列表。
在 OpenCart 4 中，顾客在结账页面的配送方式区块中点击 Choose，并在 Shipping method options 窗口中选择 Cargoson。该方式的工作方式与 OpenCart 3 相同。
订单
当顾客使用 Cargoson 下单时，结账时计算的费率会随订单保存。在 Sales > Orders 中，订单页面会显示一个 Cargoson shipping 面板：
Carrier、Service 和 Cargoson service ID：报价的 Cargoson 承运商和服务，在使用实时价格时显示。
Price source：Cargoson live price、Fixed price 或 Free shipping threshold。
Calculated price (excl. tax)：以您商店默认货币显示的价格。
即使该方式已关闭，该面板仍会显示。在 OpenCart 4 中，订单在确认步骤时创建一次，并在顾客每次返回该步骤时更新，因此保存的报价是结账时最后计算的报价；如果顾客切换到其他配送方式，则会移除该订单的 Cargoson 报价。在后台修改订单不会更改报价，报价之后也不会更改。请在 Cargoson 中或通过其自有集成预订发货。
许可证密钥
本扩展需要来自 vibefox.net 的 VibeFox 许可证密钥。扩展的 License — VibeFox Cargoson 许可证区块位于 Extensions > Extensions > Shipping > VibeFox Cargoson > Edit 页面中设置的上方，是第一个区块。将密钥输入 License key 并点击 Activate。之后，该区块会显示隐藏的密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now 用于重新检查状态，Change key 用于输入其他密钥，Remove key 用于从此商店移除密钥。其下方有一行 Product: opencart-shipping-cargoson，以及链接 Manage licenses and domains in your account，点击即可打开您的 vibefox.net 账户。只有拥有本扩展 Modify 权限的管理员用户才能更改密钥。区块的文字跟随后台语言显示（包括英语和俄语）。
如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或带有日期的 License expired on。商店地址更改后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展将继续使用最后已知的状态工作。
一个密钥只能用于一个域名：即 OpenCart 配置中的商店地址。从商店中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。
没有有效密钥时，结账时不会向顾客显示 Cargoson，也不会计算任何费率。在同一浏览器中登录后台的管理员用户，仍会在商店中看到该方式，并标记为 (unlicensed — visible to admins only)，以便您在购买密钥之前设置和测试扩展。在 OpenCart 4 中此预览不可用：商店看不到后台登录状态，因此没有有效密钥时，该方式对所有人隐藏。打开一次 Edit 页面后，后台 Dashboard 上会出现提醒。点击 × 关闭它，可隐藏 7 天。现有订单不受影响。
许可证到期后，扩展仍会继续工作，但更新和支持需要续费。当您打开后台的 Dashboard 或 Edit 页面时，系统会自动再次检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展时始终会删除许可证密钥和许可证状态。
故障排除
Cargoson 未出现在结账页面：请检查许可证是否有效，以及 Enable Cargoson 是否已开启。检查 Geo zone（或 Ignore shipping zones 和 Countries）、重量限制和 Minimum order amount。在固定模式下，检查该国家或 * All other countries 是否有该购物车尺寸的价格。检查产品的 Requires Shipping 是否设为 Yes。
实时价格未出现：查看扩展页面上的 Log 字段。API 错误始终会被记录；开启 Debug log 可查看每次计算。常见原因：尚未输入配送邮政编码、缺少 Collection postcode、API 密钥被拒绝（密钥错误或已过期，或您的 Cargoson 套餐没有 API 访问权限）、该路线或重量没有承运商，或价格为其他货币。在使用 Cargoson live prices, fixed prices if the API fails 时，您解决问题期间，顾客仍会获得固定价格。
Cargoson 拒绝包裹类型：请使用您的 Cargoson 账户在 Package type code 中使用的包裹代码。原因会显示在日志中。
其他货币的价格被拒绝：将 Price currency 设为您 Cargoson 价格的货币，并输入 Currency conversion rate。
运费被重复征税：您的 Cargoson 价格已含增值税。请将 Tax class 设为 No tax。
修改后费率看起来过时：在扩展页面点击 Save。这将清除已缓存的 Cargoson 价格。
页面显示 "Warning: You do not have permission to modify VibeFox Cargoson!"：您的管理员用户组可能只能查看设置。请在 System > Users > User Groups 中为该组授予 extension/shipping/vfd_cargoson（OpenCart 3）或 extension/vfd_cargoson/shipping/vfd_cargoson（OpenCart 4）的修改权限。
面向开发人员：Cargoson API 地址可以通过设置 vfd_cgs_api_url（用于测试）进行替换；设置页面上没有该项的字段。
卸载
进入 Extensions > Extensions，选择类型 Shipping，然后点击 VibeFox Cargoson 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被移除。OpenCart 总会重置 Enable Cargoson、Sort order、Tax class 和 Geo zone。缓存的价格始终会被删除。如果 Remove data on uninstall 已开启，则 Cargoson 设置和调试日志也会被删除。如果关闭，其他设置将保留，并在您重新安装扩展时再次使用。已下订单的 Cargoson 报价永远不会被删除，现有订单保留其配送方式和费用。
在 OpenCart 4 中，若要同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox Cargoson 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。
Cargoson 是其各自所有者的商标。本扩展与 Cargoson 无关联，也未获得其认可。