Para validar CPF em tempo real em aplicações .NET, combine uma validação local dos dígitos verificadores com uma chamada REST à API do CPFHub.io usando HttpClient. A resposta retorna nome, data de nascimento e gênero do titular em cerca de 900ms, permitindo feedback instantâneo durante o preenchimento de formulários. O processo envolve três camadas: validação de formato, consulta à API e, opcionalmente, um cache em memória para CPFs já verificados.
Introdução
Validar o CPF em tempo real durante o preenchimento de formulários melhora significativamente a experiência do usuário e reduz erros de cadastro. A abordagem recomendada é combinar validação local dos dígitos verificadores com a consulta à API do CPFHub.io para confirmar os dados em tempo real usando .NET.
Validação local do CPF
Antes de fazer uma chamada à API, é eficiente validar o formato e os dígitos verificadores do CPF localmente. Isso evita requisições desnecessárias.
public static class CpfValidator
{
public static bool ValidarDigitos(string cpf)
{
cpf = new string(cpf.Where(char.IsDigit).ToArray());
if (cpf.Length != 11 || cpf.Distinct().Count() == 1)
return false;
int[] multiplicadores1 = { 10, 9, 8, 7, 6, 5, 4, 3, 2 };
int[] multiplicadores2 = { 11, 10, 9, 8, 7, 6, 5, 4, 3, 2 };
string tempCpf = cpf[..9];
int soma = tempCpf.Select((c, i) => (c - '0') * multiplicadores1[i]).Sum();
int resto = soma % 11;
int digito1 = resto < 2 ? 0 : 11 - resto;
tempCpf += digito1;
soma = tempCpf.Select((c, i) => (c - '0') * multiplicadores2[i]).Sum();
resto = soma % 11;
int digito2 = resto < 2 ? 0 : 11 - resto;
return cpf.EndsWith($"{digito1}{digito2}");
}
}
Serviço de validação em tempo real
Combine a validação local com a consulta à API para criar um serviço completo de validação em tempo real.
public class ValidacaoCpfResult
{
public bool FormatoValido { get; set; }
public bool EncontradoNaBase { get; set; }
public string? Nome { get; set; }
public string? DataNascimento { get; set; }
public string? Mensagem { get; set; }
}
public class CpfValidationService
{
private readonly HttpClient _httpClient;
public CpfValidationService(HttpClient httpClient)
{
_httpClient = httpClient;
}
public async Task<ValidacaoCpfResult> ValidarEmTempoRealAsync(string cpf)
{
var result = new ValidacaoCpfResult();
if (!CpfValidator.ValidarDigitos(cpf))
{
result.Mensagem = "CPF com formato inválido";
return result;
}
result.FormatoValido = true;
try
{
var response = await _httpClient.GetAsync($"cpf/{cpf}");
if (response.IsSuccessStatusCode)
{
var dados = await response.Content.ReadFromJsonAsync<CpfResponse>();
if (dados is { Success: true })
{
result.EncontradoNaBase = true;
result.Nome = dados.Data.Name;
result.DataNascimento = dados.Data.BirthDate;
result.Mensagem = "CPF válido e encontrado";
}
}
else
{
result.Mensagem = "CPF válido, mas não encontrado na base";
}
}
catch (Exception ex)
{
result.Mensagem = $"Erro na consulta: {ex.Message}";
}
return result;
}
}
Expondo a validação via endpoint
Crie um endpoint que recebe o CPF e retorna o resultado da validação imediatamente.
[ApiController]
[Route("api/[controller]")]
public class ValidacaoController : ControllerBase
{
private readonly CpfValidationService _validationService;
public ValidacaoController(CpfValidationService validationService)
{
_validationService = validationService;
}
[HttpGet("validar/{cpf}")]
public async Task<IActionResult> Validar(string cpf)
{
var resultado = await _validationService.ValidarEmTempoRealAsync(cpf);
return Ok(resultado);
}
}
| Etapa | Descrição | Tempo Estimado |
|---|---|---|
| Validação local | Verifica dígitos verificadores | < 1ms |
| Chamada à API | Consulta dados na base do CPFHub | 100-300ms |
| Resposta total | Resultado completo ao usuário | ~300ms |
Implementando cache para performance
Para evitar chamadas repetidas à API com o mesmo CPF, implemente um cache em memória.
public class CachedCpfValidationService
{
private readonly CpfValidationService _inner;
private readonly IMemoryCache _cache;
public CachedCpfValidationService(
CpfValidationService inner,
IMemoryCache cache)
{
_inner = inner;
_cache = cache;
}
public async Task<ValidacaoCpfResult> ValidarAsync(string cpf)
{
var cacheKey = $"cpf_validacao_{cpf}";
if (_cache.TryGetValue(cacheKey, out ValidacaoCpfResult? cached))
return cached!;
var resultado = await _inner.ValidarEmTempoRealAsync(cpf);
var options = new MemoryCacheEntryOptions()
.SetAbsoluteExpiration(TimeSpan.FromMinutes(10));
_cache.Set(cacheKey, resultado, options);
return resultado;
}
}
Perguntas frequentes
O que é necessário para implementar validação de CPF em tempo real com .NET?
Para validar CPF em tempo real com .NET, você precisa de uma instância configurada de HttpClient apontando para https://api.cpfhub.io/, a API key no header x-api-key e uma classe de serviço que orquestre a validação local dos dígitos verificadores antes de cada chamada à API. O padrão recomendado é registrar o cliente no contêiner de DI via AddHttpClient<ICpfApiClient, CpfApiClient>.
A API CPFHub.io funciona para todos os volumes de consulta?
Sim. O plano gratuito oferece 50 consultas por mês sem cartão de crédito — ideal para testes e projetos pequenos. Para volumes maiores, o plano Pro inclui 1.000 consultas mensais por R$149. Se o limite for ultrapassado, a API não bloqueia: cobra R$0,15 por consulta adicional.
Como garantir conformidade com a LGPD ao usar uma API de CPF em .NET?
Use o CPF apenas para a finalidade declarada ao titular, armazene apenas o necessário (não guarde o CPF cru se um token bastar), implemente controle de acesso aos logs de consulta e documente a base legal para o tratamento. A ANPD orienta que dados de identificação devem ser tratados com o princípio da necessidade.
Vale a pena implementar cache local de validações de CPF?
Sim, especialmente em fluxos de onboarding com múltiplas etapas onde o mesmo CPF pode ser revalidado. Um IMemoryCache com expiração de 10 a 30 minutos elimina chamadas redundantes à API sem comprometer a confiabilidade dos dados. Para cenários de alta concorrência, considere usar IDistributedCache com Redis para compartilhar o cache entre instâncias.
Conclusão
A validação de CPF em tempo real com .NET combina eficiência local com a riqueza de dados da API. Ao utilizar validação em duas camadas — local e remota — você garante respostas rápidas e dados confiáveis.
Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e adicione validação de CPF em tempo real à sua aplicação .NET em menos de 30 minutos.
CPFHub.io
Pronto para integrar a API?
50 consultas gratuitas para testar agora. Sem cartão de crédito. Acesso imediato à documentação.
Sobre a redação
Redação CPFHub.io
Time editorial especializado em APIs de CPF, identidade digital e compliance no mercado brasileiro. Produzimos guias técnicos, análises regulatórias e tutoriais sobre LGPD e KYC para desenvolvedores e líderes de produto.



