Perguntas Frequentes
Não encontrou o que procura? Entre em contato com o suporte.
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 SimplesO 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 RealDá 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 loteO 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 SLAA 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 RealComo 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çãoO 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 planosExiste 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éditosO 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 & LGPDA 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 completaQual é 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 usoExiste 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 exemplosComo 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.ioAtualizado em 2 de outubro de 2026