LeadSoft.Adapter.IBGE 10.1.0

LeadSoft® IBGE Api Integration Adapter

LeadSoft.Adapter.IBGE

Adapter .NET para integrar com a API pública de Localidades do IBGE (https://servicodados.ibge.gov.br).
Fornece uma camada leve, testável e orientada a IHttpClientFactory para consultas de estados, regiões e municípios, encapsulando chamadas HTTP, mapeamento de modelos e tratamento de erros de forma consistente para aplicações .NET 10.

Este pacote é um tributo independente e não é afiliado oficialmente ao IBGE.
Somos gratos pela disponibilização dos dados públicos de forma aberta através da API de Localidades do IBGE. Ao utilizar este pacote, você concorda automaticamente com os termos de uso da API do IBGE.

Nuget.Org: LeadSoft.Adapter.IBGE

GitHub Repo: leadsoft-adapter-ibge

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 (IServiceCollection).
• Suporte a registro como Scoped ou Singleton.
• 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<IList<DTOState>> GetStatesAsync()

  • Retorna a lista completa de estados brasileiros com suas regiões.

• Task<DTOState> GetStatesAsync(UF aUF)

  • Retorna os dados de um estado específico pelo enum UF.
  • Inclui código IBGE, sigla, nome e região.

• Task<IList<DTOCity>> GetStatesCitiesAsync(UF aUF)

  • Retorna a lista de municípios de um estado pelo enum UF.
  • Cada município inclui código IBGE, nome, UF e nome do estado.

• Task<DTOCity> GetCitiesAsync(int aCityId)

  • Retorna os dados de um município específico pelo código IBGE.
  • Retorna null quando o código não é encontrado.

Instalação

Pelo CLI do .NET:

dotnet add package LeadSoft.Adapter.IBGE

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

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.

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

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

//...
builder.Services.AddIBGEApi();        // scoped (padrão)
// builder.Services.AddIBGEApi(true); // singleton
//...

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

Exemplo de chamada via injeção de dependência:

// Em um Controller, Service ou Minimal API endpoint:
public class LocalidadeService(IIBGE ibge)
{
    // Listar todos os estados
    IList<DTOState> estados = await ibge.GetStatesAsync();

    // Buscar estado específico (ex.: Paraná)
    DTOState pr = await ibge.GetStatesAsync(UF.PR);

    // Listar municípios de um estado
    IList<DTOCity> cidades = await ibge.GetStatesCitiesAsync(UF.PR);

    // Buscar município pelo código IBGE
    DTOCity curitiba = await ibge.GetCitiesAsync(4106902);
}

DTOs de retorno

DTOState

DTORegion

DTOCity

Configuração recomendada

• Use IServiceCollection com AddIBGEApi() — evita problemas com ciclo de vida do HttpClient.
• Configure Timeout e cabeçalhos necessários conforme os limites da API do IBGE.
• 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 (código IBGE ou UF) 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 os DTOs HTTP ao seu domínio — mapeie para modelos de domínio quando necessário.
• Evite chamadas desnecessárias: implemente cache se fizer muitas consultas aos mesmos dados (os dados do IBGE mudam raramente).

Testes

• Para testes unitários, injete um HttpMessageHandler falso no HttpClient para simular respostas da API do IBGE.
• Cubra cenários: sucesso, município 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 10.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.IBGE — adapter simples e testável para facilitar consultas à API de Localidades do IBGE em aplicações .NET 10.

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.