Como integrar a API de CPF em um sistema Blazor

Aprenda a integrar a API de consulta de CPF em um sistema Blazor com componentes reativos e feedback visual ao usuário.

Redação CPFHub.io
Redação CPFHub.io
··5 min de leitura
Como integrar a API de CPF em um sistema Blazor

Para integrar a API de CPF em Blazor, configure um HttpClient nomeado apontando para https://api.cpfhub.io/ com o header x-api-key, crie um serviço injetável que encapsula a chamada e consuma-o em componentes Razor com feedback visual reativo — tudo em C# puro, sem JavaScript.

Introdução

O Blazor permite construir interfaces web interativas utilizando C# no lugar de JavaScript. Integrar a API de consulta de CPF do CPFHub.io em um componente Blazor proporciona uma experiência de usuário rica com validação em tempo real, tudo dentro do ecossistema .NET.


Configurando o projeto Blazor

Crie um novo projeto Blazor Server ou Blazor WebAssembly e configure o HttpClient para comunicação com a API.

// Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

builder.Services.AddHttpClient("CpfHub", client =>
{
    client.BaseAddress = new Uri("https://api.cpfhub.io/");
    client.DefaultRequestHeaders.Add("x-api-key",
    builder.Configuration["CpfHub:ApiKey"]);
});

builder.Services.AddScoped<CpfService>();

var app = builder.Build();
app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();
app.Run();

Criando o serviço de CPF

O serviço encapsula a lógica de comunicação com a API e pode ser injetado em qualquer componente Blazor.

public class CpfService
{
    private readonly IHttpClientFactory _httpClientFactory;

    public CpfService(IHttpClientFactory httpClientFactory)
    {
    _httpClientFactory = httpClientFactory;
    }

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

    if (!response.IsSuccessStatusCode)
    return null;

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

public record CpfResponse(bool Success, CpfData Data);
public record CpfData(
    string Cpf, string Name, string NameUpper,
    string Gender, string BirthDate,
    string Day, string Month, string Year
);

Construindo o componente de consulta

Crie um componente Razor que permite ao usuário digitar o CPF e ver os resultados instantaneamente.

@page "/consulta-cpf"
@inject CpfService CpfService
@rendermode InteractiveServer

<h3>Consulta de CPF</h3>

<div class="mb-3">
    <label for="cpf" class="form-label">Digite o CPF:</label>
    <input id="cpf" class="form-control" @bind="cpfInput"
    @bind:event="oninput" maxlength="14" placeholder="000.000.000-00" />
</div>

<button class="btn btn-primary" @onclick="ConsultarCpf" disabled="@isLoading">
    @if (isLoading)
    {
    <span class="spinner-border spinner-border-sm"></span>
    <span> Consultando...</span>
    }
    else
    {
    <span>Consultar</span>
    }
</button>

@if (resultado is not null)
{
    <div class="card mt-3">
    <div class="card-body">
    <h5 class="card-title">@resultado.Data.Name</h5>
    <p><strong>CPF:</strong> @resultado.Data.Cpf</p>
    <p><strong>Nascimento:</strong> @resultado.Data.BirthDate</p>
    <p><strong>Gênero:</strong> @resultado.Data.Gender</p>
    </div>
    </div>
}

@if (erro is not null)
{
    <div class="alert alert-danger mt-3">@erro</div>
}

@code {
    private string cpfInput = "";
    private bool isLoading;
    private CpfResponse? resultado;
    private string? erro;

    private async Task ConsultarCpf()
    {
    erro = null;
    resultado = null;
    isLoading = true;

    try
    {
    var cpfLimpo = new string(cpfInput.Where(char.IsDigit).ToArray());

    if (cpfLimpo.Length != 11)
    {
    erro = "CPF deve conter 11 dígitos.";
    return;
    }

    resultado = await CpfService.ConsultarAsync(cpfLimpo);

    if (resultado is null || !resultado.Success)
    erro = "CPF não encontrado na base de dados.";
    }
    catch (Exception ex)
    {
    erro = $"Erro na consulta: {ex.Message}";
    }
    finally
    {
    isLoading = false;
    }
    }
}

Adicionando máscara e validação visual

Melhore a experiência do usuário com formatação automática do CPF e indicadores visuais de validação.

@code {
    private string FormatarCpf(string valor)
    {
    var digitos = new string(valor.Where(char.IsDigit).ToArray());
    return digitos.Length switch
    {
    >= 10 => $"{digitos[..3]}.{digitos[3..6]}.{digitos[6..9]}-{digitos[9..]}",
    >= 7 => $"{digitos[..3]}.{digitos[3..6]}.{digitos[6..]}",
    >= 4 => $"{digitos[..3]}.{digitos[3..]}",
    _ => digitos
    };
    }

    private string GetCssClass()
    {
    var digitos = new string(cpfInput.Where(char.IsDigit).ToArray());
    if (digitos.Length == 0) return "form-control";
    if (digitos.Length < 11) return "form-control is-invalid";
    return CpfValidator.ValidarDigitos(digitos)
    ? "form-control is-valid"
    : "form-control is-invalid";
    }
}
EstadoClasse CSSFeedback visual
Vazioform-controlNeutro, sem borda colorida
Incompletoform-control is-invalidBorda vermelha
Formato inválidoform-control is-invalidBorda vermelha com mensagem
Formato válidoform-control is-validBorda verde

Perguntas frequentes

Blazor Server ou Blazor WebAssembly: qual é melhor para consultas de CPF?

Para consultas de CPF, o Blazor Server é geralmente preferível: a API key fica no servidor e nunca é exposta ao navegador, reduzindo o risco de vazamento. No Blazor WebAssembly, toda a lógica roda no cliente — exigindo um proxy backend para proteger a chave. Se você já tem um servidor ASP.NET Core, Blazor Server simplifica a arquitetura.

Como proteger a API key da CPFHub.io em projetos Blazor?

Armazene a chave em appsettings.json (ou variáveis de ambiente em produção) e acesse via IConfiguration. Nunca inclua a chave diretamente no código-fonte ou em arquivos versionados. Em Blazor WebAssembly, crie um endpoint de proxy no servidor que recebe a requisição do cliente e repassa à CPFHub.io com a chave no servidor.

Como lidar com a latência de ~900ms da API em componentes reativos?

Use o estado isLoading para desabilitar o botão e exibir um spinner durante a consulta. Evite disparar uma nova requisição a cada tecla digitada — aguarde o clique consciente do usuário ou implemente debounce com Task.Delay combinado a CancellationToken para não acumular chamadas simultâneas.

A documentação da Microsoft recomenda algum padrão para consumo de APIs externas em Blazor?

Sim. A documentação do ASP.NET Core recomenda usar IHttpClientFactory com clientes nomeados ou tipados, injetá-los via DI e tratar erros com try/catch nos componentes. Esse é exatamente o padrão mostrado neste artigo.


Conclusão

A integração da API de CPF em Blazor combina a produtividade do C# com a interatividade de uma aplicação web moderna. Com componentes reativos, validação visual e feedback instantâneo, o usuário tem uma experiência fluida e confiável.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e comece a construir funcionalidades de consulta de CPF no seu sistema Blazor 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.

Redação CPFHub.io

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.

WhatsAppFale conosco via WhatsApp