VibeFox Correios for PrestaShop — 帮助

要求

PrestaShop：8.0 至 9.x。

PHP：8.0 或更高版本。模块拒绝安装在较旧的 PHP 版本上。

Correios 合同（仅用于实时运费）：实时运费使用 Correios Web Services（CWS）价格 API，需要带有 posting card 的 Correios 合同凭据。您需要三项信息：您的 Meu Correios 用户（通常是合同的 CNPJ 或 CPF）、API 访问代码和 posting card 号码。请在 Correios Web Services 门户（cws.correios.com.br；测试环境为 cwshom.correios.com.br）中生成访问代码。您还需要发货所在地的 CEP。没有凭据时，模块仅使用固定运费。

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

安装

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

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

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

4. 输入 Correios API 用户、访问代码、posting card 号码、发货 CEP 和服务。如果商店默认货币不是 BRL，请输入 BRL 汇率。填写其他国家的固定运费以及备用运费（参见配置）并点击 Save。

安装时，模块会创建 Correios 承运商，配送时间文字为 Correios (Brazilian Post)。该承运商分配给所有区域和所有客户组。您可以在 Shipping > Carriers 中更改区域、客户组、配送时间、徽标和尺寸限制。请不要在那里设置价格：价格始终来自模块。

配置

所有设置都在模块页面中：Modules > Module Manager > VibeFox Correios > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。每次保存还会清除缓存的 Correios 价格和 API 令牌。数字可以用小数点或逗号输入。

当实时运费或承运商无法工作时，页面会显示警告：三项凭据只填了部分、缺少发货 CEP、其他货币的商店缺少 BRL 汇率，或者既没有凭据也没有固定运费。每条警告都会说明在此期间是使用固定运费还是隐藏承运商。如果商店的重量或尺寸单位不被模块识别（此时按 kg 或 cm 读取），也会出现警告；请在 International > Localization（Local units）中设置 kg、g、lb 或 oz，以及 cm、mm、m 或 in。

如果方法标题为空或无效（最多 64 个字符），Country prices 中的数字字段或价格不是 0 或更大的数字，BRL 汇率为 0，Min cart weight 大于 Max cart weight，发货 CEP 不是 8 位数字，或其他服务代码超过 5 位，保存将被拒绝并显示提示信息。在您更正该值之前，不会保存任何内容。

常规

Enable Correios:一次性在所有区域开启或关闭承运商。这与 Shipping > Carriers 中的承运商状态是同一个开关。

Method title:在购物车和结账时显示的承运商名称。默认：Correios。必填。

Tax:加在运费上的税务规则，或 No tax（默认）。

Correios API（巴西的实时运费）

对于巴西的地址，价格来自 Correios 价格 API。如果 API 未返回价格（API 故障、CEP 不在服务范围内、包裹过大），则使用 Country prices 中的固定运费；如果没有固定运费，则隐藏承运商。错误详情会记录到日志中，绝不会显示给顾客。

API user:您的 Meu Correios 门户登录名，通常是合同的 CNPJ 或 CPF。

Access code:在 Correios Web Services 门户中生成的 API 访问代码（código de acesso）。它不是门户密码。保存后，该字段保持为空并显示 Saved — leave empty to keep it (empty the API user as well to remove it)。只有需要更改时才输入新值。要删除已保存的代码，请同时清空 API user 和 Access code 并保存。

Posting card:您合同的 posting card（cartão de postagem）号码：10 位数字，通常以两个零开头，例如 0012345678。较短的号码会在前面补零。您可以在 Correios 网站的 Correios Fácil 页面上核对该号码。

Homologation:使用 Correios 的测试（homologation）环境：请求将发送到 apihom.correios.com.br，并使用测试访问代码。在正式商店上请关闭。

Origin CEP:包裹发出的 CEP（8 位数字），例如 01001-000。

Service:结账时计价的 Correios 服务。零售代码：PAC（04510，默认）、SEDEX（04014）、SEDEX 12（04782）、SEDEX 10（04790）、SEDEX Hoje（04804）。合同代码：PAC（03298）、SEDEX（03220）、SEDEX 12（03140）、SEDEX 10（03158）、SEDEX Hoje（03204）、Correios Mini Envios（04227）。合同代码需要包含该服务的合同的 posting card。

Other service code:可选，您合同中不在列表内的 5 位服务代码，例如 03085。较短的代码会在前面补零。填写后，将代替 Service 使用。

Package format:发送给 Correios 的物件类型。

Default product weight:单位为 kg，为每个没有重量的商品发送给 Correios。默认：0.3。商品的重量和尺寸会从商店单位换算（字段说明中会显示），购物车按一个包裹计价。

BRL → store currency rate:字段名称会显示您商店的默认货币，例如 BRL → EUR rate。Correios 价格以 BRL 计价。如果您的默认货币不是 BRL，请输入 1 个 BRL 等于多少单位您的货币，例如 0.17。没有该汇率，将不使用实时价格。汇率必须大于 0。如果您的默认货币是 BRL，请留空。

固定运费（用于巴西以外的国家、没有 API 凭据时，以及 API 未返回价格时的备用运费）

Country prices:一个国家表格，包含 Base 价格，以及按购物车重量划分的价格，使用商店默认货币，不含税：XS 最多 1 kg，S 1–2 kg，M 2–3 kg，L 3–5 kg，XL 超过 5 kg。尺寸价格为空或为零时，使用 Base 价格。点击 Add country 添加一行，点击叉号删除一行。* Default (all other countries) 行为所有没有单独行的国家设置价格。没有单独行（也不是 *）的国家不会获得固定运费。没有任何价格的行不会被保存。非数字或负数的价格会导致保存出错并停止。基础价格为 0 表示该国家免运费。

