您将获得
一万次查询， 一个请求。
队列编排、并发和重试都由我们处理。
每批最多 10,000 个 CPF
一个请求提交完整列表，立即拿到 jobId。无需发起一万次调用，也不会压垮您的服务器。
处理期间即可查看部分结果
批次不是黑盒。每次查询状态，您都能看到已处理数量、查到数量以及已完成的记录。
字段与标准查询一致
每个查到的 CPF 都返回姓名、性别和出生日期，格式与单次查询相同。未查到的 CPF 返回的字段为 null。
namenameUppergenderbirthDatedaymonthyear也可以不写代码
控制台支持 CSV 和 TXT 文件，自动识别分隔符和 CPF 列，并可导出结果。您也可以直接把列表粘贴到文本框中。
支持任意编程语言集成
两步完成：先提交清单，再查询批次结果。只需 HTTP。
# 第 1 步：提交 CPF 清单
curl -X POST "https://api.cpfhub.io/cpf/bulk" \
-H "x-api-key: YOUR_API_KEY" \
-H "content-type: application/json" \
-d '{"cpfs": ["12345678909", "11144477735", "52998224725"]}'
# → 202 Accepted { "jobId": "4a1ef25e-052c-4464-..." }
# 第 2 步：等待状态变为 "done"
curl "https://api.cpfhub.io/cpf/bulk/4a1ef25e-052c-4464-9657-4148f53bb0fc" \
-H "x-api-key: YOUR_API_KEY"{
"success": true,
"data": {
"id": "4a1ef25e-052c-4464-9657-4148f53bb0fc",
"status": "done",
"total_records": 3,
"processed": 3,
"found": 2,
"not_found": 1,
"skipped": 0,
"error": null,
"cpfs": [
{
"cpf": "12345678909",
"found": true,
"name": "Joao de Exemplo",
"nameUpper": "JOAO DE EXEMPLO",
"gender": "M",
"birthDate": "15/06/1985",
"day": 15,
"month": 6,
"year": 1985
},
{
"cpf": "52998224725",
"found": false,
"name": null,
"nameUpper": null,
"gender": null,
"birthDate": null,
"day": null,
"month": null,
"year": null
}
]
}
}每月 50 个免费积分，无需信用卡。
进度跟踪
批次进展到哪一步， 您始终清楚。
三种状态，五个计数器。批次是在运行、已完成还是已中断，一目了然。
processing
批次正在运行。查询状态会返回进度和已完成的记录。
done
批次已完成。响应中包含逐条的完整结果。
failed
批次已中断。超过 10 分钟没有进展的批次会被自动标记，不会一直处于待处理状态。
批次计数器
total_records进入批次的有效 CPF 数量。
processed已完成查询的数量。
found数据库中存在的数量。这是您需要付费的部分。
not_found没有记录的数量。不收费。
skipped因处理过程中余额用尽而被跳过的数量。
适用场景
当问题出在 整个数据库时。
逐个查询 CPF 需要花上几周，现实中没人会这么做。
清理历史数据库
老客户档案里姓名拼错、出生日期缺失。提交整个数据库，一次完成标准化。
系统迁移
把客户档案迁移到新系统之前，先确认哪些 CPF 真实存在，再决定其余记录如何处理。
存量用户反欺诈
找出数据库中不存在的 CPF，以及姓名或出生日期与用户填写信息不一致的记录，在造成损失之前处理掉。
定期档案审计
每月运行一次批量查询，跟踪数据库中有多少记录已经与返回的姓名和出生日期不符。
客户组合核对
在收款、续约或发放佣金之前，确认客户组合中的持有人与登记信息一致。
并购尽职调查
接手了另一家公司的客户组合？批量查询能在几小时内告诉您有多少记录是准确的。
计费方式
只为存在的 CPF 付费。
在老旧数据库中，很多记录已经失效。在这里，未查到的 CPF 不消耗积分，过时的数据不会让账单变大。
1 个积分
每个查到的 CPF，与标准查询相同
R$ 0
每个未查到、格式错误或校验位错误的 CPF（金额单位为巴西雷亚尔，BRL）
10,000
每批 CPF 上限，批次数量不限
在不含超额用量的套餐中，只有余额足以覆盖全部有效 CPF 时，批次才会被接受。如果处理过程中余额用尽，剩余的 CPF 会以 skipped 返回，不查询也不收费。
常见 问题
每个批量任务的上限是多少？
POST /cpf/bulk 每次请求最多 10,000 个 CPF。超出时 API 以 400 拒绝请求。更大的量请拆分为多个批次，或联系我们咨询企业版。
处理是同步还是异步？
异步。POST 创建批量任务并返回 jobId。查询 GET /cpf/bulk/{jobId} ，直到状态变为 done 或 failed。控制台也会显示进度。
未查到的 CPF 消耗积分吗？
不消耗。批量查询中只有 found: true 的条目消耗积分。未查到的 CPF 以及格式或校验位错误的 CPF 不计费。单次查询规则相同。
免费版可以使用批量查询吗？
可以。免费版可调用相同的端点，每月 50 个积分。在免费版等不支持超额用量的套餐中，只有余额足以覆盖全部有效 CPF 时才接受批量任务。余额不足时 API 返回 403，不扣任何积分。详见 /zh/pricing。
控制台支持哪些文件格式？
CSV 和 TXT。分隔符（分号或逗号）、表头和 CPF 列会自动识别。也可以将列表粘贴到文本框中。不支持 XLSX，请先导出为 CSV 再上传。
各批量任务状态分别代表什么？
processing：任务运行中，此时查询即可返回进度和已完成的记录。done：已完成，返回完整结果。failed：任务已中止。超过 10 分钟没有进度的任务会被自动标记为 failed。
批量任务进行中余额用尽会怎样？
剩余的 CPF 以 skipped 返回，不查询也不计费。充值后，只需将未处理的 CPF 重新提交为新的批量任务。
可以下载 CSV 格式的结果吗？
在控制台中可以。API 返回 JSON：每个 CPF 一条记录，字段与标准查询相同，未查到的 CPF 字段值为 null。
实时查询支持批量吗？
不支持。批量仅覆盖标准查询。实时查询为单次调用，每个 CPF 调用一次 POST /cpf/realtime 。如需大批量使用实时查询，请通过 WhatsApp 或 contato@cpfhub.io 联系我们。