VibeFox Cargoson for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

PHP：8.0 或更高版本。模块不会安装在更旧的 PHP 版本上。

Cargoson 账户（仅用于实时价格）：实时价格使用 Cargoson 运费价格 API。运费价格查询需要具备 API 访问权限的 Cargoson 订阅（撰写本文时为 Advanced 套餐或更高）。API 密钥在您的 Cargoson 账户中签发；如果您的套餐不显示 API 设置，请联系 Cargoson 支持。价格来自与该账户相连的承运商和价格表。如果您只使用固定价格，则不需要 Cargoson 账户。

VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。

安装

1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。

2. 上传完成后，点击 Configure；或之后在模块列表中找到 VibeFox Cargoson，然后点击 Configure。

3. 在 Configure 页面顶部的许可证区块中，将 VibeFox 许可证密钥输入 License key 字段，然后点击 Activate（见“许可证密钥”）。

4. 选择运费的计算方式，并填写相应的部分：固定价格，以及（如使用实时价格）API 密钥和揽收邮政编码（见配置）。点击 Save。

安装时，模块会创建 Cargoson 承运商，配送时间文本为 Delivery by the cheapest Cargoson carrier。该承运商会分配给所有区域和所有顾客群组。您可以在 Shipping > Carriers 中修改区域、顾客群组、配送时间、Logo 和尺寸限制。请不要在那里设置价格：价格始终来自模块。

配置

所有设置都在模块页面中：Modules > Module Manager > VibeFox Cargoson > Configure。它们适用于承运商的每个区域。每个部分都有自己的 Save 按钮，点击后会保存整个页面。保存后，您会看到 Settings saved. Cached Cargoson prices were cleared. 小数可以用点或逗号输入。如果数字字段包含文本或负数，Currency conversion rate 为 0，Minimum weight 大于 Maximum weight，Method title 超过 64 个字符，Price currency 不是 3 位货币代码，或价格表的某一行包含无效的国家代码或价格，则不会保存任何内容，页面会显示错误。如果模块无法识别店铺的重量单位，保存后会出现警告，说明商品重量按千克计算；请在 International > Localization（Local units）中设置单位。

General

Enable Cargoson：开启或关闭承运商。这与 Shipping > Carriers 中的承运商状态是同一个开关。

Method title：在购物车和结账页面显示的承运商名称。默认：Cargoson。必填。它也是 Shipping > Carriers 中的承运商名称。

Shipping cost：价格的计算方式。

缺少实时价格的原因会写入模块日志，绝不会显示给顾客。

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：您发货的国家。默认是您店铺所在的国家。

Collection postcode：您发货的邮政编码。Cargoson 要求填写。如果留空且揽收国家是店铺所在国家，则使用 Shop Parameters > Contact > Stores 中的店铺邮政编码。

发送给 Cargoson 的揽收日期为店铺时区的当天；如果是周末，则为下一个周一。

固定价格（当 Shipping cost 为 Fixed prices 时使用，也作为实时价格的备用价格）

Price per country and size：一个表格，包含 Country 列（2 位代码）、Price 列，以及按购物车重量划分的价格（以店铺默认货币计，不含税）：XS 最高 1 kg，S 最高 2 kg，M 最高 3 kg，L 最高 5 kg，XL 超过 5 kg。尺寸价格为空或 0 时，使用 Price 列；Price 为空则表示该尺寸没有固定费率。点击 Add country 添加一行，点击垃圾桶图标删除一行。对于没有自己单独一行的所有国家，请使用 * 作为国家代码。没有对应行的国家（当没有 * 行时）不会获得固定费率，因此会隐藏该承运商。价格必须为 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：承运商的税务规则，或 No tax。Cargoson 中的承运商价格通常为不含税价（不含增值税）。如果您的价格已含税，请选择 No tax。

无配送区域时的可用性

通常，承运商会在 Shipping > Carriers 中为其分配的区域内提供。

Ignore shipping zones：无论承运商分配了哪些区域，都为下方的国家提供 Cargoson。开启并保存后，承运商会被分配到所有区域；之后创建的区域也会被分配。关闭并保存后，承运商会恢复其之前的区域。

Countries：该模式的目标国家。留空则使用您配送的所有国家（已启用的国家）。此字段仅在 Ignore shipping zones 开启时使用。

高级

Debug log：将每次运费计算记录到模块文件夹中的 logs/vfd_cgs_debug.log.php。该文件无法通过网页打开。即使此选项关闭，API 错误和被拒绝的价格也始终会被记录。API 密钥和顾客邮政编码绝不会被记录。

Log：显示日志的大小和最新条目。点击 Clear log 可清空。

Remove data on uninstall：开启后，卸载模块会删除 Cargoson 设置、承运商、缓存的价格、订单报价和日志。关闭后，所有内容都会保留，以便重新安装。

结账时的工作方式

