您将获得
出生日期， 按您的规则使用。
ECA Digital（巴西数字环境未成年人保护法）要求可靠的年龄核验，仅靠用户自行申报并不够。将 CPF 出生日期与持有人姓名进行核对，是这一流程的组成部分。
出生日期
以 DD/MM/YYYY 格式返回，同时拆分为日、月、年。计算年龄只需简单运算，无需解析文本。
birthDatedaymonthyear持有人姓名
与注册时填写的姓名比对，确认 CPF 属于正在注册的本人。
namenameUpper年龄门槛由您设定
API 不返回现成的年龄段。您可以设定 18+、16+ 或 21+，并随时调整规则。
无需自拍，无需证件
这是一次登记信息查询。不需要摄像头、OCR 或文件上传，注册流程不会多出步骤。
工作原理
三个步骤， 完成一次年龄计算。
查询返回出生日期。年龄在您的后端计算，规则按您的产品需要设定。
- 01
查询用户提供的 CPF
在注册、结账或首次访问时，携带 x-api-key 请求头发起 GET /cpf/{cpf} 请求。CPF 放在 URL 中，带不带格式符号均可。
- 02
读取出生日期
JSON 中包含 DD/MM/YYYY 格式的 birthDate，以及独立的日、月、年字段。获取年份无需解析字符串。
- 03
套用您的规则
您的后端核对姓名、计算年龄并做出决定：允许访问、要求监护人同意，或启用其他年龄核验方式。决定权在平台。
async function verificarIdade(cpf, nomeDigitado) {
const res = await fetch(`https://api.cpfhub.io/cpf/${cpf}`, {
headers: { 'x-api-key': process.env.CPFHUB_API_KEY },
})
// CPF 无记录：使用其他年龄核验方式
if (res.status === 404) return { status: 'sem_registro' }
// 其他错误（400、422、403、429）：按 HTTP 状态码处理
if (!res.ok) return { status: 'erro', http: res.status }
const { data } = await res.json()
// 归属核验：填写的姓名必须与 CPF 姓名一致
const mesmoNome = nomeDigitado.trim().toLocaleUpperCase('pt-BR') === data.nameUpper
const hoje = new Date()
let idade = hoje.getFullYear() - data.year
const aindaNaoFezAniversario =
hoje.getMonth() + 1 < data.month ||
(hoje.getMonth() + 1 === data.month && hoje.getDate() < data.day)
if (aindaNaoFezAniversario) idade -= 1
return { status: 'ok', mesmoNome, idade, maiorDeIdade: idade >= 18 }
}适用场景
年龄决定 访问权限的地方。
从注册到结账，查询可以嵌入您现有的流程，用户无需多走一步。
适用范围
查询能覆盖什么，不能覆盖什么。
未查到的 CPF 不消耗积分。对于没有 CPF 或不在数据库中的用户，备用流程由您的平台决定。
- 查到 CPFHTTP 200，返回 birthDate。消耗 1 个积分。
- 有效 CPF 但无记录HTTP 404。不返回出生日期，不收费。请使用其他年龄核验方式。
- CPF 格式错误或校验位错误HTTP 400 或 422。不收费。请用户更正。
- 用户没有 CPF不在查询范围内。由平台指定其他年龄核验方式。
- 免费版积分已用完HTTP 403。API 停止服务，直到下一个计费周期或您升级到其他套餐。
CPFHub.io 提供出生日期，为您的合规工作提供支持。我们不做生物识别验证，不读取证件，也不封禁用户。最终决定以及 ECA Digital 合规责任仍由平台承担。
常见 问题
只凭 CPF 就能验证用户年龄吗？
可以，前提是用户提供的 CPF 有登记记录。标准查询（GET /cpf/{cpf} ）返回姓名、性别和出生日期（birthDate 为 DD/MM/AAAA 格式，另含 day、month 和 year）。您的系统计算年龄并应用规则要求的门槛。CPFHub.io 不直接返回年龄，也不会拦截用户。
API 会计算年龄或返回年龄段吗？
不会。响应中包含出生日期，由您的后端与当天日期比较计算。year 字段单独返回，便于计算。这样年龄门槛（18+、16+、21+）和业务规则都由您掌控。
在 ECA Digital 下，用户自报年龄还够吗？
ECA Digital（第 15.211/2025 号法律）要求采用可靠的年龄保证机制，单纯的自我声明不符合要求。CPF 登记的出生日期，结合持有人姓名核对，可作为年龄保证流程的一部分。方法选择和合规责任由平台承担。
CPF 查询能替代 ECA Digital 合规吗？
不能。法律要求年龄保证，CPFHub.io 提供出生日期供您的系统判断。政策、流程、家长同意等其他义务仍由平台承担。如有疑问，请咨询您的法务团队，并参考巴西国家数据保护局（ANPD）的指引。
查不到 CPF 怎么办？
API 返回 404，不消耗积分。没有登记记录就没有出生日期，您的系统需要为该用户准备替代路径，例如其他年龄保证方式或人工审核。格式或校验位错误的 CPF 返回 400 或 422，同样不计费。
没有 CPF 的用户可以用吗？
不能直接使用。查询依赖用户提供 CPF。没有 CPF 的人（例如部分外国人）需要平台另行确定其他年龄保证方式。
CPFHub.io 会使用自拍、生物识别或证件识别吗？
不会。标准查询是登记数据查询，不涉及摄像头、自拍、OCR 或证件上传。它不是生物识别身份验证。
验证年龄的费用是多少？
查到 CPF 的查询消耗 1 个积分。免费版每月包含 50 个积分，无需信用卡，积分用尽后 API 停止响应。Pro 版每月 R$ 19（巴西雷亚尔）起，含 100 个积分，档位最高 10,000 个，超额用量每次查询 R$ 0.19 至 R$ 0.10。未查到的 CPF 不计费。
可以核验现有用户库的年龄吗？
可以。批量查询（POST /cpf/bulk ）每批最多 10,000 个 CPF，异步处理，返回相同字段。只有查到的 CPF 消耗积分。
ECA Digital 何时开始执法？
该法自 2026 年 3 月 17 日起生效，并由第 12.880/2026 号法令作出规定。根据实施时间表，带罚款的执法自 2027 年 1 月开始。具体期限和要求请与 ANPD 及您的法务团队确认。