# FAQ - Documentação CPFHub.io

> Perguntas frequentes sobre a API de consulta de CPF da CPFHub.io: créditos, planos, limites, LGPD, erros e integração.

**URL:** https://www.cpfhub.io/documentacao/faq

---

# Perguntas Frequentes

Não encontrou o que procura? [Entre em contato com o suporte.](mailto:suporte@cpfhub.io) 

## O que a API do CPFHub.io retorna?

Na Consulta Simples (GET /cpf/{cpf}) e na consulta em lote (POST /cpf/bulk): nome completo, gênero e data de nascimento a partir do CPF. Na Consulta em Tempo Real (POST /cpf/realtime): nome, data de nascimento, ano do óbito (deathYear, inteiro ou null), situação cadastral na Receita Federal, código de controle e comprovante. Não retorna score, e-mail, nem dia ou mês do óbito.

[Ver Consulta Simples](https://www.cpfhub.io/documentacao/referencia/cpf) 

## O CPFHub.io consulta a Receita Federal ao vivo?

Depende da rota. GET /cpf/{cpf} responde a partir da nossa base, com nome, gênero e nascimento (1 crédito por CPF encontrado). POST /cpf/realtime consulta a Receita Federal no momento da chamada e devolve situação cadastral, ano do óbito (deathYear, inteiro ou null), código de controle e comprovante, mas exige a data de nascimento do titular. Custa 1,5 crédito somente na resposta HTTP 200; falhas, inclusive data de nascimento divergente (HTTP 422), não consomem crédito. As rotas são independentes: uma nunca cai para a outra.

[Ver Consulta em Tempo Real](https://www.cpfhub.io/documentacao/referencia/cpf-tempo-real) 

## Dá para validar CPF e nome no cadastro?

Sim: você envia o CPF, recebe nome e nascimento, e compara com o que o usuário digitou no seu fluxo (antifraude/cadastro). A regra de match fica no seu sistema.

## Tem consulta em lote?

Sim. POST /cpf/bulk é assíncrono e aceita até 10.000 CPFs por requisição; só CPFs encontrados consomem crédito. Útil para limpar base. Sem código, use a consulta em lote do dashboard (app.cpfhub.io/lote) com um arquivo CSV ou TXT.

[Ver consulta em lote](https://www.cpfhub.io/documentacao/referencia/lote) 

## O CPFHub.io faz KYC com selfie ou OCR?

Sim, com a Verificação de Identidade (KYC). Você cria um link, a pessoa faz a selfie com prova de vida e fotografa o documento (CNH, CNH Digital, RG ou passaporte), e a decisão chega por webhook. Cada verificação concluída custa 5 créditos por padrão. As consultas de CPF (simples, em lote e em tempo real) não usam selfie nem OCR.

## Qual o SLA?

Por plano, em /precos: Grátis 95%, Pro 99%, Corporativo 99,9%. Na Consulta em Lote, o tempo depende de quantos CPFs estão no envio.

[Ver planos e SLA](https://www.cpfhub.io/precos) 

A Consulta em Tempo Real devolve o ano de falecimento?

Sim. POST /cpf/realtime devolve deathYear, o ano do óbito, sempre presente como inteiro ou null. Não devolve dia nem mês. null aparece quando não há óbito registrado ou quando o valor recebido é inválido (não tem 4 dígitos, está fora do intervalo entre 1900 e o ano atual ou é anterior ao ano de nascimento).

[Ver Consulta em Tempo Real](https://www.cpfhub.io/documentacao/referencia/cpf-tempo-real) 

Como obtenho minha API Key?

Ao criar sua conta, uma API Key já é gerada automaticamente. Acesse app.cpfhub.io/api-keys para visualizá-la e copiá-la a qualquer momento. Se precisar, você pode gerar uma nova chave nessa mesma página.

[Ver documentação de autenticação](https://www.cpfhub.io/documentacao/referencia) 

O plano gratuito tem limite de consultas?

Sim. O plano gratuito inclui 50 créditos por mês e a API para de responder quando eles acabam. Planos pagos oferecem volumes maiores. Veja os planos disponíveis na página de preços.

[Ver planos](https://www.cpfhub.io/precos) 

Existe um ambiente sandbox para testes?

Os testes são feitos direto na API de produção: toda conta inclui 50 créditos gratuitos por mês. Use-os para testar sua integração em produção sem custo. CPFs não encontrados (404) e CPFs inválidos (400/422) nunca consomem créditos, então você pode testar cenários de erro à vontade.

[Ver limites e créditos](https://www.cpfhub.io/documentacao/referencia/rate-limits) 

O que acontece quando o CPF não é encontrado?

A API retorna HTTP 404 com error.message "CPF não encontrado na base de dados". Essa consulta não desconta créditos do seu plano: você só paga por consultas bem-sucedidas.

CPFs inválidos também consomem crédito?

Não. CPF com formato inválido (HTTP 400) ou dígitos verificadores errados (HTTP 422) não consome créditos. O motivo vem em error.message. Só consultas com CPF encontrado são cobradas: HTTP 200 na Consulta Simples e na Consulta em Tempo Real, ou found: true em cada item do lote.

A API armazena os CPFs consultados?

Sim. Cada consulta fica registrada com o CPF consultado, o resultado, a data e a conta que fez a consulta, inclusive quando o CPF não é encontrado. O registro serve para o histórico no dashboard, a cobrança de créditos, auditoria e prevenção a fraude. Na Consulta em Tempo Real, o comprovante HTML também fica guardado. Detalhes de retenção na página de compliance.

[Compliance & LGPD](https://www.cpfhub.io/documentacao/compliance) 

A API é compatível com a LGPD?

Sim. A API usa dados licenciados de provedores privados e fontes públicas oficiais, e não retorna informações sensíveis além do nome, gênero e data de nascimento (e, na consulta em tempo real, a situação cadastral e o ano do óbito na Receita Federal). O uso é permitido para finalidades legítimas, como verificação de identidade, validação de cadastro e prevenção de fraudes.

[Ver política completa](https://www.cpfhub.io/documentacao/compliance) 

Qual é o tempo de resposta?

A Consulta Simples responde a partir da nossa base, na mesma chamada (use timeout de cerca de 10 s). A Consulta em Tempo Real depende do tempo de resposta da Receita Federal (use timeout de pelo menos 60 s). Na Consulta em Lote, o tempo depende de quantos CPFs estão no envio. O SLA de disponibilidade varia por plano: Grátis 95%, Pro 99%, Corporativo 99,9%. Consulte /precos e o status em app.cpfhub.io/status.

Posso usar a API no frontend (browser)?

Tecnicamente sim, mas não é recomendado. Expor sua API Key no código client-side é um risco de segurança. Sempre faça as chamadas em um backend (servidor, serverless function, API Route no Next.js) e nunca inclua a chave em código público.

Existe limite de requisições por segundo ou por minuto?

Sim, por minuto e por API Key: por padrão, 30 requisições por minuto na Consulta Simples (cada envio de lote conta como 1) e 5 por minuto na Consulta em Tempo Real. Planos personalizados podem ter limites diferentes; confirme com o suporte da CPFHub.io em suporte@cpfhub.io. Acima do limite, a API responde HTTP 429 com o header Retry-After (segundos de espera), sem consumir crédito. Além disso, quando os créditos acabam em um plano sem cobrança de excedente, a API responde HTTP 403 com a mensagem "Limite de créditos excedido".

[Ver limites de uso](https://www.cpfhub.io/documentacao/referencia/rate-limits) 

Existe SDK para minha linguagem?

A API é REST: um GET com o header x-api-key, que funciona em qualquer linguagem com cliente HTTP. A página SDKs e exemplos traz exemplos prontos para 18 linguagens e frameworks, como Node.js, Next.js, Python, PHP, Laravel, Ruby, Go, Java, .NET e curl. O SDK oficial publicado é o de Python (pip install cpfhub); nas demais linguagens, use o cliente HTTP.

[Ver SDKs e exemplos](https://www.cpfhub.io/documentacao/sdks) 

Como cancelo minha assinatura?

Acesse o painel em app.cpfhub.io, vá em Configurações → Assinatura e clique em Cancelar plano. A solicitação de cancelamento é processada imediatamente; você mantém o acesso ao plano até o fim do período já pago.

O CPFHub.io tem suporte técnico?

Sim. O atendimento automatizado no WhatsApp funciona 24 horas, e casos que exigem análise seguem para a equipe especializada, em dias úteis, das 9h às 18h (horário de Brasília). Para dúvidas rápidas, a documentação e o playground cobrem a maioria dos casos.

Ainda com dúvidas?

Atendimento automatizado 24 horas no WhatsApp e equipe especializada em dias úteis, das 9h às 18h (horário de Brasília).

[suporte@cpfhub.io](mailto:suporte@cpfhub.io) 

Atualizado em 2 de outubro de 2026
