# Como consumir API de CPF em C# com HttpClient e .NET 8

> Aprenda a consumir a API de consulta de CPF em C# usando HttpClient no .NET 8. Guia completo com exemplos de código e boas práticas.

**Publicado:** 22/11/2024
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/como-consumir-api-de-cpf-em-csharp-com-httpclient-e-dotnet-8

---


Para consumir a API de CPF da CPFHub.io em C# com .NET 8, você faz uma requisição GET para `https://api.cpfhub.io/cpf/{CPF}` com o header `x-api-key` e deserializa a resposta JSON com `System.Text.Json`. Em produção, use `IHttpClientFactory` para evitar socket exhaustion e Polly para retry com backoff exponencial em erros transitórios.

## Introdução

O C# com .NET 8 oferece um ecossistema robusto para desenvolvimento de aplicações corporativas, web APIs e serviços que precisam validar dados cadastrais de pessoas físicas. A validação de CPF via API é uma prática essencial para fintechs, e-commerces, ERPs e qualquer sistema que opere no mercado brasileiro.

---

## Pré-requisitos

* **.NET 8 SDK** — Instalado e configurado.
* **Visual Studio 2022** ou **VS Code** com extensão C#.
* **Conta na CPFHub.io** — Para obter a chave de API. O plano gratuito oferece 50 consultas/mês.

### Criando o projeto

```bash
dotnet new console -n CpfHubDemo
cd CpfHubDemo
```

---

## Modelando a resposta da API

Crie as classes que representam a resposta JSON:

```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; }
}
```

A resposta da API segue este formato:

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

---

## Implementação básica com HttpClient

O exemplo mais direto para uma aplicação console:

```csharp
using System.Net.Http.Headers;
using System.Text.Json;

var apiKey = "SUA_CHAVE_DE_API";
var cpf = "12345678900";
var url = $"https://api.cpfhub.io/cpf/{cpf}";

using var client = new HttpClient();
client.Timeout = TimeSpan.FromSeconds(10);
client.DefaultRequestHeaders.Add("x-api-key", apiKey);
client.DefaultRequestHeaders.Accept.Add(
 new MediaTypeWithQualityHeaderValue("application/json"));

try
{
 var response = await client.GetAsync(url);
 response.EnsureSuccessStatusCode();

 var json = await response.Content.ReadAsStringAsync();
 var resultado = JsonSerializer.Deserialize<CpfResponse>(json);

 if (resultado?.Success == true && resultado.Data != null)
 {
 Console.WriteLine($"Nome: {resultado.Data.Name}");
 Console.WriteLine($"CPF: {resultado.Data.Cpf}");
 Console.WriteLine($"Nascimento: {resultado.Data.BirthDate}");
 Console.WriteLine($"Gênero: {resultado.Data.Gender}");
 }
 else
 {
 Console.WriteLine("CPF não encontrado.");
 }
}
catch (TaskCanceledException)
{
 Console.WriteLine("A requisição excedeu o tempo limite.");
}
catch (HttpRequestException ex)
{
 Console.WriteLine($"Erro na requisição: {ex.Message}");
}
```

---

## Implementação com IHttpClientFactory (recomendada)

Para aplicações de produção, o uso de `IHttpClientFactory` evita problemas de exaustão de sockets e permite configuração centralizada. Abaixo está a implementação usando injeção de dependência.

### Configuração no Program.cs

```csharp
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.AddHttpClient("CpfHub", client =>
{
 client.BaseAddress = new Uri("https://api.cpfhub.io/");
 client.Timeout = TimeSpan.FromSeconds(10);
 client.DefaultRequestHeaders.Add("x-api-key",
 builder.Configuration["CpfHub:ApiKey"] ?? "");
 client.DefaultRequestHeaders.Accept.Add(
 new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue(
 "application/json"));
});

builder.Services.AddTransient<CpfService>();

var app = builder.Build();

var service = app.Services.GetRequiredService<CpfService>();
var resultado = await service.ConsultarAsync("12345678900");

if (resultado != null)
{
 Console.WriteLine($"Nome: {resultado.Name}");
 Console.WriteLine($"Nascimento: {resultado.BirthDate}");
}
```

### Classe CpfService

```csharp
using System.Text.Json;

public class CpfService
{
 private readonly IHttpClientFactory _httpClientFactory;

 public CpfService(IHttpClientFactory httpClientFactory)
 {
 _httpClientFactory = httpClientFactory;
 }

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

 if (cpfLimpo.Length != 11)
 {
 Console.WriteLine("CPF inválido. Informe 11 dígitos.");
 return null;
 }

 var client = _httpClientFactory.CreateClient("CpfHub");

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

 var json = await response.Content.ReadAsStringAsync();
 var resultado = JsonSerializer.Deserialize<CpfResponse>(json);

 if (resultado?.Success == true)
 {
 return resultado.Data;
 }

 return null;
 }
 catch (TaskCanceledException)
 {
 Console.WriteLine("Timeout na consulta de CPF.");
 return null;
 }
 catch (HttpRequestException ex)
 {
 Console.WriteLine($"Erro: {ex.Message}");
 return null;
 }
 }
}
```

