您将获得
不只是数据， 更是凭证。
知道一件事，和日后能证明这件事，是两回事。
登记状态
正常、待规范、暂停、注销、无效或持有人已故，以查询时 Receita Federal 的登记为准。
situation死亡年份
始终返回，值为整数或 null。只有年份，不含日和月。没有死亡记录，或从 Receita 收到的值无效时，返回 null。
deathYear查询凭证
一个包含查询结果的 HTML 页面，可直接归档，并附有在 Receita Federal 网站上核对该查询的链接。
validationHtmlUrlvalidationUrl出具时间和控制码
Receita 响应的精确日期和时间，以及标识本次查询的控制码。可证明核验发生在决策之前。
emissionDateemissionTimecontrolCode响应中还包含持有人的大写姓名和出生日期（name 和 birthDate）。
查看完整的响应参考登记状态
六种可能的 结果。
其中一种意味着可以放行。另外五种，正是您需要查询的原因。
正常
CPF 状态良好，无待处理事项。
待规范
缺少纳税申报，或登记信息需要更新。
暂停
登记信息有误或不完整。
注销
因行政或司法决定，或因重复登记而被注销。
无效
通过欺诈手段取得的登记。
持有人已故
Receita Federal 登记中有死亡记录。
工作原理
输入两项数据， 输出一份凭证。
无需数字证书，无需 e‑CNPJ（巴西企业数字证书），无需电子授权书，也不用在 Receita 网站上排队。
- 01
您提交两项数据
CPF 和持有人的出生日期。这是 Receita Federal 响应查询所需的信息，我们也只要求这些。
- 02
我们当场查询 Receita
没有中间数据库，也不是昨天的副本。查询在您调用的那一刻于 Receita Federal 完成。
- 03
您获得 JSON 和凭证
登记状态、死亡年份、出具日期和时间、控制码以及凭证链接。由您的系统做出决定并归档凭证。
响应时间取决于 Receita Federal。如果您的流程不能等待，请在关键路径上使用标准查询，在需要凭证的环节使用本查询。
支持任意编程语言集成
使用您现有的同一个密钥，只需换一个路由。提供十种语言的现成示例。
# 从 Receita Federal 获取税务登记状态，附凭证
curl -X POST \
'https://api.cpfhub.io/cpf/realtime' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'content-type: application/json' \
-d '{"cpf":"12345678909","birthDate":"15/06/1990"}'{
"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…",
"validationHtmlUrl": "https://api.cpfhub.io/…"
}
}每月 50 个免费积分，无需信用卡。
适用场景
当有人 会要求出示凭证时。
任何决策会变成合同、付款或记录，并且日后必须经得起检查的流程。
合同与法务
HTML 凭证记录了识别合同各方时的尽职调查，包含日期、时间和控制码。
薪资与福利
当登记中有死亡记录时，响应会在 deathYear 中返回死亡年份，并返回 TITULAR FALECIDO（持有人已故）状态。不当付款在发出之前即可拦截。
受监管行业的开户
当监管机构要求您证明核验过什么时，凭证文件比 API 日志更有说服力。
价格
同一套餐，同一积分余额。
实时查询与标准查询使用同一个密钥、同一个套餐和同一余额。默认每次完成的查询消耗 1.5 个积分，部分套餐的数值不同。
1.5 个积分
每次完成的查询，标准查询为 1 个积分
0 个积分
CPF 格式错误或 Receita Federal 未响应时
50
每月免费积分供您试用，无需信用卡
常见 问题
标准查询和实时查询有什么区别？
标准查询（GET /cpf/{cpf} ）只需 CPF，从我们的数据库返回姓名、性别和出生日期。实时查询（POST /cpf/realtime ）在 JSON 请求体中接收 CPF 和出生日期，在调用时查询 Receita Federal，返回登记状态、死亡年份（deathYear，整数或 null）、控制码和 HTML 凭证。两者是独立的接口，不会互相回退。
为什么实时查询需要出生日期？
这是 Receita Federal 自身的要求。其公开查询服务只在同时收到 CPF 和持有人出生日期时才会响应。如果您的流程中没有出生日期，应使用标准查询。
查询会返回死亡年份吗？
会在 deathYear 字段返回死亡年份。该字段始终存在，为整数或 null，不含日和月。无死亡记录，或收到的值无效时为 null。有效值须为 4 位数字，介于 1900 年和当前年份之间，且不早于出生年份。
各登记状态分别代表什么？
正常（Regular）：CPF 状态良好。待规范（Pendente de regularização）：缺少申报或登记信息需要更新。暂停（Suspensa）：登记信息有误或不完整。注销（Cancelada）：因行政或司法决定，或因重复登记而注销。无效（Nula）：通过欺诈取得的登记。持有人已故（Titular falecido）：登记中已记录死亡。
凭证如何使用？
响应包含 validationHtmlUrl 和 validationUrl。前者是 HTML 凭证，含查询数据、签发日期时间和控制码，后者是在 Receita Federal 网站核验该次查询的链接。在审计中，它可作为雇佣、租赁或签约决定的依据记录。
实时查询的价格是多少？
默认每次完成的查询 1.5 个积分，标准查询为 1 个积分（部分套餐数值不同）。与套餐共用同一余额，无需单独购买套餐包。格式或校验位错误的 CPF，以及与 Receita Federal 的通信故障（502 和 503）不消耗积分。
需要多长时间？
实时查询取决于 Receita Federal 的响应时间。如果您的流程无法等待，可异步调用，或在关键路径上使用标准查询。
实时查询能批量使用或通过 MCP 使用吗？
不支持批量。POST /cpf/bulk 只覆盖标准查询。可通过远程 MCP 服务器（https://api.cpfhub.io/mcp ）使用：它提供 lookup_cpf（标准查询）、lookup_cpf_realtime（实时查询，需 CPF 和出生日期，同样返回死亡年份 deathYear，整数或 null）和 get_quota_info（余额）。MCP 中没有批量工具。如需大批量使用实时查询，请通过 WhatsApp 或 contato@cpfhub.io 联系我们。
需要另开账户或另申请密钥吗？
不需要。使用的是您在 GET /cpf/{cpf} 上已有的同一账户、同一 x-api-key、同一套餐和同一积分余额。