常见问题

CPFHub.io API 返回哪些数据？

标准查询（GET /cpf/{cpf} ）和批量查询（POST /cpf/bulk ）：根据 CPF（巴西个人税号）返回全名、性别和出生日期。实时查询（POST /cpf/realtime ）：返回姓名、出生日期、死亡年份（deathYear，整数或 null）、在 Receita Federal（巴西联邦税务局）的登记状态、控制码和凭证。不返回评分、电子邮件，也不返回死亡的具体日和月。

CPFHub.io 会实时查询 Receita Federal 吗？

取决于接口。GET /cpf/{cpf} 从我们的数据库返回姓名、性别和出生日期（每个查到的 CPF 1 个积分）。POST /cpf/realtime 在调用时查询 Receita Federal，返回登记状态、死亡年份（deathYear，整数或 null）、控制码和凭证，但需要提供持有人的出生日期。仅在返回 HTTP 200 时消耗 1.5 个积分。失败的请求（包括出生日期不匹配导致的 HTTP 422）不消耗积分。两个接口相互独立，不会互相回退。

可以在用户注册时核验 CPF 和姓名吗？

可以。您发送 CPF，获得姓名和出生日期，再与用户在您的流程中填写的信息进行比对（反欺诈或用户注册）。匹配规则由您的系统决定。

支持批量查询吗？

支持。POST /cpf/bulk 为异步接口，每次请求最多接受 10,000 个 CPF。只有查到的 CPF 消耗积分。适合清洗数据库。不写代码的话，可以在控制台（app.cpfhub.io/lote）上传 CSV 或 TXT 文件进行批量查询。

CPFHub.io 提供基于自拍或 OCR 的 KYC（了解您的客户）吗？

提供，即身份验证（KYC）。您创建一个链接，用户完成自拍活体检测并拍摄证件（CNH、电子 CNH、RG 或护照），结果通过 webhook 推送。每次完成的验证默认消耗 5 积分。CPF 查询（标准查询、批量查询和实时查询）不涉及自拍或 OCR。

SLA（可用性保证）是多少？

按套餐区分，详见价格页面（/pricing ）：免费版 95%，Pro 版 99%，企业版 99.9%。批量查询的耗时取决于提交的 CPF 数量。

实时查询会返回死亡年份吗？

会。POST /cpf/realtime 返回 deathYear，即死亡年份，该字段始终存在，值为整数或 null。不返回日和月。没有死亡记录，或收到的值无效（不是 4 位数字、不在 1900 至当前年份之间，或早于出生年份）时为 null。

如何获取 API 密钥？

创建账户时会自动生成 API 密钥。您可以随时访问 app.cpfhub.io/api-keys 查看和复制。如有需要，也可以在同一页面生成新密钥。

免费版有查询次数限制吗？

有。免费版每月包含 50 个积分，积分用完后 API 将停止响应。付费套餐提供更大的用量。可用套餐请见价格页面。

有用于测试的沙盒环境吗？

测试直接在生产 API 上进行：每个账户每月包含 50 个免费积分，您可以用它们在生产环境中免费测试集成。未查到的 CPF（404）以及格式或校验位错误的 CPF（400/422）都不消耗积分，因此可以放心测试各种错误场景。

查不到 CPF 时会怎样？

API 返回 HTTP 404，error.message 为 "CPF não encontrado na base de dados"（葡萄牙语，意为“数据库中未找到该 CPF”）。该查询不会扣除套餐积分，您只需为成功的查询付费。

格式或校验位错误的 CPF 也消耗积分吗？

不消耗。格式错误（HTTP 400）或校验位错误（HTTP 422）的 CPF 不消耗积分，原因见 error.message。只有查到 CPF 的查询才会计费：标准查询和实时查询返回 HTTP 200，或批量查询中每项的 found 为 true。

API 会存储我查询的 CPF 吗？

会。每次查询都会记录所查询的 CPF、结果、日期和发起查询的账户，CPF 未查到时也会记录。这些记录用于控制台历史、积分计费、审计和反欺诈。实时查询还会保存 HTML 凭证。数据保留详情请见合规页面。

API 符合 LGPD（巴西《通用数据保护法》）吗？

符合。API 使用从私营数据提供商获得授权的数据和官方公开来源，除姓名、性别和出生日期外（实时查询还包括 Receita Federal 的登记状态和死亡年份），不返回其他敏感信息。可用于正当目的，例如身份验证、注册信息核验和反欺诈。

响应时间是多少？

标准查询在同一次调用中从我们的数据库返回结果（超时建议设为约 10 s）。实时查询取决于 Receita Federal 的响应时间（超时至少设为 60 s）。批量查询的耗时取决于提交的 CPF 数量。可用性 SLA 因套餐而异：免费版 95%，Pro 版 99%，企业版 99.9%。请查看 /pricing ，以及 app.cpfhub.io/status 上的服务状态。

可以在前端（浏览器）中使用 API 吗？

技术上可以，但不建议。在客户端代码中暴露 API 密钥存在安全风险。请始终从后端（服务器、serverless 函数、Next.js API Route）发起调用，切勿将密钥放入公开代码。

每秒或每分钟有请求次数限制吗？

有，按分钟和 API 密钥计算：默认标准查询每分钟 30 次请求（每次批量提交计为 1 次），实时查询每分钟 5 次。定制套餐的限制可能不同，请通过 suporte@cpfhub.io 向 CPFHub.io 支持团队确认。超出限制时，API 返回 HTTP 429 和 Retry-After header（需等待的秒数），不消耗积分。此外，在不支持超额计费的套餐中积分用完后，API 返回 HTTP 403，信息为 "Limite de créditos excedido"（“积分额度已超出”）。

有适用于我所用语言的 SDK 吗？

API 是 REST 接口：带 x-api-key header 的 GET 请求，任何有 HTTP 客户端的语言都可以调用。SDK 与示例页面提供 18 种语言和框架的现成示例，例如 Node.js、Next.js、Python、PHP、Laravel、Ruby、Go、Java、.NET 和 curl。已发布的官方 SDK 为 Python 版（pip install cpfhub）。其他语言请使用 HTTP 客户端。

如何取消订阅？

登录控制台 app.cpfhub.io，打开 Settings → Subscription，然后点击 Cancel plan。取消请求会立即处理，您可以继续使用套餐直至已付费周期结束。

CPFHub.io 提供技术支持吗？

提供。WhatsApp 自动化服务 24 小时在线，需要分析的问题会转交专业团队，在工作日 9:00 至 18:00（巴西利亚时间）处理。一般问题可以通过文档和 Playground 解决。