身份认证
每个发往 CPFHub.io API 的请求都必须通过 x-api-key 请求头携带 API 密钥 完成身份认证。
获取 API 密钥
创建账户时，系统会自动生成一个 API 密钥。您可以随时前往 app.cpfhub.io/api-keys 查看和复制。
如有需要，您可以在同一页面生成新密钥。每个账户只有一个有效密钥。生成新密钥后，旧密钥会在 5 分钟内失效，并开始返回 401 和 "API Key inativa"（API 密钥已停用）。
ℹ
在生产环境中轮换密钥
不存在两个密钥同时有效的过渡期。请在能够立即更新系统中密钥配置时再生成新密钥，以免查询中断。
密钥是一个不透明字符串。请不要在代码中校验它的前缀、长度或格式。
⚠
安全保存您的密钥
切勿在客户端代码、公开代码仓库或日志中暴露 API 密钥。请使用环境变量。
发送 API 密钥
在每个请求中加入 x-api-key 请求头：
bash
curl "https://api.cpfhub.io/cpf/12345678909" \
-H "x-api-key: $CPFHUB_API_KEY"将密钥保存在环境变量中（示例中为 CPFHUB_API_KEY），并在代码中从环境变量读取。
基础 URL
所有请求都必须使用 HTTPS：
https://api.cpfhub.io通过 http:// 发出的请求会收到 301 重定向到 HTTPS。许多 HTTP 客户端在跟随重定向时会把 POST 改为 GET，导致实时查询和批量查询失败。请始终使用 https://。
身份认证错误
API 只返回葡萄牙语信息，因此下方的 error 信息按原样列出，括号内为中文释义。
| 状态码 | 信息（error） | 触发场景 |
|---|---|---|
401 | API Key não fornecida（未提供 API 密钥） | 未发送 x-api-key 请求头 |
401 | API Key inválida（API 密钥无效） | 密钥不存在 |
401 | API Key inativa（API 密钥已停用） | 该密钥已在控制台中被新密钥替换 |
403 | Usuário inativo. Entre em contato com o suporte.（用户已停用，请联系支持团队） | 账户已停用 |
403 | Conta bloqueada. Entre em contato com o suporte.（账户已封禁，请联系支持团队） | 账户已封禁 |
在这些情况下，error 字段是字符串：
JSON
{
"success": false,
"error": "API Key não fornecida"
}同一个 API 密钥适用于所有端点：标准查询、实时查询、批量查询、CNPJ 查询、CNPJ 批量查询和积分余额。
各错误的完整说明见错误码。
更新于 2026 年 10 月 15 日