LeadSoft.Adapter.ViaCep 10.0.1

LeadSoft® Via CEP Api Integration Adapter

LeadSoft.Adapter.ViaCep

Adapter .NET para integrar com o serviço público ViaCEP (https://viacep.com.br).
Fornece uma camada leve, testável e orientada a IHttpClientFactory para consultas de CEP, encapsulando chamadas HTTP, mapeamento de modelos e tratamento de erros de forma consistente para aplicações .NET 9.

Este pacote é um tributo independente e não é afiliado oficialmente à ViaCEP. Somos gratos pela iniciativa de disponibilizar dados públicos de forma aberta. Conheça o projeto oficial e utilizando este pacote, você concorda automaticamente com os termos de uso da ViaCEP, aproveite para fazer uma doação no rodapé do site oficial do ViaCEP.

Nuget.Org: LeadSoft.Adapter.ViaCep

GitHub Repo: leadsoft-adapter-viacep

Principais características

• Compatível com .NET 10.0.
• Chamadas assíncronas com async/await.
• Fácil integração com injeção de dependência (IHttpClientFactory).
• Projetado para ser testável (injeção de HttpMessageHandler / HttpClient).
• Tratamento centralizado de erros e respostas HTTP.
• Preparado para extensão com políticas de resiliência (ex.: Polly).
• Open Source (MIT License).

Métodos disponíveis

• Task<DTOFoundAddress> GetAddressAsync(string aCEP)
  • Consulta endereço pelo CEP informado.
  • Retorna logradouro, bairro, localidade, uf, ibge, etc.

Instalação

Pelo CLI do .NET:

dotnet add package LeadSoft.Adapter.ViaCep

Ou via NuGet Package Manager no Visual Studio (pesquise por LeadSoft.Adapter.ViaCep).

Uso básico (exemplo)

Abaixo um exemplo genérico de como registrar e usar o adapter em uma aplicação ASP.NET Core / Console com DI e IHttpClientFactory.

// Program.cs (exemplo)
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using LeadSoft.Adapter.BrasilAPI;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

//...
builder.Logging.AddViaCEPApi(); //builder.Logging.AddViaCEPApi(true); para injeção em singleton
//...

WebApplication app = builder.Build();
app.Run();

Exemplo de chamada (pseudocódigo; adapte para os tipos reais do pacote):

string cep = "80240060";
DTOFoundAddress dto = await new ViaCEP().GetAddressAsync(cep);

Configuração recomendada

• Use IHttpClientFactory (services.AddHttpClient(...)) — evita problemas com HttpClient.
• Configure Timeout, User-Agent e cabeçalhos necessários.
• Adicione políticas de resiliência com Polly (Retry, Circuit Breaker) para chamadas de rede.
• Propague CancellationToken em todas as chamadas assíncronas.

Boas práticas de integração

• Valide entradas (CEP com tamanho/formato corretos) antes de chamar o adapter.
• Capture e logue erros com ILogger<T> para diagnóstico: inclua status code e corpo quando aplicável.
• Não exponha diretamente modelos HTTP ao seu domínio — mapeie para DTOs/Modelos de domínio quando necessário.
• Evite chamadas desnecessárias: implemente cache se fizer muitas consultas ao mesmo CEP.

Testes

• Para testes unitários, injete um HttpMessageHandler falso no HttpClient para simular respostas do ViaCEP.
• Cubra cenários: sucesso, CEP não encontrado, respostas inválidas e timeouts.
• Use fixtures com exemplos de payloads JSON conhecidos para manter os testes determinísticos.

Versionamento e Compatibilidade

• Destinado a .NET 9.0. Verifique a compatibilidade do pacote com seu projeto.
• Siga versionamento semântico: breaking changes → major, novas features → minor, correções → patch.

Licença

Consulte o arquivo de licença no repositório para detalhes sobre uso e redistribuição.

LeadSoft.Adapter.ViaCep — adapter simples e testável para facilitar consultas ao ViaCEP em aplicações .NET 9.

Development

Desenvolvido pelo time da LeadSoft® Soluções Web.

• Lucas Resende Tavares
• Frederico Ferreira Bitencourt
• Pedro Foresti Leão

Nossa empresa

LeadSoft Soluções Web Ltda CNPJ 38.043.762/0001-48

Como nos encontrar:

• Nosso Site
• GitHub
• LinkedIn
• Behance
• YouTube
• Instagram
• Facebook

INFORMAÇÕES DE CONTATO Se você tiver alguma dúvida sobre estes Termos ou Serviços, entre em contato conosco em

developers@leadsoft.inf.br.