CPFHub.io
免费开始

实时查询

发送 CPF（巴西个人税号）和 出生日期，即可直接从 Receita Federal（巴西联邦税务局）获取 姓名、出生日期、死亡年份、登记状态、控制码 和 查询凭证。每次查询消耗 1.5 个积分。

正在使用 Cursor、Lovable、v0 或其他 AI 工具？ 复制实时查询的提示词，粘贴到您的 AI 助手中。

在 Cursor 中打开

不确定该用哪种查询？请对比各查询方式。

端点

POSThttps://api.cpfhub.io/cpf/realtime

参数

位置名称必填说明
请求头x-api-key是您的 API 密钥，与标准查询使用的密钥相同。见身份认证。
请求头Content-Type是application/json
请求体cpf是带或不带格式的 CPF：12345678909 或 123.456.789-09
请求体birthDate是出生日期，8 位数字（日、月、年）：DD/MM/YYYY 或 DDMMYYYY。分隔符会被忽略。年份须在 1900 年至今年之间。

示例

示例从 CPFHUB_API_KEY 读取密钥，设置 60 秒超时，并按 HTTP 状态码处理错误。

curl --max-time 60 -X POST "https://api.cpfhub.io/cpf/realtime" \
  -H "x-api-key: $CPFHUB_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "cpf": "12345678909",
    "birthDate": "15/06/1990"
  }'

响应

HTTP 200 OK

JSON
{
  "success": true,
  "data": {
    "cpf": "12345678909",
    "name": "FULANO DE TAL",
    "birthDate": "15/06/1990",
    "deathYear": null,
    "situation": "REGULAR",
    "emissionDate": "02/10/2026",
    "emissionTime": "14:15:16",
    "controlCode": "ABCD.1234.EFGH.5678",
    "validationUrl": "https://servicos.receita.fazenda.gov.br/Servicos/CPF/ca/ResultadoAut.asp?cp=12345678909&cc=ABCD1234EFGH5678&de=02102026&he=141516&dv=09&em=01",
    "validationHtmlUrl": "https://api.cpfhub.io/cpf/proof/12345678909/1790950516000"
  }
}
字段类型说明
data.cpfstring查询的 CPF，11 位数字，不带格式
data.namestringReceita Federal 登记的姓名，大写
data.birthDatestring出生日期，DD/MM/YYYY
data.deathYearinteger | null死亡年份。始终返回：未登记死亡或收到的值无效时为 null。有效值为 4 位数字，在 1900 年至今年之间，且不早于出生年份。
data.situationstring登记状态（见下表）
data.emissionDatestring凭证签发日期，DD/MM/YYYY。可选。
data.emissionTimestring签发时间，HH:MM:SS。可选。
data.controlCodestring凭证控制码（XXXX.XXXX.XXXX.XXXX）。可选。
data.validationUrlstringReceita Federal 网站上的核验链接（二维码指向的地址）。可选。
data.validationHtmlUrlstringCPFHub.io 保存的查询凭证（带二维码的 HTML）。可选。

可选字段可能缺失，取决于 Receita Federal 的返回内容和凭证生成情况。deathYear 不是可选字段，它始终存在，值为有效整数或 null。

登记状态

situation 的取值为葡萄牙语，与 Receita Federal 的登记内容一致。

situation含义
REGULARCPF 状态正常，无待处理事项
PENDENTE DE REGULARIZAÇÃO缺少纳税申报或登记信息需要更新（待规范）
SUSPENSA登记信息错误或不完整（已暂停）
CANCELADA因行政或司法决定，或因重复登记而注销（已注销）
NULA因欺诈被宣告无效（无效）
TITULAR FALECIDO登记记录显示持有人已死亡（持有人已故）

只有 REGULAR 表示 CPF 无待处理事项。所有状态都以 200 返回，并消耗积分。

错误

API 只返回葡萄牙语信息。错误信息按原样列出，首次出现时在括号内附中文释义。

状态码触发场景处理方式
400CPF 不是 11 位数字，或 birthDate 缺失、无效修正请求体。不要重试。
401API 密钥缺失、无效或已停用（error 为字符串）检查 x-api-key 请求头。
403积分不足且未开通超额用量（error.message："Limite de créditos excedido"，积分额度已超出），或账户已停用/封禁（error 为字符串）补充积分或联系支持团队。不要重试。
422校验位错误，或 Receita Federal 拒绝了查询（例如出生日期不匹配）修正 CPF 或日期。不消耗积分。请按状态码处理，不要依赖文本（文本来自 Receita Federal）。
429超出每分钟限制（默认 5 次/分钟）等待 Retry-After 请求头给出的秒数。不消耗积分。
500内部错误如持续出现，请反馈给我们。
502, 503Receita Federal 或积分预留环节出现临时故障按递增间隔重试（2 秒、4 秒、8 秒）。不消耗积分。

错误格式、重试策略以及如何在不消耗积分的情况下测试，见错误码。每分钟限制和积分规则见使用限制。

补充说明

  • 费用： 每次返回 200 的查询消耗 1.5 个积分，与登记状态无关。部分套餐有单独的费用，请在控制台查看您套餐的费用。
  • 响应时间： 取决于 Receita Federal。请设置至少 60 秒的超时。如果您的流程无法等待，请异步调用。
  • 不支持批量： 每次只能查询一个 CPF。
  • 本地超时后不要重试： 该 POST 请求不是幂等的。查询可能已完成并计费。再次尝试前，请先用 GET /quota 查看余额。
  • 示例数据： CPF 12345678909 及上方数据均为虚构。
⚠

凭证链接是公开的

任何拿到 validationHtmlUrl 链接的人都能打开凭证（姓名、CPF 和状态）。请将其视为个人数据：只保存在后端，不要写入日志，也不要在前端展示。

更新于 2026 年 10 月 4 日