Como consumir a API de CPF em C# usando 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.

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.

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.

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.

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.

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:

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.

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.

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