# Como integrar a API de CPF em uma aplicação ASP.NET Core

> Aprenda a integrar a API de consulta de CPF em uma aplicação ASP.NET Core com injeção de dependência e boas práticas.

**Publicado:** 07/10/2024
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/como-integrar-api-cpf-aspnet-core

---


Para integrar a API de CPF da [**CPFHub.io**](https://www.cpfhub.io/) em ASP.NET Core, use `IHttpClientFactory` com um serviço tipado, registre as configurações via `appsettings.json` e injete a dependência no controller. Essa abordagem mantém o código desacoplado, facilita testes e segue as boas práticas recomendadas pelo ecossistema .NET.

## Introdução

Integrar serviços externos em aplicações ASP.NET Core é uma prática essencial no desenvolvimento moderno. Este guia mostra como consumir a API da CPFHub.io dentro de uma aplicação ASP.NET Core, utilizando `IHttpClientFactory`, injeção de dependência e o padrão de serviços tipados.

---

## Criando o projeto ASP.NET Core

Comece criando uma nova aplicação Web API com o template padrão do .NET.

```csharp
dotnet new webapi -n CpfApi
cd CpfApi
```

Adicione a configuração da chave de API no arquivo `appsettings.json`:

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

---

## Configurando o HttpClient tipado

O ASP.NET Core recomenda o uso de `IHttpClientFactory` para gerenciar instâncias de `HttpClient`. Crie uma classe de configuração e um serviço tipado.

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

public interface ICpfService
{
 Task<CpfResponse?> ConsultarAsync(string cpf);
}

public class CpfService : ICpfService
{
 private readonly HttpClient _httpClient;

 public CpfService(HttpClient httpClient)
 {
 _httpClient = httpClient;
 }

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

 return await response.Content
 .ReadFromJsonAsync<CpfResponse>();
 }
}
```

---

## Registrando o serviço no container de DI

No `Program.cs`, registre o `HttpClient` tipado com as configurações corretas:

```csharp
using Microsoft.Extensions.Options;

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddHttpClient<ICpfService, CpfService>((sp, client) =>
{
 var settings = sp.GetRequiredService<IOptions<CpfHubSettings>>().Value;
 client.BaseAddress = new Uri(settings.BaseUrl);
 client.DefaultRequestHeaders.Add("x-api-key", settings.ApiKey);
});

builder.Services.AddControllers();
var app = builder.Build();

app.MapControllers();
app.Run();
```

---

## Criando o controller de consulta

Com o serviço registrado, crie um controller que expõe um endpoint para consulta de CPF.

```csharp
using Microsoft.AspNetCore.Mvc;

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

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

 [HttpGet("{cpf}")]
 public async Task<IActionResult> Consultar(string cpf)
 {
 try
 {
 var resultado = await _cpfService.ConsultarAsync(cpf);

 if (resultado is { Success: true })
 return Ok(resultado.Data);

 return NotFound(new { message = "CPF não encontrado" });
 }
 catch (HttpRequestException)
 {
 return StatusCode(502, new { message = "Erro ao consultar API externa" });
 }
 }
}
```

| Endpoint | Método | Descrição |
|---|---|---|
| `/api/cpf/{cpf}` | GET | Consulta dados de um CPF |
| Resposta 200 | JSON | Retorna dados do titular |
| Resposta 404 | JSON | CPF não localizado |
| Resposta 502 | JSON | Falha na API externa |

---

## Testando a integração

Após iniciar a aplicação, você pode testar o endpoint com `curl` ou qualquer cliente HTTP:

```csharp
// Teste de integração com xUnit
public class CpfControllerTests : IClassFixture<WebApplicationFactory<Program>>
{
 private readonly HttpClient _client;

 public CpfControllerTests(WebApplicationFactory<Program> factory)
 {
 _client = factory.CreateClient();
 }

 [Fact]
 public async Task Consultar_DeveRetornarOk_ParaCpfValido()
 {
 var response = await _client.GetAsync("/api/cpf/12345678900");
 Assert.Equal(System.Net.HttpStatusCode.OK, response.StatusCode);

 var content = await response.Content.ReadAsStringAsync();
 Assert.Contains("name", content);
 }
}
```

---

## Perguntas frequentes

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

Instanciar `HttpClient` diretamente em cada requisição é uma causa comum de esgotamento de sockets (socket exhaustion) em aplicações .NET sob carga. O `IHttpClientFactory` gerencia o ciclo de vida dos handlers de forma correta, reutilizando conexões e evitando esse problema. Além disso, facilita a configuração centralizada de headers — como o `x-api-key` — e a adição de políticas de retry com [Polly](https://github.com/App-vNext/Polly).

### Como proteger a chave de API em ambiente de produção?

Nunca armazene a `ApiKey` em texto puro no `appsettings.json` que vai para o repositório. Em produção, use variáveis de ambiente, Azure Key Vault, AWS Secrets Manager ou o recurso de User Secrets do .NET para desenvolvimento local. No `appsettings.json` de produção, deixe o campo vazio e injete o valor via variável de ambiente `CpfHub__ApiKey`.

### O que acontece se o limite de consultas do plano for atingido?

A API CPFHub.io não bloqueia as requisições ao atingir o limite mensal do plano. Cada consulta adicional é cobrada a R$0,15 automaticamente. No ASP.NET Core, isso significa que seu código continuará recebendo respostas normais — sem erros 429 — e a cobrança é tratada na fatura do mês.

### Como adicionar retry automático na integração com ASP.NET Core?

Use a biblioteca [Microsoft.Extensions.Http.Polly](https://www.nuget.org/packages/Microsoft.Extensions.Http.Polly/) para adicionar políticas de retry ao `HttpClient`. Configure tentativas com backoff exponencial para lidar com falhas transitórias de rede, sem impactar o consumo de créditos em casos de erro definitivo (4xx). Defina no máximo 2-3 tentativas com delay crescente para não ultrapassar o timeout do usuário.

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

A integração da API de CPF em ASP.NET Core se torna robusta e testável ao utilizar `IHttpClientFactory` e injeção de dependência. Essa abordagem permite trocar implementações facilmente, adicionar políticas de retry e manter o código desacoplado.

Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e comece a consultar dados de CPF na sua aplicação ASP.NET Core em minutos.