Sirb.CepBrasil 1.4.0

Sirb.CepBrasil

Biblioteca .NET para consulta de endereços brasileiros através do CEP (Código de Endereçamento Postal).

📋 Sobre

O Sirb.CepBrasil é uma biblioteca simples e eficiente para buscar informações de logradouro através do CEP (Código de Endereçamento Postal) utiliza uma estratégia inteligente de fallback entre múltiplos serviços públicos para garantir máxima disponibilidade.

⚠️ Aviso Importante

Esta biblioteca utiliza serviços externos de APIs públicas brasileiras. A disponibilidade e precisão dos dados dependem destes provedores, não sendo responsabilidade deste projeto.

✨ Características

• ✅ Busca inteligente com fallback entre múltiplos serviços (BrasilAPI → ViaCEP → AwesomeAPI → OpenCEP)
• ✅ Suporte a async/await com CancellationToken
• ✅ Validação automática de formato do CEP
• ✅ Gerenciamento flexível de HttpClient
• ✅ Tratamento robusto de erros com exceções personalizadas
• ✅ 100% de cobertura de testes unitários
• ✅ Documentação XML completa
• ✅ Multi-target: .NET 8, 9 e 10

📦 Instalação

dotnet add package Sirb.CepBrasil

Ou via Package Manager:

Install-Package Sirb.CepBrasil

🚀 Como Usar

Uso Básico

using Sirb.CepBrasil.Interfaces;
using Sirb.CepBrasil.Services;

// Instanciar o serviço
ICepService cepService = new CepService();

// Buscar CEP
var result = await cepService.FindAsync("01310100", CancellationToken.None);

if (result.Success)
{
    Console.WriteLine($"CEP: {result.CepContainer.Cep}");
    Console.WriteLine($"Logradouro: {result.CepContainer.Logradouro}");
    Console.WriteLine($"Bairro: {result.CepContainer.Bairro}");
    Console.WriteLine($"Cidade: {result.CepContainer.Cidade}");
    Console.WriteLine($"UF: {result.CepContainer.Uf}");
    Console.WriteLine($"Complemento: {result.CepContainer.Complemento}");
}
else
{
    Console.WriteLine($"Erro: {result.Message}");
}

Uso com HttpClient Customizado

using var httpClient = new HttpClient
{
    Timeout = TimeSpan.FromSeconds(10)
};

ICepService cepService = new CepService(httpClient);
var result = await cepService.FindAsync("01310100", CancellationToken.None);

Uso com Injeção de Dependência

// Program.cs ou Startup.cs
services.AddHttpClient<ICepService, CepService>();

// Controller ou Service
public class MeuService
{
    private readonly ICepService _cepService;

    public MeuService(ICepService cepService)
    {
        _cepService = cepService;
    }

    public async Task<string> ObterEndereco(string cep)
    {
        var result = await _cepService.FindAsync(cep, CancellationToken.None);
        return result.Success 
            ? $"{result.CepContainer.Logradouro}, {result.CepContainer.Cidade}"
            : result.Message;
    }
}

📊 Estrutura de Dados

CepResult

CepContainer

🔄 Fluxo de Funcionamento

graph TD
    A[Usuário solicita CEP] --> B{Validação}
    B -->|Inválido| C[Retorna erro]
    B -->|Válido| D[Tenta BrasilAPI]
    D -->|Sucesso| E[Retorna resultado]
    D -->|Falha/Não encontrado| F[Tenta ViaCEP]
    F -->|Sucesso| E
    F -->|Falha/Não encontrado| G[Tenta AwesomeAPI]
    G -->|Sucesso| E
    G -->|Falha/Não encontrado| H[Tenta OpenCEP]
    H -->|Sucesso| E
    H -->|Falha| I{Erro em todas?}
    I -->|Sim| J[Lança ServiceException]
    I -->|Não encontrado| K[Retorna null]

Estratégia de Fallback

A biblioteca implementa um fluxo robusto de tentativas múltiplas para garantir máxima confiabilidade:

1. BrasilAPI - Primeira tentativa
2. ViaCEP - Segunda tentativa (se BrasilAPI falhar ou não encontrar)
3. AwesomeAPI - Terceira tentativa (se ViaCEP falhar ou não encontrar)
4. OpenCEP - Quarta e última tentativa (se AwesomeAPI falhar ou não encontrar)

Comportamento por Resultado

Validação

O CEP deve conter 8 caracteres numéricos. A biblioteca aceita CEPs com ou sem formatação:

• ✅ 01310100
• ✅ 01310-100

Tratamento de Erros

• Erros de validação retornam Success = false com mensagem descritiva
• Falhas em todas as tentativas lançam ServiceException
• CEP não encontrado em nenhum serviço retorna null
• Timeout padrão de 30 segundos (personalizável via CancellationToken)

🔧 Compatibilidade

• .NET 8.0
• .NET 9.0
• .NET 10.0

📝 Licença

Este projeto está licenciado sob a Licença MIT.

🔗 Links Úteis

• BrasilAPI - Documentação
• ViaCEP - Documentação
• AwesomeAPI - Documentação
• OpenCEP - Documentação
• Repositório GitHub
• NuGet Package

📋 Changelog

Versão 1.4.0 (Atual)

• 🚀 Nova estratégia de fallback entre múltiplos serviços (BrasilAPI → ViaCEP → AwesomeAPI → OpenCEP)
• 🎯 Melhorada confiabilidade e disponibilidade do serviço
• 🚀 Atualização para .NET 8, 9 e 10
• ⚠️ Remoção de suporte para .NET 5, 6 e 7
• ⚠️ Remoção do serviço dos Correios
• ✨ 100% de cobertura de testes unitários
• ✨ Documentação XML completa em português
• ✨ Modernização da biblioteca

Versão 1.3.1

• 🐛 Ajuste de dependência faltante
• ✨ Compatibilidade com .NET 8
• ⚠️ Remoção de suporte para .NET Core 3.0 e 3.1

Versão 1.3.0

• ✨ Inclusão de compatibilidade com .NET 8
• 🚨 Remoção temporária do serviço dos Correios (em estudo)
• ✨ Adição de chamadas assíncronas com CancellationToken
• ⚡ Melhorias de performance

Versão 1.2.0

• 🐛 Correções de bugs
• ⚡ Melhorias de performance

Versão 1.1.0

• 🐛 Correções de bugs

Versão 1.0.3

• ✨ Inclusão de compatibilidade com .NET 6 e 7

Versão 1.0.2

• 🧹 Limpeza de caracteres indesejados no retorno

Versão 1.0.1

• ✨ Compatibilidade com .NET Core 3 e 3.1

Versão 1.0.0

• 🎉 Lançamento inicial para .NET 5

🤝 Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para abrir issues ou pull requests no repositório GitHub.

👤 Autor

Rodrigo Araujo Barbosa

Nota: Esta biblioteca utiliza o serviço externo ViaCEP. A disponibilidade e precisão dos dados dependem deste provedor.