简介

通过 CPFHub.io API，您只需发送一次带身份认证的 HTTP 请求，即可查询与 CPF（巴西个人税号）关联的登记信息：姓名、出生日期和性别。它还可以直接向 Receita Federal（巴西联邦税务局）查询 CPF 的登记状态，并支持批量处理 CPF 列表。

您可以做什么

通过 CPF 号码查询全名、出生日期和性别
检查 CPF 的校验位是否有效
根据 year、month 和 day 计算持有人的年龄
在注册或交易流程中加入年龄验证
实时向 Receita Federal 查询 CPF 的登记状态和死亡年份，并获取控制码和查询凭证（实时查询）

接口

方法	接口	说明	费用
`GET`	`/cpf/{cpf}`	标准查询：从 CPFHub.io 数据库返回姓名、性别和出生日期	每查到 1 个 CPF 消耗 1 积分
`POST`	`/cpf/realtime`	向 Receita Federal 发起的实时查询：登记状态、死亡年份（`deathYear`，整数或 `null`）、控制码和查询凭证	每次成功查询消耗 1.5 积分
`POST`	`/cpf/bulk`	异步批量查询，最多 10,000 个 CPF	每查到 1 个 CPF 消耗 1 积分
`GET`	`/cpf/bulk/{jobId}`	批量任务的状态和结果	免费
`GET`	`/quota`	积分余额、用量和套餐	免费

以上为默认费用。您账户的具体费用请在控制台中查看。

Base URL

所有请求都必须使用 HTTPS：

https://api.cpfhub.io

通过 http:// 发送的请求会收到指向 HTTPS 的 301 重定向。许多 HTTP 客户端在跟随该重定向时会把 POST 变成 GET，因此请始终直接使用 https://。

响应格式

API 响应使用 Content-Type: application/json。唯一的例外是查询凭证（validationHtmlUrl），它以 text/html 格式提供。

成功（2xx）：

JSON

{
  "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
  }
}

错误（4xx / 5xx）：

JSON

{
  "success": false,
  "data": null,
  "error": {
    "message": "CPF não encontrado na base de dados"
  }
}

API 的错误信息只有葡萄牙语版本。上面这条的意思是“数据库中未找到该 CPF”。请根据 HTTP 状态码决定处理流程。大多数错误带有 error.message。身份认证和账户错误（401，以及账户被封禁时的 403）、500 "Erro ao validar assinatura"（“验证订阅时出错”）和 503 "usage_unavailable" 的 error 是字符串：

JSON

{
  "success": false,
  "error": "API Key não fornecida"
}

这条信息的意思是“未提供 API 密钥”。要同时兼容两种格式读取错误信息，可以使用：typeof body.error === 'string' ? body.error : body.error?.message。完整列表见错误码。

身份认证

每个请求都需要在 x-api-key 请求头中携带您的 API 密钥：

bash

curl "https://api.cpfhub.io/cpf/12345678909" \
  -H "x-api-key: YOUR_API_KEY"

您可以在 app.cpfhub.io/api-keys 免费获取密钥。密钥是一个不透明字符串，请不要依赖它的前缀或格式。

下一步

身份认证：API 密钥与安全
标准查询：字段、参数和示例
实时查询：登记状态、死亡年份和 Receita Federal 查询凭证
批量查询：每个请求最多 10,000 个 CPF
积分余额：账户的余额、用量和套餐
用量限制：各套餐的积分和每分钟速率限制
错误码：完整错误列表以及何时重试

更新于 2026 年 10 月 3 日