您将获得
输入 CPF， 得到这个人的信息。
用户还没输完，11 位数字就已经变成一条完整的记录。
持有人姓名
带葡萄牙语重音符号的全名。nameUpper 字段提供同一姓名的大写形式，便于与用户填写的内容比对。
namenameUpper出生日期
以 DD/MM/YYYY 格式返回，同时拆分为日、月、年。计算年龄只需简单运算，无需解析文本。
birthDatedaymonthyear性别
M 或 F，以登记信息为准。数据不存在时可能为 null。
gender标准化的 CPF
11 位纯数字，不含点和连字符，即使您提交的是带格式的 CPF。
cpf工作原理
三个步骤， 没有繁琐手续。
从新建账户到在生产环境拿到第一份 JSON，中间没有销售环节。
- 01
创建账户并复制密钥
在 app.cpfhub.io 自助注册，无需 e-CNPJ（巴西企业数字证书）、数字证书或合同。注册完成后，API 密钥立即显示在控制台中。
- 02
调用 GET /cpf/{cpf}
一次携带 x-api-key 请求头的 HTTP 请求。CPF 放在 URL 中，带不带格式符号均可。无需请求体，无需 OAuth，也没有会过期的令牌。
- 03
拿到 JSON，继续流程
姓名、性别和出生日期在同一次调用中返回。表单自动填写，或由您的校验规则当场做出判断。
支持任意编程语言集成
REST API，提供 OpenAPI 规范和现成示例，简单到您的 AI 智能体可以自行完成集成。
# 发送 CPF，返回姓名、性别和出生日期
curl -X GET \
'https://api.cpfhub.io/cpf/12345678909' \
-H 'x-api-key: YOUR_API_KEY'{
"success": true,
"data": {
"cpf": "12345678909",
"name": "Fulano de Tal",
"nameUpper": "FULANO DE TAL",
"gender": "M",
"birthDate": "15/06/1990",
"day": 15,
"month": 6,
"year": 1990
}
}每月 50 个免费积分，无需信用卡。
适用场景
为关键路径 而设计。
用查询取代手动录入、电话核实和注册返工。
自动填写注册表单
用户输入 CPF，表单其余部分自动补全。需要填写的字段越少，流失越少，写入数据库的数据也已经标准化。
注册和结账环节的反欺诈
将用户填写的姓名和出生日期与 API 返回结果比对。不一致的情况转入人工审核，而不是变成拒付。
年龄验证
年份字段单独返回，正是为了这个场景。无需解析字符串即可计算年龄，并套用您的年龄段规则。
客户档案清理
老数据库里姓名拼错、出生日期缺失。把 CPF 交给 API 处理，整个档案即可完成规范化。
客服环节核验
客服在通话中确认持有人的姓名和出生日期，不必依赖客户当场的记忆。
通过 MCP 接入 AI 智能体
官方 MCP 服务器将查询功能作为工具开放。Claude、Cursor 和 Windsurf 可以直接查询 CPF，您无需编写 HTTP 客户端。
积分与错误
未查到的 CPF 不消耗积分。
您为结果付费，而不是为尝试付费。杂乱的数据库不会变成虚高的账单。
积分如何扣除
- 查到 CPF 的查询消耗 1 个积分。
- 无记录的 CPF 返回 404，不消耗积分。
- 格式错误或校验位错误的 CPF 返回 400 或 422，不查询也不收费。
- GET /quota 显示您的余额，从不消耗积分。
- 默认速率限制为每个密钥每分钟 30 次请求（每个批次计为 1 次）。超出后 API 返回 429，不消耗积分。
响应状态码
| 200 | 查到 CPF。消耗 1 个积分。 |
| 400 | 去除非数字字符后，CPF 不足 11 位。 |
| 401 | API 密钥缺失或无效。 |
| 403 | 不含超额用量的套餐积分已用完，或账户未激活。 |
| 404 | CPF 有效，但无记录。不消耗积分。 |
| 422 | 校验位错误，包括重复数字序列。 |
| 429 | 每分钟请求超过 30 次。请按 Retry-After 响应头中的时间等待。不消耗积分。 |
套餐
从免费版开始， 需要时再升级。
标准查询（1 个积分）和实时查询（1.5 个积分）共用同一余额。切换接口无需切换套餐。所有价格均以巴西雷亚尔（BRL）计。
免费版
R$ 0
每月 50 个积分，无需信用卡
SLA 95%
Pro 版
R$ 19 起（巴西雷亚尔）
每月 100 至 10,000 个积分，超额用量单价 R$ 0.19 至 R$ 0.10
SLA 99%
企业版
定制价格
每月超过 10,000 个积分
SLA 99.9%
常见 问题
巴西 CPF 查询 API 返回什么？
全名、性别（M/F）和出生日期。字段：cpf（11 位数字，无格式符号）、name、nameUpper、gender、birthDate、day、month 和 year。不返回评分、地址、电话或电子邮箱。如需登记状态、死亡年份和凭证，请使用实时查询（/zh/cpf-lookup-federal-revenue）。
API 支持单次查询和批量查询吗？
支持。标准查询为 GET /cpf/{cpf} ，批量为 POST /cpf/bulk （最多 10,000 个 CPF，异步任务，通过 GET /cpf/bulk/{jobId} 轮询）。另有 GET /quota 查询余额和套餐，不消耗积分。
需要 e-CNPJ 或数字证书吗？
不需要。集成完全自助：创建账户，从控制台复制 API 密钥，放在 x-api-key 请求头中发送即可。无需 e-CNPJ，无需生物识别。
CPF 查询 API 的价格是多少？
免费版：每月 50 个积分，无需信用卡，SLA 95%。Pro 版：每月 R$ 19（巴西雷亚尔）起，含 100 个积分（最高 10,000 个），超额用量按量计费，每个积分 R$ 0.19 至 R$ 0.10，SLA 99%。企业版：定制价格，SLA 99.9%。详见 /zh/pricing。
与实时查询有什么区别？
标准查询只需 CPF，从我们的数据库返回姓名、性别和出生日期，消耗 1 个积分。实时查询还需要持有人的出生日期，实时查询 Receita Federal（巴西联邦税务局），返回登记状态、死亡年份（deathYear，整数或 null）、控制码和 HTML 凭证，每次成功查询消耗 1.5 个积分。两者使用同一个密钥和同一份余额。
有请求频率限制吗？
有，按每个 API 密钥每分钟计算：标准查询每分钟 30 次（每个批量任务计为 1 次），实时查询每分钟 5 次。超出时 API 返回 429 和 Retry-After，不消耗积分。用量由套餐的积分余额控制。免费版（每月 50 个积分）积分用尽后 API 停止响应。开启超额用量的付费套餐会继续响应，超额部分计入下一个计费周期。
未查到的 CPF 消耗积分吗？
不消耗。只有返回数据的查询才消耗积分。有效但无记录的 CPF 返回 404，不计费。校验位错误的 CPF 返回 422，不会执行查询。
API 能与 AI 智能体配合使用吗？
可以。官方 MCP 服务器地址为 https://api.cpfhub.io/mcp ，以工具形式向 Claude、Cursor 和 Windsurf 提供查询能力，使用同一个 API 密钥。无需自己编写 HTTP 客户端。
API 符合 LGPD 吗？
符合。我们依据法律依据和隐私规范处理个人数据。LGPD 即巴西《通用数据保护法》。数据保护官（DPO）：dpo@cpfhub.io。隐私政策见 /zh/privacy。