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

> Aprenda a integrar a validação de CPF via API em ASP.NET Core Web API com exemplos completos usando HttpClient, middleware e injeção de dependência.

**Publicado:** 07/12/2024
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/como-integrar-validacao-de-cpf-em-aspnet-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**](https://www.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

```bash
dotnet new webapi -n CpfValidationApi
cd CpfValidationApi
```

---

## Configuração inicial

### appsettings.json

Adicione a configuração da chave de API:

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

### Classe de configuração

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

---

## Modelos de dados

```csharp
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:

```csharp
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

```csharp
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

```csharp
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:

```bash
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:

```json
{
 "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:

```csharp
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](https://learn.microsoft.com/pt-br/azure/key-vault/general/overview), 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](https://learn.microsoft.com/pt-br/aspnet/core/security/app-secrets) 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.

### Leia também

- [Como validar CPF no frontend com React e API REST](https://cpfhub.io/blog/como-validar-cpf-no-frontend-com-react-e-api-rest)
- [SLA de API de CPF: níveis de disponibilidade e o que exigir do seu provedor](https://cpfhub.io/blog/sla-api-cpf-niveis-disponibilidade)
- [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos)
- [10 erros mais comuns ao integrar uma API de CPF e como evitá-los](https://cpfhub.io/blog/10-erros-mais-comuns-ao-integrar-uma-api-de-cpf)

---

## 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**](https://www.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](https://www.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.