Fixed price per:Order 仅收取一次价格。Item (price × quantity) 则乘以购物车中的商品数量。这仅适用于固定运费。实时运费始终按整个包裹计算。

条件

Min cart weight:单位为 kg，购物车重量低于此值时隐藏承运商。0 表示无限制。不能大于 Max cart weight。

Max cart weight:单位为 kg，购物车重量高于此值时隐藏承运商。默认：30。0 表示无限制，空字段表示 30 kg。Correios PAC 和 SEDEX 包裹的重量最高可达 30 kg。

Minimum order amount:只有当购物车小计（需要配送的商品，扣除折扣后，税前）达到此金额时才显示承运商。留空则始终显示。

Free shipping:开启下方金额起的免费配送。

Free shipping from:购物车小计（扣除折扣后，税前）达到此金额起免运费。在这种情况下不会发出 API 请求。

无配送区域时的可用性

通常，承运商会显示在 Shipping > Carriers 中分配给它的区域内。

Ignore shipping zones:无论匹配哪个区域，都为下方的国家提供承运商。保存时，承运商会添加到所有区域。关闭该选项会移除它添加的区域。选项开启期间新建的区域会自动添加。

Countries:该模式的目的地国家。留空则使用商店所有启用的国家。仅当 Ignore shipping zones 开启时才使用此字段。

高级

Debug log:将运费计算写入模块文件夹中的 logs/vfd_crr_debug.log.php。该文件无法通过网页打开。即使此选项关闭，API 错误也始终会被记录。API 用户、访问代码、posting card、令牌和顾客 CEP 不会被记录。

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

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

结账时的工作原理

在配送步骤，PrestaShop 会向模块请求 Correios 运费。只有实物商品计入：虚拟商品不增加重量，也不计入订单金额。模块首先检查条件：允许的国家（配合 Ignore shipping zones）、购物车重量和最低订单金额。如果适用免运费，价格为 0，并且不会向 Correios 发送请求。

对于已设置凭据的巴西地址，模块首先为您的 posting card 获取 API 令牌。该令牌还会提供合同号和地区办事处编号，因此价格就是您合同的价格。然后，模块会根据发货和收货 CEP、以克为单位的包裹重量以及以 cm 为单位的包裹尺寸，请求所选服务的价格。仅当收货 CEP 为 8 位数字时才会请求价格。当所有商品都有尺寸时，包裹尺寸会根据这些尺寸估算；否则发送 Correios 最小尺寸。超过 30 kg 的包裹不会发送到 API。BRL 价格按您的汇率换算。价格以您商店的默认货币计算，然后显示为顾客购物车的货币。

每个价格按包裹缓存 1 小时。失败的请求缓存 10 分钟，因此 API 故障不会拖慢每次结账更新。令牌会缓存到快过期时，并自动续期；如果 Correios 拒绝该令牌，将申请新令牌并重复一次价格请求。API 超时时间为 12 秒。

如果 API 未返回价格，则使用固定运费；如果没有固定运费，则隐藏承运商。顾客永远看不到 API 错误详情；这些信息会进入调试日志。

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

模块只计算运费。它不获取 Correios 国际运费（Exporta Fácil、Packet）、配送时间估算、面单、预先登记、报关单或跟踪信息。顾客无法选择 Correios 网点或智能柜。不会添加额外服务（申报价值、本人签收、回执通知）。每家商店只显示一种 Correios 服务，货币汇率也不会自动更新。

订单

使用 Correios 承运商下单时，模块会保存其运费的计算方式。后台订单页面随后会显示 Correios 区块，其中包含 Correios service（实时运费时，例如 PAC — contract (03298)）和 Price source：Live price (Correios API)、Fixed price 或 Free shipping。

许可证密钥

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

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

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

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

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

故障排除

结账时没有显示 Correios：请检查许可证是否有效，且 Enable Correios 已开启。在 Shipping > Carriers 中，检查承运商是否覆盖了顾客所在国家的区域和顾客所属的客户组（或 Ignore shipping zones 已开启且该国家被允许）。检查重量限制和 Minimum order amount。没有实时价格时，必须存在该国家或 * 的固定运费。产品页面中还可以将商品限制为特定承运商。

承运商显示固定运费而不是 Correios 运费：请查看模块页面上的 Log 字段。Correios 错误会记录在那里：访问代码错误、服务不在您的合同中、CEP 不在服务范围内、包裹超过 30 kg 或超出尺寸限制。还要检查发货 CEP 是否已设置、顾客的 CEP 是否为 8 位数字，以及如果默认货币不是 BRL，BRL 汇率是否已设置。开启 Debug log 可查看每一次计算。

令牌请求失败：请检查 API 用户、访问代码、posting card 和环境。测试（homologation）访问代码只有在 Homologation 开启时才有效，正式访问代码只有在其关闭时才有效。

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

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

保存时提示没有权限：您的员工资料可以查看模块，但无法配置。保存设置和清空日志需要模块的配置权限。

卸载

前往 Modules > Module Manager，打开 VibeFox Correios 旁边的菜单，然后选择 Uninstall。许可证密钥、许可证状态以及缓存的价格和令牌始终会被删除。如果 Remove data on uninstall 已开启，承运商会被删除（订单保留其历史记录），设置、已保存的订单服务和日志也会被删除。如果已关闭，承运商仅会被停用，所有设置都会保留。再次安装模块会以之前的状态恢复承运商。

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