Como validar CPF em tempo real usando .NET e APIs REST

Aprenda a validar CPF em tempo real em aplicações .NET consumindo APIs REST com feedback instantâneo ao usuário.

Redação CPFHub.io
Redação CPFHub.io
··6 min de leitura
Como validar CPF em tempo real usando .NET e APIs REST

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);
    }
}
EtapaDescriçãoTempo Estimado
Validação localVerifica dígitos verificadores< 1ms
Chamada à APIConsulta dados na base do CPFHub100-300ms
Resposta totalResultado 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.

Redação CPFHub.io

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.

WhatsAppFale conosco via WhatsApp