LeadSoft® Via CEP Api integration methods and classes.
Get Started
$ dotnet add package LeadSoft.Adapter.ViaCepReadme
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 comHttpClient. - Configure
Timeout,User-Agente cabeçalhos necessários. - Adicione políticas de resiliência com Polly (
Retry,Circuit Breaker) para chamadas de rede. - Propague
CancellationTokenem 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
HttpMessageHandlerfalso noHttpClientpara 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 BitencourtPedro Foresti Leão
Nossa empresa
LeadSoft Soluções Web Ltda CNPJ 38.043.762/0001-48