# 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.

**Publicado:** 19/10/2024
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/como-integrar-api-cpf-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.

```csharp
// 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.

```csharp
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.

```csharp
@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.

```csharp
@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](https://learn.microsoft.com/pt-br/aspnet/core/blazor/call-web-api) 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.

### Leia também

- [Como validar CPF no frontend com React e API REST](https://cpfhub.io/blog/como-validar-cpf-no-frontend-com-react-e-api-rest)
- [SLA de API de CPF: níveis de disponibilidade e o que exigir do seu provedor](https://cpfhub.io/blog/sla-api-cpf-niveis-disponibilidade)
- [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos)
- [Timeout na API de CPF: como configurar e tratar corretamente](https://cpfhub.io/blog/timeout-na-api-de-cpf-como-configurar-e-tratar-corretamente)

---

## 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](https://www.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.