VibeFox Correios for OpenCart — 帮助

系统要求

OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。

PHP：8.0 或更高版本。

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

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

安装

下载文件是一个 zip 压缩包，内含适用于两个 OpenCart 版本的安装包。请解压到您的计算机上。压缩包包含 README.txt、OpenCart 3 安装包 vfd_correios-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 vfd_correios.ocmod.zip。请只安装与您的 OpenCart 版本对应的安装包。两个版本的许可证密钥相同。

OpenCart 3

1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_correios-oc3-(version).ocmod.zip。本扩展不添加任何 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用 Installer，而是将本安装包中 upload 文件夹的内容复制到店铺的根目录。

2. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Correios，点击 Install（绿色的 + 按钮）。

3. 点击 Edit（铅笔按钮）打开设置页面。

4. 将您的 VibeFox 许可证密钥粘贴到 Edit 页面顶部许可证区块中的 License key 字段，然后点击 Activate（参见许可证密钥）。

5. 填写 Correios API 用户、访问代码、邮寄卡号码、始发地 CEP 和服务。如果店铺的默认货币不是 BRL，请输入 BRL 汇率。为其他国家和备用运费填写固定运费（参见 Configuration），开启 Enable Correios，然后点击 Save。

OpenCart 4

1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_correios.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包无法使用。

2. 安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色的 + 按钮）。

3. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Correios，点击 Install（绿色的 + 按钮），然后点击 Edit（铅笔按钮）。

4. 请按照 OpenCart 3 步骤 4 和 5 的方法输入许可证密钥和设置。两个版本的设置页面及其字段相同。

安装后，在您开启 Enable Correios 并保存之前，该配送方式处于关闭状态。如果卸载后重新安装扩展，之前保留的 Correios 设置将再次生效。

Configuration

所有设置都在扩展页面中：Extensions > Extensions > Shipping > VibeFox Correios > Edit。各分区列在左侧。页面底部的一个 Save 按钮可在不重新加载页面的情况下保存整个页面。每次保存还会清除缓存的 Correios 运费和 API 令牌。数字可以使用小数点或逗号输入。只有拥有本扩展修改权限的管理员用户才能保存设置。

当实时运费或该方式无法正常工作时，页面会显示警告：三项凭据只填了部分，缺少始发地 CEP，使用其他货币的店铺缺少 BRL 汇率，或既没有凭据也没有固定运费。每条警告都会说明此时使用的是固定运费还是该方式已被隐藏。如果店铺没有单位为 kg 的重量类别，或没有单位为 cm 的长度类别，也会出现警告；此时商品单位将按其类别的单位名称进行换算（无法识别的单位按 kg 或 cm 计算）。请检查 System > Localisation > Weight Classes 和 Length Classes。

如果配送方式名称为空或无效（最多 64 个字符，且不得包含 < > ; = # { }），Country prices 中的数字字段或运费不是 0 或更大的数字，BRL 汇率为 0，Min cart weight 大于 Max cart weight，始发地 CEP 不是 8 位数字，其他服务代码超过 5 位，或 Sort order 不是整数，保存将被拒绝并显示提示信息。在您更正该值之前，不会保存任何内容。

常规

这些设置适用于所有地理区域。您可以在 Conditions 中将该方式限制在某个地理区域，或使用 Ignore shipping zones 将其限制在国家列表中。

Enable Correios：在结账时显示或隐藏 Correios。默认：关闭。

Method title：顾客在购物车和结账时看到的配送方式名称。默认：Correios。必填。

Sort order：Correios 在结账时配送方式列表中的位置。整数。

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 并保存。

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）。合同代码需要包含该服务的合同的邮寄卡。

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 添加一行，点击 × 按钮删除一行。* All other countries 行为所有没有单独一行的国家设置运费。没有对应行（且未被 * 覆盖）的国家没有固定运费。每行至少需要一个运费。基础运费为 0 表示该国家免运费。

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

Conditions

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 发送请求。

Tax class：添加到运费上的税务类别，或 No tax（默认）。

Geo zone：仅向此地理区域内的地址提供 Correios。All zones（默认）表示不限制。地理区域在 System > Localisation > Geo Zones 中管理。与 Ignore shipping zones 一起使用时不生效。

在不使用配送区域的情况下的可用性

通常，该方式会在 Conditions 中选定的地理区域内提供（若未选择，则在所有区域提供）。

Ignore shipping zones：无论匹配哪个地理区域，都为下列国家提供该方式。此时不会检查 Conditions 中的 Geo zone。

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

高级

Debug log：将运费计算写入 storage/logs/vfd_crr_debug.log.php（OpenCart 4 上为 system/storage/logs/vfd_crr_debug.log.php）。该文件无法通过网页读取。即使此选项关闭，API 错误也始终会被记录。API 用户、访问代码、邮寄卡、令牌和顾客 CEP 不会被记录。文件达到 5 MB 时，会被移至 vfd_crr_debug.old.log.php，并开始新的日志。

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

Remove data on uninstall：开启后，卸载扩展会删除 Correios 设置和日志。关闭时（默认），这些数据会保留，以便重新安装。随订单保存的 Correios 服务始终会保留。

导入 / 导出

Export：点击 Download JSON 可将设置保存为 JSON 文件。访问代码不会被导出。

Import：粘贴之前导出的 JSON，然后点击 Import 以恢复设置，例如在另一家店铺中使用。这些值会像正常保存一样进行检查。已保存的访问代码会保留。

结账时的工作方式

