身份验证

创建 验证链接，发送给用户，然后获取 审核结果。验证页面由 CPFHub.io 托管，负责活体检测、读取证件（CNH 驾驶证、电子版 CNH、RG 身份证或护照）、将人脸与证件照片比对，并向 Receita Federal（巴西联邦税务局）核验 CPF（巴西个人税号）。每次完成的验证消耗 5 个积分。

正在使用 Cursor、Lovable、v0 或其他 AI 工具？复制身份验证的提示词，粘贴到您的 AI 助手中。

在 Cursor 中打开

正在使用 Cursor、Lovable、v0 或其他 AI 工具？复制身份验证的提示词，粘贴到您的 AI 助手中。

在 Cursor 中打开

POST /kyc/links 创建链接并返回 url。
您将 url 发送给用户，或在注册流程中将用户重定向到该地址。
审核结果会推送到您的 webhook，也可以通过 GET /kyc/links/{id} 查询。

本验证不会将证件与政府数据库比对，也不进行证件司法鉴定。电子驾驶证（CNH Digital）只接受从 Carteira Digital de Trânsito 应用导出的 PDF。截图或翻拍屏幕的照片会在计费前被拒绝。

创建链接

POSThttps://api.cpfhub.io/kyc/links

位置	名称	必填	说明
请求头	`x-api-key`	是	您的 API 密钥，与查询使用的密钥相同
请求体	`externalId`	否	您为这次注册设定的标识（最多 200 个字符）。会在 webhook 中返回。
请求体	`cpf`	否	您已知的 CPF。如果与证件不一致，验证会转入人工审核。响应中永远不会返回该字段。
请求体	`redirectUrl`	否	用户完成后返回的地址。仅支持 `https`。
请求体	`language`	否	`pt-BR`、`en` 或 `es`。默认：浏览器语言。
请求体	`expiresInMinutes`	否	有效期，`5` 到 `10080`。默认：`1440`（24 小时）。
请求体	`maxAttempts`	否	尝试次数，`1` 到 `10`。默认：`3`。

curl -X POST "https://api.cpfhub.io/kyc/links" \
  -H "x-api-key: $CPFHUB_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "externalId": "cliente-4821",
    "redirectUrl": "https://seusite.com.br/cadastro/concluido"
  }'

HTTP 201 Created

JSON

{
  "success": true,
  "data": {
    "id": "5b1d7c2e-8a4f-4e7b-9c3d-2f6a1e0b9d47",
    "url": "https://verificar.cpfhub.io/AbC123xYz",
    "externalId": "cliente-4821",
    "expiresAt": "2026-10-28T14:00:00.000Z",
    "maxAttempts": 3,
    "language": null
  }
}

请保存 id，它会在 webhook 中以 linkId 返回。用户完成后会回到 redirectUrl，URL 中带有 kyc_link_id 和 external_id，但不包含审核结果。请通过 webhook 或查询接口确认结果。

查询链接

GEThttps://api.cpfhub.io/kyc/links/{id}

JSON

{
  "success": true,
  "data": {
    "id": "5b1d7c2e-8a4f-4e7b-9c3d-2f6a1e0b9d47",
    "url": null,
    "externalId": "cliente-4821",
    "status": "completed",
    "attempts": 1,
    "maxAttempts": 3,
    "expiresAt": "2026-10-28T14:00:00.000Z",
    "createdAt": "2026-10-27T14:00:00.000Z",
    "completedAt": "2026-10-27T14:06:12.000Z",
    "verification": {
      "id": "8f3c2a1e-77b0-4d3c-9a1f-0e5b6c7d8e9f",
      "status": "approved",
      "reasons": [],
      "completedAt": "2026-10-27T14:06:12.000Z"
    }
  }
}

链接 status：pending、completed、expired 或 canceled。只有在链接仍可使用时才返回 url。用户完成前 verification 为 null。响应不含个人数据。

审核结果

`verification.status`	含义
`approved`	全部通过。链接已关闭。
`manual_review`	需要您的团队人工处理（见 `reasons`）。请在控制台中审核。链接已关闭。
`rejected`	按账户规则被拒绝。在尝试次数用完前，用户可以重试。

原因在 reasons 中以 [{ "code", "message" }] 形式返回。常见原因有：face_similarity_borderline、document_expired、ocr_failed、cpf_document_mismatch、cpf_name_mismatch 和 cpf_situation_irregular。遇到未知的 code 时请按人工审核处理，message 只向您的团队展示。

设置

可接受的证件、人脸相似度阈值、人工审核、过期证件、品牌样式、数据保留期限和 webhook 均在控制台的 Verificações > Configurações（验证 > 设置）中配置，并适用于账户下的所有链接。

错误

状态码	触发场景	处理方式
`400`	参数无效（`redirectUrl` 不是 `https`、`cpf` 无效、取值超出范围）	修正请求体。不要重试。
`401`	API 密钥缺失、无效或已停用	检查 `x-api-key` 请求头。
`403`	账户已停用或封禁	联系支持团队。
`404`	链接不存在或属于其他 API 密钥	检查 `id`。
`503`	临时故障	按递增间隔重试（2 秒、4 秒、8 秒）。

错误格式见错误码。

费用

每次完成的验证消耗 5 个积分，与查询共用同一余额，即使结果为拒绝也会计费。费用已包含 CPF 交叉核验。创建和查询链接免费，因我方技术故障导致的失败不计费。

⚠

链接即验证入口

任何拿到 url 的人都可以代替用户完成验证。请为每位用户单独创建链接，只发送给本人，并在流程允许的范围内使用尽可能短的有效期和尽可能少的尝试次数。

更新于 2026 年 10 月 27 日