NovoVerificação de identidade facial

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.

Lucas Vieira
Lucas Vieira
··6 min de leitura
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.

Código HTTPSignificadoAção recomendada
200SucessoProcessar resposta normalmente
400Requisição inválidaVerificar formato do CPF enviado
401Não autorizadoVerificar a chave de API
404CPF não encontradoInformar ao usuário que não há dados
500Erro interno do servidorTentar novamente após alguns segundos

No gratuito, zerar os 50 créditos do mês interrompe as consultas com HTTP 403 ("Limite de créditos excedido"). Nos planos pagos o excedente não é um valor único: ele varia e está publicado na página de preços. O limite por minuto responde HTTP 429 com Retry-After.

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 ~150 ms, 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.

CPFHub.io

Pronto para integrar a API?

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

WhatsApp