当 OpenCart 显示配送方式时，会向扩展请求 Correios 运费。如果设置了 Geo zone（且 Ignore shipping zones 未开启），而地址位于该区域之外，则不提供 Correios。只有 Requires Shipping 设为 Yes 的商品才会计入：其他商品不增加重量，也不计入订单金额。随后扩展会检查条件：允许的国家（配合 Ignore shipping zones）、购物车重量和最低订单金额。订单金额是需要配送的商品在扣除优惠券折扣后、税前的价格。如果适用免运费，则运费为 0，且不会向 Correios 发送请求。

对于设置了凭据的巴西地址，扩展首先会为您的邮寄卡获取 API 令牌。该令牌还提供合同号和地区办事处号，因此运费为您合同的价格。然后，扩展根据始发地和目的地 CEP、以克为单位的包裹重量以及以 cm 为单位的包裹尺寸，请求所选服务的运费。仅当目的地 CEP 为 8 位数字时才会请求运费。当所有商品都有尺寸时，包裹尺寸会根据这些尺寸估算；否则发送 Correios 最小尺寸。超过 30 kg 的包裹不会发送至 API。BRL 运费会按您的汇率换算。运费按店铺默认货币计算，按该货币的小数位数取整，并以顾客的货币显示，同时加上所选 Tax class 的税额。

每个运费缓存 1 小时。失败的请求缓存 10 分钟，以免 API 故障导致每次结账更新都变慢。令牌会缓存到快过期时（最长不超过 OpenCart 缓存的有效期，默认 1 小时），并自动更新；如果 Correios 拒绝该令牌，则会请求新令牌，并重试一次运费请求。API 超时时间为 12 秒。

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

该扩展只计算费率。它不获取 Correios 国际运费（Exporta Fácil、Packet）、配送时效预估、运单、预先登记、报关单或追踪信息。顾客无法选择 Correios 网点或快递柜。不会添加附加服务（声明价值、亲收、回执通知）。每个店铺仅显示一种 Correios 服务，且货币汇率不会自动更新。

在 OpenCart 4 上，顾客在结账页面的配送方式区块中点击 Choose，并在 Shipping method options 窗口中选择 Correios。该方式的工作方式与 OpenCart 3 相同。

订单

使用 Correios 下单时，扩展会保存其运费的计算方式。随后 Sales > Orders 中的订单页面会显示 Correios 区块，其中包含 Correios service（例如 PAC — contract (03298)）和 Price：Live price (Correios API)、Fixed price 或 Free shipping。该区块仅在管理后台显示，不会出现在顾客邮件中，并且即使扩展已禁用，仍会保持可见。

在 OpenCart 4 上，结账时会保留一个订单，并在顾客再次确认时更新该订单。订单的 Correios 数据会随之更新；如果顾客改选其他配送方式，则该订单将不再显示 Correios 区块。

许可证密钥

本扩展需要一个来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox Correios 许可证区块是 Extensions > Extensions > Shipping > VibeFox Correios > Edit 页面中位于设置上方的第一个区块。将密钥粘贴到 License key 中并点击 Activate。之后，该区块会以隐藏形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及按钮 Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺移除密钥）。其下方是 Product: opencart-shipping-correios 一行，以及 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 账户中释放该名额。

没有有效的密钥时，结账时不会向顾客显示 Correios，也不会计算任何运费。在同一浏览器中登录管理后台的管理员用户，仍会在店铺中看到该配送方式，并标记为 (unlicensed — visible to admins only)，以便您在购买密钥之前设置和测试扩展。在 OpenCart 4 上此预览不可用：店铺看不到管理后台的登录状态，因此没有有效密钥时，该方式对所有人都隐藏。打开一次 Edit 页面后，管理后台的 Dashboard 上会出现提醒。点击 × 可将其关闭，并隐藏 7 天。现有订单不受影响。

许可证到期后，扩展仍会继续运行，但更新和支持需要续费。当您打开管理后台的 Dashboard 或 Edit 页面时，会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展时总会删除许可证密钥和许可证状态。

故障排除

Correios 未出现在结账页面：请检查许可证是否有效，以及 Enable Correios 是否已开启。检查 Geo zone（或 Ignore shipping zones 和 Countries）、重量限制和 Minimum order amount。如果没有实时运费，则必须为该国家或 * 设置固定运费。检查商品的 Requires Shipping 是否设为 Yes。

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

令牌请求失败：请检查 API 用户、访问代码、邮寄卡和运行环境。测试访问代码只有在 Homologation 开启时才有效，正式访问代码只有在其关闭时才有效。

修改后运费显示过时：在扩展页面点击 Save。这会清除缓存的运费和 API 令牌。

页面显示 "Warning: You do not have permission to modify VibeFox Correios!"：您的管理员用户组可能只有查看设置的权限。请在 System > Users > User Groups 中，为该组授予 extension/shipping/vfd_correios（OpenCart 3）或 extension/vfd_correios/shipping/vfd_correios（OpenCart 4）的修改权限。

面向开发者：可通过设置 vfd_crr_api_url（用于测试）替换 Correios API 地址；设置页面上没有对应字段。

卸载

进入 Extensions > Extensions，选择 Shipping 类型，然后点击 VibeFox Correios 旁边的 Uninstall（红色 − 按钮）。本扩展的许可证密钥和许可证状态总会被删除。OpenCart 总会重置 Enable Correios、Sort order、Tax class 和 Geo zone。缓存的运费和令牌总会被删除。如果 Remove data on uninstall 已开启，则 Correios 设置和调试日志也会被删除。如果关闭，其他设置会保留，并在您重新安装扩展时再次使用。随订单保存的 Correios 服务始终保留，现有订单保留其配送方式和运费。

在 OpenCart 4 上，如需同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox Correios 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）删除已上传的安装包。

Correios 是其各自所有者的商标。本扩展与 Correios 无关联，也未获得 Correios 的认可或背书。