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

Para integrar a API de CPF da 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.

dotnet new webapi -n CpfApi
cd CpfApi

Adicione a configuração da chave de API no arquivo appsettings.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.

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:

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.

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" });
    }
    }
}

Testando a integração

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

// 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.

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

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 — 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.