### Configuração no appsettings.json

```json
{
 "CpfHub": {
 "ApiKey": "SUA_CHAVE_DE_API"
 }
}
```

---

## Adicionando resiliência com Polly

Para operações críticas, adicione políticas de retry com a biblioteca Polly. A documentação do [Microsoft.Extensions.Http.Polly](https://learn.microsoft.com/pt-br/dotnet/core/resilience/http-resilience) explica as opções disponíveis para .NET 8.

```bash
dotnet add package Microsoft.Extensions.Http.Polly
```

```csharp
builder.Services.AddHttpClient("CpfHub", client =>
{
 client.BaseAddress = new Uri("https://api.cpfhub.io/");
 client.Timeout = TimeSpan.FromSeconds(10);
 client.DefaultRequestHeaders.Add("x-api-key",
 builder.Configuration["CpfHub:ApiKey"] ?? "");
 client.DefaultRequestHeaders.Accept.Add(
 new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue(
 "application/json"));
})
.AddTransientHttpErrorPolicy(policy =>
 policy.WaitAndRetryAsync(3, attempt =>
 TimeSpan.FromSeconds(Math.Pow(2, attempt))
 )
);
```

Essa configuração faz até 3 tentativas com backoff exponencial (2s, 4s, 8s) em caso de erros transitórios.

---

## Boas práticas

* **IHttpClientFactory** — Sempre prefira sobre `new HttpClient()` para evitar problemas de socket exhaustion.

* **Timeout** — Configure timeout no HttpClient para evitar travamentos.

* **Chave de API** — Armazene em `appsettings.json`, variáveis de ambiente ou Azure Key Vault. Nunca no código-fonte.

* **Plano gratuito** — Oferece 50 consultas/mês sem cartão de crédito. O plano Pro oferece 1.000 consultas mensais por R$149/mês, com excedente cobrado a R$0,15/consulta sem bloqueio.

* **Resiliência** — Use Polly para retry e circuit breaker em ambientes de produção.

---

## Perguntas frequentes

### Por que usar IHttpClientFactory em vez de instanciar HttpClient diretamente?

Instanciar `new HttpClient()` a cada requisição esgota os sockets disponíveis do sistema operacional rapidamente, causando falhas intermitentes em produção — um problema clássico chamado socket exhaustion. O `IHttpClientFactory` gerencia um pool de conexões HTTP reutilizáveis, resolvendo isso de forma transparente. Para aplicações que consultam a API de CPF com frequência, o factory é a única abordagem recomendada pelo [padrão oficial da Microsoft](https://learn.microsoft.com/pt-br/dotnet/core/resilience/http-resilience).

### A API da CPFHub.io bloqueia requisições quando o limite do plano gratuito é atingido?

Não. A API da CPFHub.io nunca bloqueia requisições nem retorna erro de limite atingido. Ao ultrapassar as 50 consultas mensais do plano gratuito, cada consulta adicional é cobrada automaticamente a R$0,15 — sem interrupção do serviço. Isso simplifica o código em C#: não é necessário tratar nenhum estado de bloqueio.

### Como armazenar a API key com segurança em aplicações .NET 8?

Em desenvolvimento, use `appsettings.Development.json` (não versionado no Git) ou as variáveis de ambiente do sistema. Em produção, prefira Azure Key Vault, AWS Secrets Manager ou variáveis de ambiente injetadas pelo orquestrador (Kubernetes Secrets, App Service Configuration). Nunca inclua a chave no código-fonte ou em arquivos commitados.

### Polly é obrigatório para consumir a API de CPF em .NET 8?

Não é obrigatório, mas é altamente recomendado para produção. Sem Polly, uma falha transitória de rede retorna imediatamente um erro ao usuário. Com Polly configurando retry com backoff exponencial, a aplicação tenta novamente de forma automática em erros 5xx e timeouts, aumentando a resiliência sem alterar a lógica de negócio.

### Leia também

- [Como consumir a API de CPF em C# usando HttpClient](https://cpfhub.io/blog/como-consumir-api-cpf-csharp-httpclient)
- [Como usar Polly para retry e circuit breaker ao consultar CPF em .NET](https://cpfhub.io/blog/como-usar-polly-retry-circuit-breaker-consultar-cpf-dotnet)
- [Como criar um serviço de validação de CPF em .NET com injeção de dependência](https://cpfhub.io/blog/como-criar-servico-validacao-cpf-dotnet-injecao-dependencia)
- [Como validar CPF em tempo real usando .NET e APIs REST](https://cpfhub.io/blog/como-validar-cpf-tempo-real-dotnet-apis-rest)

---

## Conclusão

Consumir a API de consulta de CPF da CPFHub.io em C# com .NET 8 é direto usando `HttpClient`, e seguro em produção com `IHttpClientFactory` e Polly para resiliência. Com poucos minutos de configuração, sua aplicação .NET passa a validar CPFs com dados reais, reduzindo fraudes e erros de cadastro.

Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e integre a validação de CPF ao seu projeto .NET 8 hoje mesmo.