在配送步骤，PrestaShop 会向模块请求 Cargoson 价格。只有实体商品才计算在内：虚拟商品不增加重量，也不计入订单金额。商品重量会从店铺单位换算为千克。模块首先检查条件：配送国家、购物车重量和最低订单金额。如果适用免运费，价格为 0，并且不会向 Cargoson 发送请求。

在固定价格模式下，价格取自表格。在实时价格模式下，模块会向 Cargoson 发送揽收日期、揽收国家和邮政编码、配送国家和邮政编码，以及一个包裹（包含包裹类型代码和购物车总重量，至少 0.1 kg）。只有配送地址有邮政编码时才会请求实时价格。Cargoson 会返回您承运商的价格；模块会选择最便宜的一个（如已选择某承运商，则只在该承运商中选择），并在需要时换算为店铺默认货币。价格以店铺默认货币计算，然后以顾客购物车的币种显示。

每次响应都会缓存 1 小时，因此同一购物车不会触发新的请求。失败的请求会缓存 10 分钟，这样结账时每次刷新都无需等待 Cargoson。API 超时时间为 10 秒。如果 Cargoson 返回错误、没有该路线的价格，或返回的价格币种没有换算汇率，顾客不会看到任何错误。承运商会被隐藏；在备用模式下则使用固定价格。

如果您在承运商已有订单后，在 Shipping > Carriers 中编辑该承运商，PrestaShop 会将其保存为新的承运商版本。模块会自动跟随新版本。

模块只计算费率。它不会在 Cargoson 中创建发货或预订，不打印面单，也不跟踪包裹，顾客也无法选择自提柜或取货点。购物车会按总重量报价为一个包裹；不会发送包裹尺寸。只显示最低价格，而不是承运商列表。

订单

Cargoson 订单的页面会显示一个 Cargoson shipping 区块，其中包含结账时计算的费率：

Carrier、Service 和 Cargoson service ID：报价的 Cargoson 承运商和服务，在使用实时价格时显示。

Price source：Cargoson live price、Fixed price 或 Free shipping threshold。

Calculated price (excl. tax)：以店铺默认货币表示的价格。

报价在下单时保存，之后不会更改。请在 Cargoson 中或通过其自有集成预订发货。

许可证密钥

模块需要使用从 vibefox.net 获取的 VibeFox 许可证密钥。许可证区块 License — VibeFox Cargoson 是 Modules > Module Manager > VibeFox Cargoson > Configure 页面中的第一个区块，位于设置上方。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），并提供以下按钮：Check now 用于重新检查状态，Change key 用于输入其他密钥，Remove key 用于从此店铺中移除密钥。它们下方是 Product: presta-shipping-cargoson 一行，以及打开您 vibefox.net 账户的链接 Manage licenses and domains in your account。只有拥有该模块配置权限的员工才能更改密钥。该区块的文字跟随后台语言显示（包含英语和俄语）。

如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或 License expired on 加上日期。店铺地址更改后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，模块将继续使用最后已知的状态运行。

一个密钥只能用于一个域名：即主店铺的域名，多店铺设置中也是如此。从店铺中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。

没有有效密钥时，Cargoson 承运商不会在结账时显示给顾客，也不会计算任何运费。PrestaShop 前台无法得知您已登录后台，因此承运商对您也会隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 的 Alerts 选项卡中会出现提醒。现有订单不受影响。

许可证到期后，模块仍会继续运行，但更新和支持需要续费。在您使用后台期间，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。

故障排除

Cargoson 没有出现在结账页面：请检查许可证是否有效，以及 Enable Cargoson 是否开启。在 Shipping > Carriers 中，检查承运商是否覆盖顾客所在国家的区域和顾客的群组（或 Ignore shipping zones 已开启且该国家在 Countries 中）。检查重量限制和 Minimum order amount。在固定价格模式下，检查该国家或 * 是否有该购物车尺寸的价格。商品也可能在商品页面中被限制为特定承运商。

实时价格没有出现：请查看模块页面上的 Log 字段。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 价格已含增值税。请将 Tax 设置为 No tax。

更改后费率看起来过时：在模块页面点击 Save。这会清除缓存的 Cargoson 价格。

页面提示未找到 Cargoson 承运商：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块以重新创建。

卸载

进入 Modules > Module Manager，打开 VibeFox Cargoson 旁边的菜单，选择 Uninstall。许可证密钥和许可证状态总会被删除。缓存的价格始终会被删除。如果 Remove data on uninstall 已开启，承运商会被删除（订单保留其历史记录），同时删除设置、订单报价和日志。如果已关闭，承运商只会被停用，设置和已下订单的报价会被保留，只删除没有订单的购物车报价。重新安装模块时，已保存的承运商会恢复其之前的状态，因此 Reset 不会重新启用您曾停用的承运商。

Cargoson 是其各自所有者的商标。本模块与 Cargoson 无关联，也未获得 Cargoson 的认可。