VibeFox Cargoson for WooCommerce — 帮助
系统要求
WordPress: 5.8 或更高版本。
WooCommerce: 5.0 或更高版本，须已安装并启用。没有 WooCommerce，插件无法激活。
PHP: 8.0 或更高版本。
Cargoson 账户（仅实时价格需要）：实时价格使用 Cargoson 货运价格 API。货运价格查询需要带 API 访问权限的 Cargoson 订阅（撰写本文时为 Advanced 或更高套餐）。API 密钥由您的 Cargoson 账户签发；如果您的套餐中看不到 API 设置，请联系 Cargoson 支持。价格来自与该账户相连的承运商和价格表。如果只使用固定价格，则无需 Cargoson 账户。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 vfd_cargoson 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Shipping > VibeFox Cargoson，或在 Plugins 页面点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 选择运费的计算方式，并填写相应的部分：固定价格，以及（如使用实时价格）API 密钥和发货邮政编码（参见配置）。
6. 在 WooCommerce > Settings > Shipping > Shipping zones 中，将 VibeFox Cargoson 添加到某个配送区域；或者开启 Ignore shipping zones 并选择国家。
配置
所有设置都位于同一页面：WooCommerce > Settings > Shipping > VibeFox Cargoson。这些设置适用于所有配送区域。将该方式添加到某个区域时，区域窗口中只有一个字段：
Title (zone): 此区域向顾客显示的名称。留空则使用全局的 Method title。
每次保存设置时，缓存的 Cargoson 价格都会被清除。小数可以用小数点或逗号输入。
General
Enable/Disable: 同时在所有区域启用或停用该方式。
Method title: 在购物车和结账页面显示的配送方式名称。默认：Cargoson。区域可以覆盖此名称。
Shipping cost: 价格的计算方式。
实时价格缺失的原因会写入 WooCommerce 日志，且绝不会显示给顾客。
Cargoson API（仅实时价格需要）
API key: 您 Cargoson 账户中的 API 密钥。它只会发送至 cargoson.com，绝不会显示给顾客，也不会写入日志。
Carrier: 使用哪家承运商的价格。顾客只会看到一个价格。
Package type code: 随价格查询发送的 Cargoson 包裹类型。默认：CLL。Cargoson API 示例使用 EUR（EUR 托盘）和 FIN（FIN 托盘）。对于包裹，请使用您 Cargoson 账户的包裹代码。订单将以购物车总重量作为一个包裹发送。
Price currency: 您 Cargoson 账户中价格的币种，使用 3 位字母代码。默认：EUR。API 返回的金额不含币种代码。
Currency conversion rate: 仅当价格币种与商店币种不同时需要：1 个 Cargoson 币种单位 = X 个商店币种单位。留空则拒绝此类价格，确保顾客绝不会以错误的币种付款。
Ship from (collection address)（用于实时价格）
Collection country: 您的发货国家。默认为您的商店所在国家。
Collection postcode: 您的发货邮政编码。Cargoson 要求填写。如果留空且发货国家为商店所在国家，则使用 WooCommerce > Settings > General 中的商店邮政编码。
发送给 Cargoson 的取件日期为当天；如果当天是周末，则为下一个星期一。
Fixed prices（当 Shipping cost 为 Fixed prices 时使用，也作为实时价格的备用方案）
Price per country and size: 国家表格，包含 Price 列，以及按购物车重量划分的商店币种价格：XS 最高 1 kg，S 最高 2 kg，M 最高 3 kg，L 最高 5 kg，XL 超过 5 kg。尺寸价格留空或为 0 时使用 Price 列；Price 列留空则表示该尺寸没有固定运费。点击 Add country 添加一行，点击叉号删除一行。* Default 行适用于所有没有专属行的国家。没有专属行的国家（且不存在 * 行时）没有固定运费，因此不会显示该方式。
Fixed price applies: Per order 只收取一次价格。Per item (price × quantity) 则按购物车中的商品数量相乘。Cargoson 实时价格始终按每次发货计算。
Conditions
Minimum weight (kg): 购物车重量低于此值时隐藏该方式。0 表示不设限制。
Maximum weight (kg): 购物车重量高于此值时隐藏该方式。默认：25。0 表示不设限制。
Minimum order amount: 仅当购物车小计（折扣后、税前）不低于此金额时才显示该方式。留空则始终显示。
Excluded shipping classes: 如果购物车中包含任一 WooCommerce 配送类别的商品，则隐藏该方式。
Free shipping: 当达到下方的订单金额时，开启免费配送。
Free shipping from: 购物车小计（折扣后、税前）达到此金额即免运费。仅在 Free shipping 开启时使用。
Tax status: Taxable 会根据您的 WooCommerce 税务设置添加配送税费，None 则不添加。Cargoson 中的承运商价格通常为不含增值税的净价。如果您的价格已含税，请选择 None。
Availability without shipping zones
Ignore shipping zones: 即使未将 Cargoson 添加到配送区域，也为下方指定的国家提供该方式。
Countries: 该模式适用的目的国家。留空则使用您配送的所有国家。此字段仅在 Ignore shipping zones 开启时使用。
Advanced
Debug log: 在 WooCommerce > Status > Logs 中记录每次运费计算，来源为 vfd_cargoson。即使此选项关闭，API 错误也始终会被记录。API 密钥和顾客邮政编码绝不会被记录。
Remove data on uninstall: 开启后，删除插件会移除所有 Cargoson 设置、区域方式和缓存价格。停用插件则不会删除任何内容。
结账时的工作流程
当顾客输入配送地址时，WooCommerce 会向插件请求运费。插件会先检查条件：配送国家、购物车重量、最低订单金额和排除的配送类别。如果适用免运费，顾客将获得免费运费，且不会向 Cargoson 发送请求。
在固定价格模式下，价格取自表格。在实时价格模式下，插件会向 Cargoson 发送取件日期、发货国家和邮政编码、收货国家和邮政编码，以及一个包含包裹类型代码和购物车总重量（至少 0.1 kg）的包裹。商品重量会从您的商店单位换算为千克。只有顾客输入邮政编码后才会请求实时价格。Cargoson 返回您承运商的价格；插件选择最便宜的一个（如果已设置指定承运商，则只从该承运商中选择），并在需要时换算为商店币种。
每个响应缓存 1 小时，因此相同的购物车不会触发新的请求。失败的请求缓存 10 分钟，因此结账页面在每次刷新时都不必等待 Cargoson。API 超时时间为 10 秒。如果 Cargoson 返回错误、没有该线路的价格，或返回的价格币种不同且没有换算汇率，顾客不会看到任何错误。该方式会被隐藏；在备用模式下，则使用固定价格。
该方式适用于经典结账以及购物车和结账区块。它兼容 WooCommerce 高性能订单存储（HPOS）。
插件仅计算运费。它不会在 Cargoson 中创建发货单或预订，不打印面单，也不跟踪包裹；顾客也无法选择自提柜或取货点。购物车将以总重量作为一个包裹进行报价；包裹尺寸不会发送。只显示最低价格，而不是承运商列表。
订单
使用实时价格时，订单的配送行会保存报价的 Carrier、Service 和 Cargoson service ID。它们显示在订单编辑页面，让您知道应在 Cargoson 中预订什么。请在 Cargoson 中或通过其自有集成预订发货。
许可证密钥
插件需要使用从 vibefox.net 获取的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Shipping > VibeFox Cargoson 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期截止日期和您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 从本站点移除密钥。Manage licenses and domains in your account 链接可打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。
没有有效密钥时，Cargoson 不会在结账时显示给顾客。已登录的商店管理人员仍可看到它，并标有 (unlicensed — visible to admins only)，方便您在购买密钥前完成设置和测试。插件页面和 WooCommerce 页面上会出现提醒。现有订单不受影响。
许可证到期后，插件仍可继续运行，但更新和支持需要续期。系统会在后台自动重新检查状态。
故障排除
Cargoson 未在结账时显示：请检查许可证是否有效、Enable/Disable 是否开启，以及该方式是否已添加到顾客所在国家的区域中（或开启了 Ignore shipping zones 且该国家被允许）。检查重量限制、Minimum order amount 和 Excluded shipping classes。在固定价格模式下，请确认该国家或 * Default 对购物车尺寸有价格。
实时价格未显示：打开 WooCommerce > Status > Logs，来源为 vfd_cargoson。API 错误始终会被记录；开启 Debug log 可查看每次计算。常见原因：尚未输入配送邮政编码、缺少发货邮政编码、API 密钥被拒绝（密钥错误或已过期，或您的 Cargoson 套餐没有 API 访问权限）、该线路或重量没有承运商，或价格为其他币种。使用 Cargoson live prices, fixed prices if the API fails 时，顾客在您解决问题期间仍会获得固定价格。
Cargoson 拒绝包裹类型：请使用您的 Cargoson 账户在 Package type code 中所用的包裹代码。原因会显示在日志中。
其他币种的价格被拒绝：将 Price currency 设置为您 Cargoson 价格的币种，并填写 Currency conversion rate。
更改后费率看起来过时：保存设置页面。这会清除缓存的 Cargoson 价格。
许可证区块显示错误：请按区块中的提示操作。例如，如果该密钥已在其他域名上使用，请在您的 vibefox.net 账户中释放名额，然后点击 Check now。如果站点地址已更改，请点击 Check now 为新域名激活密钥。如果无法连接许可证服务器，插件将使用最后已知的状态继续运行。
卸载
停用插件会保留所有数据。要删除插件，请先停用，然后在 Plugins 页面中删除。本插件的许可证密钥和许可证状态始终会被删除。只有开启了 Remove data on uninstall，设置、区域方式和缓存价格才会被删除；否则它们会保留，以便日后重新安装。现有订单会保留其配送行。
Cargoson 是其各自所有者的商标。本插件与 Cargoson 无关联，也未获得 Cargoson 的认可。