VibeFox Correios for WooCommerce — 帮助
要求
WordPress：5.8 或更高版本。
WooCommerce：5.0 或更高版本，已安装并启用。未安装 WooCommerce 时，插件无法启用。
PHP：8.0 或更高版本。
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. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 vfd_correios 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置：WooCommerce > Settings > Shipping > VibeFox Correios，或在插件页面点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 输入 Correios API 用户、访问代码、posting card 号码、发货 CEP 和服务。如果您的商店货币不是 BRL，请输入 BRL 汇率。为其他国家以及作为备用运费填写固定运费（见配置）。
6. 在 WooCommerce > Settings > Shipping > Shipping zones 中将 VibeFox Correios 添加到配送区域，或开启 Ignore shipping zones 并选择国家。
配置
所有设置都在一个页面上：WooCommerce > Settings > Shipping > VibeFox Correios。它们适用于所有配送区域。将该方式添加到某个区域时，区域窗口只有一个字段：
Title (zone)：此区域向顾客显示的名称。留空则使用全局的 Method title。
设置页面会在实时运费或该方式无法工作时显示警告：三项凭据只填了部分、缺少发货 CEP、非 BRL 货币的商店缺少 BRL 汇率，或既没有凭据也没有固定运费。每次保存设置时，缓存的价格和 API 令牌都会被清除。数字可以用小数点或逗号输入。
常规
Enable/Disable：一次性在所有区域启用或禁用此方式。
Method title：在购物车和结账时显示的配送方式名称。默认：Correios。区域可以用自己的标题覆盖它。
Tax status：Taxable 会在运费上增加 WooCommerce 税费，None 则不增加。
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）。它不是门户密码。
Posting card：您合同的 posting card（cartão de postagem）号码：10 位数字，通常以两个零开头，例如 0012345678。位数较少的号码会在前面补零。您可以在 Correios 网站的 Correios Fácil 页面上查看该号码。
Homologation：使用 Correios 测试（homologation）环境和测试访问代码。在正式商店中请关闭。
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 的、没有重量的每件商品的重量。Default: 0.3。商品重量和尺寸会从商店单位换算，购物车按一个包裹计价。
BRL → store currency rate：字段名称会显示您的商店货币。Correios 价格以 BRL 计价。如果您的商店货币不是 BRL，请输入 1 BRL 等于多少单位的您的货币，例如 0.17。没有该汇率时，不会使用实时运费。如果您的商店货币是 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 (kg)：高于此购物车重量时隐藏该方式。默认：30。0 表示无限制。Correios PAC 和 SEDEX 包裹的重量最高可达 30 kg。
Minimum order amount：仅当购物车小计达到此金额时才显示该方式。留空则始终显示。
Excluded shipping classes：如果购物车中任何商品属于这些 WooCommerce 配送类别，则隐藏该方式。
Free shipping：开启后，达到下方金额即免运费。
Free shipping from：购物车小计达到此金额时运费免费。在这种情况下不会发出 API 请求。
没有配送区域时的可用性
Ignore shipping zones：无论匹配哪个区域，都为下方的国家提供该方式。
Countries：该模式下的目的地国家。留空则使用商店配送的所有国家。此字段仅在 Ignore shipping zones 开启时使用。
高级
Debug log：将运费计算记录在 WooCommerce > Status > Logs 中，来源为 vfd-correios。即使此选项关闭，API 错误也始终会被记录。API 用户、访问代码、posting card、令牌和顾客 CEP 均不会被记录。
Remove data on uninstall：开启后，删除插件会移除其设置、区域方式和缓存的价格。停用插件从不会删除任何内容。
结账时的工作方式
顾客输入配送地址时，WooCommerce 会向插件请求运费。插件首先检查条件：购物车重量、最低订单金额和排除的配送类别。如果适用免运费，顾客将获得免费运费，并且不会向 Correios 发出任何请求。
对于已设置凭据的巴西地址，插件首先为您的 posting card 获取 API 令牌。令牌还会提供合同和地区办事处编号，因此价格是您合同的价格。然后，插件会根据发货和收货 CEP、以克为单位的包裹重量以及以 cm 为单位的包裹尺寸，请求所选服务的价格。只有收货 CEP 为 8 位数字时才会请求价格。如果所有商品都有尺寸，包裹尺寸将根据这些尺寸估算；否则发送 Correios 最小尺寸。超过 30 kg 的包裹不会发送给 API。BRL 价格会按您的汇率换算。该服务会以 Correios service 的形式保存在订单的配送行中，并可在订单后台查看。
每个包裹的价格缓存 1 小时。失败的请求缓存 10 分钟，这样 API 故障就不会拖慢每次结账更新。令牌会缓存到快过期前，并自动续期；如果 Correios 拒绝该令牌，则会请求新令牌，并重复一次价格请求。API 超时时间为 12 秒。
如果 API 没有返回价格，则使用固定运费；如果没有固定运费，则隐藏该方式。顾客永远不会看到 API 错误详情，这些信息会进入 WooCommerce 日志。
该方式适用于经典结账以及购物车和结账区块。它兼容 WooCommerce High-Performance Order Storage（HPOS）。
插件只计算运费。它不获取 Correios 国际价格（Exporta Fácil、Packet）、送达时间估算、面单、预先登记、报关单或物流跟踪。顾客无法选择 Correios 网点或自提柜。不会添加额外服务（申报价值、亲手投递、回执通知）。每家商店只显示一种 Correios 服务，且货币汇率不会自动更新。
许可证密钥
插件使用从 vibefox.net 获取的 VibeFox 许可证密钥运行。许可证区块位于 WooCommerce > Settings > Shipping > VibeFox Correios 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期至何时，以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入另一个密钥，使用 Remove key 将其从此站点移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥不会释放该域名的名额。请在您的 vibefox.net 账户中释放名额。
没有有效密钥时，Correios 不会在结账时向顾客显示。已登录的商店管理员仍可看到，并标注为 (unlicensed — visible to admins only)，以便您在购买密钥前设置和测试插件。插件页面和 WooCommerce 页面上会出现提醒。现有订单不受影响。
许可证到期后，插件仍可继续工作，但更新和支持需要续费。状态会在后台自动重新检查。
故障排除
结账时没有显示 Correios：请检查许可证是否有效、Enable/Disable 是否开启，以及该方式是否已添加到顾客所在国家的区域（或 Ignore shipping zones 已开启且该国家被允许）。检查重量限制、Minimum order amount 和 Excluded shipping classes。没有实时运费时，必须存在该国家或 * 的固定运费。
该方式显示固定运费而不是 Correios 运费：打开 WooCommerce > Status > Logs，来源选择 vfd-correios。Correios 错误会记录在那里：访问代码错误、服务不在您的合同中、CEP 不在服务范围内、包裹超过 30 kg 或超出尺寸限制。还请检查是否已设置发货 CEP，以及如果商店货币不是 BRL，是否已设置 BRL 汇率。开启 Debug log 可查看每次计算。
令牌请求失败：请检查 API 用户、访问代码、posting card 和环境。测试访问代码仅在 Homologation 开启时有效，正式访问代码仅在该选项关闭时有效。
修改后运费看起来过时：保存设置页面。这会清除缓存的价格和 API 令牌。
许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在另一个域名上使用，请在 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now 以便为新域名激活该密钥。如果无法连接许可证服务器，插件将继续使用最后一次已知的状态运行。
卸载
停用插件会保留所有数据。要删除它，请先停用，然后在 Plugins 页面删除。该插件的许可证密钥和许可证状态始终会被删除。只有在 Remove data on uninstall 开启时，设置、区域方式和缓存的价格才会被删除；否则它们会保留，以便之后重新安装。订单永远不会被改动。
Correios 是其各自所有者的商标。本插件与 Correios 没有关联，也未获得 Correios 的认可。