# Como consumir a API de CPF em C# usando HttpClient

> Aprenda a consumir a API de consulta de CPF em C# usando HttpClient. Guia completo com exemplos práticos de integração .NET.

**Publicado:** 04/10/2024
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/como-consumir-api-cpf-csharp-httpclient

---


Para consumir a API de CPF da CPFHub.io em C#, configure um `HttpClient` com `BaseAddress` apontando para `https://api.cpfhub.io/` e adicione o header `x-api-key` com sua chave de acesso. Uma chamada GET para `cpf/{numero}` retorna nome, data de nascimento e gênero em JSON, que você desserializa com `System.Text.Json`. O processo completo leva menos de 30 minutos em qualquer projeto .NET.

## Introdução

Consultar dados de CPF de forma programática é uma necessidade comum em aplicações brasileiras. O C# oferece o `HttpClient`, uma classe poderosa e flexível para realizar chamadas HTTP de maneira eficiente. Este guia mostra como integrar a API da CPFHub.io em projetos .NET utilizando boas práticas de consumo de APIs REST.

---

## Configurando o projeto .NET

Para começar, crie um novo projeto console ou utilize um projeto existente. O `HttpClient` já faz parte do namespace `System.Net.Http`, disponível nativamente no .NET.

```csharp
dotnet new console -n CpfConsulta
cd CpfConsulta
dotnet add package System.Text.Json
```

A estrutura do projeto será simples, com um único arquivo `Program.cs` para demonstrar a integração completa com a API.

---

## Modelando a resposta da API

Antes de realizar a chamada HTTP, é importante criar classes que representem a estrutura de resposta da API. Isso facilita a desserialização e garante tipagem forte no código.

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

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

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

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

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

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

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

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

---

## Realizando a consulta com HttpClient

Com os modelos prontos, podemos criar o método que realiza a consulta à API. Utilize `HttpClient` com o header `x-api-key` para autenticação.

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

public class CpfService
{
 private readonly HttpClient _httpClient;

 public CpfService(string apiKey)
 {
 _httpClient = new HttpClient
 {
 BaseAddress = new Uri("https://api.cpfhub.io/")
 };
 _httpClient.DefaultRequestHeaders.Add("x-api-key", apiKey);
 _httpClient.DefaultRequestHeaders.Accept.Add(
 new MediaTypeWithQualityHeaderValue("application/json"));
 }

 public async Task<CpfResponse?> ConsultarCpfAsync(string cpf)
 {
 var response = await _httpClient.GetAsync($"cpf/{cpf}");
 response.EnsureSuccessStatusCode();

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

---

## Tratamento de erros e boas práticas

Ao consumir APIs externas, é fundamental tratar erros de rede, timeouts e respostas inesperadas. A tabela abaixo resume os principais cenários de erro e como lidar com cada um.

| Código HTTP | Significado | Ação recomendada |
|---|---|---|
| 200 | Sucesso | Processar resposta normalmente |
| 400 | Requisição inválida | Verificar formato do CPF enviado |
| 401 | Não autorizado | Verificar a chave de API |
| 404 | CPF não encontrado | Informar ao usuário que não há dados |
| 500 | Erro interno do servidor | Tentar novamente após alguns segundos |

A API da CPFHub.io não retorna status 429: ao atingir o limite do plano, as consultas excedentes são cobradas a R$0,15 cada, sem interrupção do serviço.

```csharp
public async Task<CpfResponse?> ConsultarCpfComTratamentoAsync(string cpf)
{
 try
 {
 var response = await _httpClient.GetAsync($"cpf/{cpf}");

 if (!response.IsSuccessStatusCode)
 {
 Console.WriteLine($"Erro: {response.StatusCode}");
 return null;
 }

 var json = await response.Content.ReadAsStringAsync();
 return JsonSerializer.Deserialize<CpfResponse>(json);
 }
 catch (HttpRequestException ex)
 {
 Console.WriteLine($"Erro de rede: {ex.Message}");
 return null;
 }
 catch (TaskCanceledException)
 {
 Console.WriteLine("Timeout na requisição.");
 return null;
 }
}
```

---

## Exemplo completo de uso

Reunindo todos os componentes, o programa final fica assim:

```csharp
using System;
using System.Threading.Tasks;

class Program
{
 static async Task Main(string[] args)
 {
 var apiKey = "SUA_API_KEY";
 var service = new CpfService(apiKey);

 var resultado = await service.ConsultarCpfComTratamentoAsync("12345678900");

 if (resultado is { Success: true })
 {
 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("Não foi possível consultar o CPF.");
 }
 }
}
```

---

## Perguntas frequentes

### Devo usar uma instância compartilhada de HttpClient ou criar uma nova a cada requisição?
Use sempre uma instância compartilhada (singleton ou via `IHttpClientFactory`). Criar um novo `HttpClient` a cada chamada esgota as conexões de socket disponíveis, causando erros de `SocketException` sob carga. Em aplicações ASP.NET Core, registre o `CpfService` com `AddHttpClient<CpfService>()` no `Program.cs` para gerenciamento automático do ciclo de vida do cliente.

### Como configurar timeout adequado para a API de CPF em C#?
Configure o timeout diretamente na instância do `HttpClient` antes do primeiro uso: `_httpClient.Timeout = TimeSpan.FromSeconds(15)`. A latência típica da API da CPFHub.io é de aproximadamente 900ms, então 10 a 15 segundos é um valor conservador adequado. Capte `TaskCanceledException` para tratar timeouts de forma amigável ao usuário.

### O System.Text.Json é suficiente para desserializar a resposta da CPFHub.io?
Sim. A resposta da API segue JSON padrão com campos em camelCase (`name`, `birthDate`, `nameUpper`). Use `[JsonPropertyName]` nos modelos para mapear corretamente os campos, como mostrado nos exemplos deste artigo. O `System.Text.Json` é mais rápido que `Newtonsoft.Json` na maioria dos cenários e não exige dependência adicional no .NET 6+. Para referência, consulte a [documentação oficial do System.Text.Json](https://learn.microsoft.com/pt-br/dotnet/standard/serialization/system-text-json/overview).

### Como injetar a API key de forma segura em uma aplicação .NET?
Nunca coloque a chave diretamente no código-fonte. Em desenvolvimento, use `dotnet user-secrets` para armazenar a chave localmente. Em produção, leia-a de variáveis de ambiente ou de um serviço como Azure Key Vault ou AWS Secrets Manager. No `Program.cs`, acesse via `builder.Configuration["CpfHub:ApiKey"]` e injete no serviço pelo construtor.

### 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

Consumir a API de CPF da CPFHub.io em C# com `HttpClient` é um processo direto e eficiente. Com as classes de modelo, tratamento de erros adequado e boas práticas de uso do `HttpClient`, você consegue integrar a consulta de CPF em qualquer aplicação .NET com poucas linhas de código.

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 na sua aplicação .NET hoje mesmo.