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";
}
}
| Estado | Classe CSS | Feedback visual |
|---|---|---|
| Vazio | form-control | Neutro, sem borda colorida |
| Incompleto | form-control is-invalid | Borda vermelha |
| Formato inválido | form-control is-invalid | Borda vermelha com mensagem |
| Formato válido | form-control is-valid | Borda 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.
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.



