RBytesNetCep 0.4.0

RBytesNetCep

RBytesNetCep é uma biblioteca .NET para consulta de CEPs brasileiros, com múltiplos provedores e fallback automático. Ela facilita a integração de busca de endereços a partir do CEP, garantindo maior disponibilidade e confiabilidade ao utilizar diferentes fontes de dados. Controle de cache para evitar requisições desnecessárias e melhorar a performance.

Instalação

Adicione o pacote ao seu projeto via NuGet:

dotnet add package RBytesNetCep

Ou, se estiver utilizando referência local:

dotnet add reference ../RBytesNetCep/RBytesNetCep.csproj

Uso Básico - consulta de cep com controle de fallback

using RBytesNetCep;

var service = new CepService();
var result = await service.GetCepAsync("06233-030", false); //true = não usar cache, false = usar cache

if (result?.Address != null)
{
      Console.WriteLine("Endereço encontrado:");
      Console.WriteLine($"CEP: {address.Cep}");
      Console.WriteLine($"Logradouro: {address.Logradouro}");
      Console.WriteLine($"Bairro: {address.Bairro}");
      Console.WriteLine($"Cidade: {address.Localidade}");
      Console.WriteLine($"UF: {address.Uf}");
      Console.WriteLine($"Complemento: {address.Complemento}");
      Console.WriteLine($"DDD: {address.Ddd}");
      Console.WriteLine($"Provider: {address.ProviderUsado}"); //informa de qual provider retornou o resultado
}
else
{
      Console.WriteLine(result?.ErrorMessage);  
}

Consulta direto utilizando provider especifico (sem fallback)

using RBytesNetCep;

var service = new CepService();
var result = await cepService.GetCepByProviderAsync(cep, "BrasilAPI"); //opções: ApiCep, BrasilAPI, OpenCEP e ViaCEP

if (result?.Address != null)
{
      Console.WriteLine("Endereço encontrado:");
      Console.WriteLine($"CEP: {address.Cep}");
      Console.WriteLine($"Logradouro: {address.Logradouro}");
      Console.WriteLine($"Bairro: {address.Bairro}");
      Console.WriteLine($"Cidade: {address.Localidade}");
      Console.WriteLine($"UF: {address.Uf}");
      Console.WriteLine($"Complemento: {address.Complemento}");
      Console.WriteLine($"DDD: {address.Ddd}"); //nem todos os provedores trazem essa informação
      Console.WriteLine($"Provider: {address.ProviderUsado}");
}
else
{
      Console.WriteLine(result?.ErrorMessage);  
}

Provedores Suportados

Atualmente, a biblioteca suporta os seguintes provedores, com fallback automático:

• ApiCep
• ViaCEP
• BrasilAPI
• OpenCEP

A ordem de fallback pode ser personalizada conforme a necessidade.

Exemplo de Resposta

{
  "cep": "06233-030",
  "logradouro": "Avenida dos Autonomistas",
  "bairro": "Presidente Altino",
  "localidade": "Osasco",
  "uf": "SP",
  "complemento": "",
  "ddd": ""
}

Roadmap

• Suporte a múltiplos provedores
• Fallback automático
• Consulta individual por provider
• Cache de resultados
• Circuit breaker para provedores instáveis
• Suporte a consulta por faixa de CEP

Contribuindo

Pull requests são bem-vindos! Para grandes mudanças, abra uma issue primeiro para discutir o que você gostaria de modificar.

por: Rodrigo Delphino rodrigo.s.delphino@gmail.com