Como validar CPF em ASP.NET Core Web API

Para integrar validação de CPF em uma ASP.NET Core Web API, crie um serviço tipado com IHttpClientFactory, registre a API key via appsettings.json e exponha um controller que consulta a CPFHub.io e devolve os dados do titular ao cliente. A abordagem com injeção de dependência centraliza a lógica de verificação, facilita testes unitários e garante que todos os endpoints consumam CPFs já validados. A latência da consulta é de aproximadamente 900ms, adequada para fluxos de cadastro e onboarding.

Introdução

O ASP.NET Core é uma das plataformas mais utilizadas para construção de Web APIs corporativas. Em aplicações que atendem o mercado brasileiro, a validação de CPF é um requisito recorrente em endpoints de cadastro de usuários, onboarding de clientes e processamento de transações financeiras.

Integrar a validação de CPF diretamente na Web API permite centralizar a lógica de verificação em um único ponto, garantindo que todos os serviços que consomem a API trabalhem com dados validados. Este guia mostra como implementar essa integração em uma ASP.NET Core Web API utilizando a API da CPFHub.io com HttpClient tipado, injeção de dependência e tratamento de erros adequado.

Pré-requisitos

.NET 8 SDK -- Instalado e configurado.
Conta na CPFHub.io -- Para obter a chave de API (50 consultas/mês no plano gratuito).

Criando o projeto

dotnet new webapi -n CpfValidationApi
cd CpfValidationApi

Configuração inicial

appsettings.json

Adicione a configuração da chave de API:

{
    "CpfHub": {
    "ApiKey": "SUA_CHAVE_DE_API",
    "BaseUrl": "https://api.cpfhub.io/"
    }
}

Classe de configuração

public class CpfHubSettings
{
    public string ApiKey { get; set; } = string.Empty;
    public string BaseUrl { get; set; } = string.Empty;
}

Modelos de dados

using System.Text.Json.Serialization;

public class CpfResponse
{
    [JsonPropertyName("success")]
    public bool Success { get; set; }

    [JsonPropertyName("data")]
    public CpfData? Data { get; set; }
}

public class CpfData
{
    [JsonPropertyName("cpf")]
    public string Cpf { get; set; } = string.Empty;

    [JsonPropertyName("name")]
    public string Name { get; set; } = string.Empty;

    [JsonPropertyName("nameUpper")]
    public string NameUpper { get; set; } = string.Empty;

    [JsonPropertyName("gender")]
    public string Gender { get; set; } = string.Empty;

    [JsonPropertyName("birthDate")]
    public string BirthDate { get; set; } = string.Empty;

    [JsonPropertyName("day")]
    public int Day { get; set; }

    [JsonPropertyName("month")]
    public int Month { get; set; }

    [JsonPropertyName("year")]
    public int Year { get; set; }
}

Criando o serviço de consulta

Implemente a interface e o serviço para consultar a API:

public interface ICpfValidationService
{
    Task<CpfData?> ValidarCpfAsync(string cpf);
}

public class CpfValidationService : ICpfValidationService
{
    private readonly HttpClient _httpClient;
    private readonly ILogger<CpfValidationService> _logger;

    public CpfValidationService(
    HttpClient httpClient,
    ILogger<CpfValidationService> logger)
    {
    _httpClient = httpClient;
    _logger = logger;
    }

    public async Task<CpfData?> ValidarCpfAsync(string cpf)
    {
    var cpfLimpo = new string(cpf.Where(char.IsDigit).ToArray());

    if (cpfLimpo.Length != 11)
    {
    _logger.LogWarning("CPF inválido: {Cpf}", cpfLimpo);
    return null;
    }

    try
    {
    var response = await _httpClient.GetAsync($"cpf/{cpfLimpo}");
    response.EnsureSuccessStatusCode();

    var resultado = await response.Content
    .ReadFromJsonAsync<CpfResponse>();

    if (resultado?.Success == true)
    {
    _logger.LogInformation(
    "CPF {Cpf} validado com sucesso.", cpfLimpo);
    return resultado.Data;
    }

    _logger.LogWarning("CPF {Cpf} não encontrado.", cpfLimpo);
    return null;
    }
    catch (TaskCanceledException)
    {
    _logger.LogError("Timeout ao consultar CPF: {Cpf}", cpfLimpo);
    throw;
    }
    catch (HttpRequestException ex)
    {
    _logger.LogError(ex,
    "Erro ao consultar CPF: {Cpf}", cpfLimpo);
    throw;
    }
    }
}

Registrando o serviço no Program.cs

using System.Net.Http.Headers;

var builder = WebApplication.CreateBuilder(args);

builder.Services.Configure<CpfHubSettings>(
    builder.Configuration.GetSection("CpfHub"));

builder.Services.AddHttpClient<ICpfValidationService, CpfValidationService>(
    (serviceProvider, client) =>
    {
    var settings = builder.Configuration
    .GetSection("CpfHub").Get<CpfHubSettings>();

    client.BaseAddress = new Uri(settings?.BaseUrl
    ?? "https://api.cpfhub.io/");
    client.Timeout = TimeSpan.FromSeconds(10);
    client.DefaultRequestHeaders.Add("x-api-key",
    settings?.ApiKey ?? "");
    client.DefaultRequestHeaders.Accept.Add(
    new MediaTypeWithQualityHeaderValue("application/json"));
    });

builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();
app.Run();

Criando o controller

using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/[controller]")]
public class CpfController : ControllerBase
{
    private readonly ICpfValidationService _cpfService;

    public CpfController(ICpfValidationService cpfService)
    {
    _cpfService = cpfService;
    }

    [HttpGet("{cpf}")]
    public async Task<IActionResult> Validar(string cpf)
    {
    if (string.IsNullOrWhiteSpace(cpf))
    {
    return BadRequest(new { error = "CPF não informado." });
    }

    try
    {
    var resultado = await _cpfService.ValidarCpfAsync(cpf);

    if (resultado != null)
    {
    return Ok(new
    {
    valido = true,
    dados = resultado
    });
    }

    return NotFound(new
    {
    valido = false,
    error = "CPF não encontrado."
    });
    }
    catch (TaskCanceledException)
    {
    return StatusCode(504, new
    {
    error = "Tempo limite excedido."
    });
    }
    catch (Exception)
    {
    return StatusCode(500, new
    {
    error = "Erro interno ao validar CPF."
    });
    }
    }
}

Testando a API

Inicie a aplicação e teste com cURL:

curl -X GET https://localhost:5001/api/cpf/12345678900 \
    -H "Accept: application/json" \
    --max-time 10

A resposta da API da CPFHub.io que alimenta o endpoint:

{
    "success": true,
    "data": {
    "cpf": "12345678900",
    "name": "João da Silva",
    "nameUpper": "JOÃO DA SILVA",
    "gender": "M",
    "birthDate": "15/06/1990",
    "day": 15,
    "month": 6,
    "year": 1990
    }
}

Adicionando validação com FluentValidation

Para projetos que utilizam FluentValidation, é possível criar uma regra customizada:

using FluentValidation;

public class CadastroCLienteValidator : AbstractValidator<CadastroClienteRequest>
{
    public CadastroCLienteValidator()
    {
    RuleFor(x => x.Cpf)
    .NotEmpty().WithMessage("CPF é obrigatório.")
    .Must(CpfValido).WithMessage("CPF sintaticamente inválido.");
    }

    private bool CpfValido(string cpf)
    {
    var cpfLimpo = new string(cpf.Where(char.IsDigit).ToArray());
    if (cpfLimpo.Length != 11) return false;
    if (cpfLimpo.Distinct().Count() == 1) return false;
    return true;
    }
}

Boas práticas

Injeção de dependência -- Registre o HttpClient com AddHttpClient<T> para gerenciamento correto do ciclo de vida.
Timeout -- Configure timeout no HttpClient e trate TaskCanceledException.
Logging -- Registre consultas realizadas para auditoria e diagnóstico.
Chave de API -- Armazene em variáveis de ambiente ou Azure Key Vault, nunca em código-fonte.
Excedente de consultas -- A CPFHub.io não bloqueia requisições ao atingir o limite mensal. O plano gratuito oferece 50 consultas/mês; cada consulta extra custa R$0,15. O plano Pro inclui 1.000 consultas por R$149/mês.

Perguntas frequentes

Como armazenar a API key da CPFHub.io de forma segura em ASP.NET Core?

A prática recomendada é usar variáveis de ambiente em produção e o Secret Manager do .NET em desenvolvimento. Nunca armazene a chave diretamente no appsettings.json versionado. Em ambientes Azure, use o Azure Key Vault integrado ao IConfiguration para recuperar a chave em tempo de execução sem expô-la no repositório.

A API da CPFHub.io pode retornar HTTP 429 e travar o fluxo de cadastro?

Não. A CPFHub.io nunca retorna HTTP 429 nem bloqueia requisições. Ao superar o limite mensal do plano, cada consulta adicional é cobrada automaticamente a R$0,15 — o serviço continua respondendo normalmente. Não é necessário implementar lógica de retry por bloqueio de rate limit.

Como testar o serviço de validação de CPF sem consumir consultas reais?

Use a interface ICpfValidationService para criar um mock nos testes unitários. Injete o mock via construtor no controller e simule diferentes retornos (CPF encontrado, não encontrado, timeout). Para testes de integração, configure um HttpMessageHandler fake que intercepta as chamadas ao HttpClient e retorna respostas pré-definidas sem acessar a API real.

Qual o impacto de latência da consulta à CPFHub.io em uma Web API ASP.NET Core?

A latência da API é de aproximadamente 900ms. Em fluxos de cadastro e onboarding, esse tempo é aceitável. Para cenários onde a latência precisa ser menor, implemente cache em memória (IMemoryCache) para CPFs já consultados na mesma sessão, ou use cache distribuído (Redis) para evitar consultas repetidas ao mesmo CPF em múltiplas requisições.

Conclusão

Integrar a validação de CPF em uma ASP.NET Core Web API é uma prática essencial para aplicações que atendem o mercado brasileiro. Com a API da CPFHub.io, HttpClient tipado e injeção de dependência, a implementação fica limpa, testável e fácil de manter em produção.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e adicione validação de CPF à sua ASP.NET Core Web API com o código deste guia.

CPFHub.io

Pronto para integrar a API?

50 consultas gratuitas para testar agora. Sem cartão de crédito. Acesso imediato à documentação.

Começar grátis Ver 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.

Como integrar validação de CPF em ASP.NET Core Web API