Como consumir API de CPF em C# com HttpClient e .NET 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

dotnet new console -n CpfHubDemo
cd CpfHubDemo

Modelando a resposta da API

Crie as classes que representam a resposta JSON:

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:

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

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

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

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

{
    "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 explica as opções disponíveis para .NET 8.

dotnet add package Microsoft.Extensions.Http.Polly

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.

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.

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 — 50 consultas mensais gratuitas, sem cartão de crédito — e integre a validação de CPF ao seu projeto .NET 8 hoje mesmo.

CPFHub.io

Pronto para integrar a API?

50 consultas gratuitas para testar agora. Sem cartão de crédito. Acesso imediato à documentação.

Começar grátis Ver documentação

Sobre a redação

Redação CPFHub.io

Time editorial especializado em APIs de CPF, identidade digital e compliance no mercado brasileiro. Produzimos guias técnicos, análises regulatórias e tutoriais sobre LGPD e KYC para desenvolvedores e líderes de produto.