使用限制

CPFHub.io API 有两类限制：

• 积分： 每次成功查询都会从您的套餐额度中扣除积分。
• 每分钟请求数： 每种查询类型每分钟的调用上限，用于保障 API 稳定性。

下方费用为默认值。您套餐的具体费用和超额用量规则请在控制台查看。默认限制为标准查询 30 次/分钟（每次批量提交计为 1 次），实时查询 5 次/分钟。定制套餐的限制可能不同，请向 CPFHub.io 支持团队确认。超出限制时，API 返回 429 和 Retry-After 请求头。您的余额和当前套餐可通过 GET /quota 查看，该接口不消耗积分。

各套餐积分

网站上的 Pro 版按用量档位选择，每个档位对应上表中的一个套餐。GET /quota 中的名称是 API 返回的葡萄牙语名称。定制套餐可能有单独的规则，请在控制台查看您账户的条款。价格见 cpfhub.io/precos。

积分何时续期： 付费套餐在订阅的每个计费周期开始时续期。免费版在每月 1 日（UTC）续期。余额属于整个账户，所有密钥合计计算。

各查询的费用

以上为默认费用。您套餐的具体费用请在控制台查看。

积分用完

在不支持超额计费的套餐（例如免费版）中，余额不足以支付查询费用时，API 返回 403：

• CNPJ 查询与标准查询使用同一额度，费用相同。
• 批量查询（CPF 或 CNPJ）提交前，余额必须足以覆盖列表中所有有效证件号。余额不足时不扣任何积分。
• 余额为 1 个积分时仍可进行标准查询，但不能进行实时查询（1.5 个积分）。
• 请用 GET /quota 跟踪余额，该接口在积分为零时也可使用，且不消耗积分。

每分钟限制

以上为默认限制。定制套餐的限制可能不同，请向 CPFHub.io 支持团队确认。每次批量提交计为 1 次标准查询请求。超出限制时，API 返回 429 和 Retry-After 请求头。

• 限制按 API 密钥和查询类型分别计算。CPF 标准查询和 CNPJ 查询属于同一类型：同一分钟内查询 20 个 CPF 和 10 个 CNPJ 即已达到 30 次。
• 所有请求都计数，包括返回 404 的请求。
• 计数在每个整分钟开始时重置。
• GET /cpf/bulk/{jobId} 和 GET /quota 不计入限制。

超出限制时，API 返回 429 和 Retry-After 请求头（距离解除限制的秒数），且不消耗积分：

HTTP/1.1 429 Too Many Requests
Retry-After: 18

{
  "success": false,
  "data": null,
  "error": {
    "message": "Limite de requisições por minuto excedido. Tente novamente em 18 segundos."
  }
}

message 文本为葡萄牙语（超出每分钟请求限制，请 18 秒后重试）。请等待 Retry-After 给出的时间后重复同一请求。如需查询大量 CPF，请使用批量查询：一次提交最多处理 10,000 个 CPF，只计为一次请求。

重复查询保护

仅适用于标准查询（GET /cpf/{cpf}）：如果同一密钥在 10 分钟内查询同一 CPF 达 20 次，该 CPF 的后续查询会被临时封锁并返回 429（信息："Este CPF foi consultado repetidas vezes em sequência pela mesma chave. Novas consultas dele estão bloqueadas temporariamente para não consumir seus créditos. Verifique se sua integração está em loop. As consultas de outros CPFs seguem normais."）。该保护不适用于实时查询、CNPJ 查询和批量查询。如需重复使用某个 CPF 的结果，请将其保存在您的系统中，不要重复查询。

公开 KYC 端点的 IP 限制

身份验证链接令牌使用的公开端点还有按 IP 计算的限制。超出后 API 返回 429。

批量限制

POST /cpf/bulk 每次请求最多接受 10,000 个 CPF。数量更大时，请拆分为多次调用。详见批量查询。

POST /cnpj/bulk 每次请求最多接受 10,000 个 CNPJ，并限制每个客户的待处理批次数（超出时返回 429 和 Retry-After: 60）。详见 CNPJ 批量查询。

实时查询不支持批量。

大批量使用

如果您更倾向于逐个调用，请限制并发数并遵守 429：

import asyncio, os
import httpx

CONCURRENCY = 5

async def process_batch(cpf_list: list[str]):
    semaphore = asyncio.Semaphore(CONCURRENCY)

    async with httpx.AsyncClient(
        base_url='https://api.cpfhub.io',
        headers={'x-api-key': os.environ['CPFHUB_API_KEY']},
        timeout=10,
    ) as client:
        async def lookup_one(cpf: str):
            async with semaphore:
                for _ in range(3):
                    res = await client.get(f'/cpf/{cpf}')
                    if res.status_code != 429:
                        return res.status_code, res.json()
                    await asyncio.sleep(int(res.headers.get('retry-after', '5')))
                return res.status_code, res.json()

        return await asyncio.gather(*[lookup_one(cpf) for cpf in cpf_list])

实时查询请设置至少 60 秒的超时。

更大用量

如果每月查询量超过 10,000 次，或需要更高的每分钟限制、协商条款或专属 SLA，请与我们联系，了解企业版。

联系销售 →

更新于 2026 年 10 月 15 日