Biblioteca para consulta de CNPJ em APIs públicas brasileiras (ReceitaWS, BrasilAPI, CNPJA). Suporta .NET Framework 4.5+, .NET 8, .NET 9 e .NET Standard 2.0 com rate limiting integrado.
Get Started
$ dotnet add package GetCNPJReadme
GetCNPJ
Biblioteca .NET para consulta de CNPJ em APIs públicas brasileiras, com suporte a múltiplos provedores e rate limiting integrado.
📋 Características
- ✅ Multi-Target: Suporta .NET Framework 4.8, 4.8.1, .NET 8, .NET 9 e .NET Standard 2.0
- 🔄 Chain of Responsibility: Tenta automaticamente outros provedores em caso de falha
- ⏱️ Rate Limiting: Controle automático de 3 requisições por minuto por provedor
- 🎯 Retorno Padronizado: Dados consistentes independente do provedor utilizado
- 📋 Inscrição Estadual: Suporte completo a inscrições estaduais (via CNPJ.WS)
- 🔌 Múltiplos Provedores:
- CNPJ.WS (https://publica.cnpj.ws) - Provedor padrão ⭐ Único que retorna inscrição estadual
- ReceitaWS (https://receitaws.com.br)
- BrasilAPI (https://brasilapi.com.br)
- CNPJA (https://open.cnpja.com)
- 🛡️ Validação: Validação automática de dígitos verificadores do CNPJ
- ⚡ Async/Await: API totalmente assíncrona + métodos síncronos para compatibilidade
- 🎨 Clean Code: Seguindo padrões SOLID e melhores práticas
📦 Instalação
dotnet add package GetCNPJ
Ou via NuGet Package Manager:
Install-Package GetCNPJ
🚀 Uso Básico
Consulta Simples
using GetCNPJ;
using System;
// Criar cliente
using var client = new CnpjClient();
// Consultar CNPJ (aceita formatado ou apenas números)
var result = await client.GetAsync("03.312.791/0001-83");
if (result.Success)
{
var data = result.Data;
Console.WriteLine($"Razão Social: {data.RazaoSocial}");
Console.WriteLine($"Nome Fantasia: {data.NomeFantasia}");
Console.WriteLine($"CNPJ: {data.Cnpj}");
Console.WriteLine($"Situação: {data.Situacao}");
Console.WriteLine($"Endereço: {data.Endereco.EnderecoCompleto}");
Console.WriteLine($"Email: {data.Email}");
Console.WriteLine($"Telefones: {string.Join(", ", data.Telefones)}");
// Inscrições Estaduais (disponível quando usa CNPJ.WS)
if (data.InscricoesEstaduais != null && data.InscricoesEstaduais.Any())
{
Console.WriteLine("Inscrições Estaduais:");
foreach (var ie in data.InscricoesEstaduais)
{
Console.WriteLine($" - {ie}"); // Formato: Inscrição (UF) - Status
}
}
Console.WriteLine($"Provedor usado: {data.Provedor}");
}
else
{
Console.WriteLine($"Erro: {result.ErrorMessage}");
// Exibir erros de cada provedor
foreach (var error in result.Errors)
{
Console.WriteLine($"- {error.ProviderName}: {error.ErrorMessage}");
}
}
Consulta com Provedor Específico
using var client = new CnpjClient();
// Forçar uso de um provedor específico
var result = await client.GetFromProviderAsync("03312791000183", "BrasilAPI");
if (result.Success)
{
Console.WriteLine($"Razão Social: {result.Data.RazaoSocial}");
}
Consulta Síncrona
Para aplicações que não usam async/await, você pode usar os métodos síncronos:
using var client = new CnpjClient();
// Método síncrono
var result = client.Get("03312791000183");
if (result.Success)
{
Console.WriteLine($"Razão Social: {result.Data.RazaoSocial}");
Console.WriteLine($"Nome Fantasia: {result.Data.NomeFantasia}");
}
// Provedor específico síncrono
var result2 = client.GetFromProvider("03312791000183", "ReceitaWS");
Nota: Os métodos síncronos bloqueiam a thread atual. Para aplicações modernas (ASP.NET Core, WPF, etc.), recomenda-se usar os métodos assíncronos.
Configuração Customizada
var options = new CnpjClientOptions
{
MaxRequestsPerMinute = 5, // Aumentar rate limit (use com cuidado!)
Timeout = TimeSpan.FromSeconds(60), // Timeout customizado
EnableReceitaWS = true, // Habilitar/desabilitar provedores
EnableBrasilAPI = true,
EnableCNPJA = false // Desabilitar CNPJA, por exemplo
};
using var client = new CnpjClient(null, options);
var result = await client.GetAsync("03312791000183");
HttpClient Customizado
// Usar seu próprio HttpClient (recomendado em aplicações ASP.NET Core)
var httpClient = new HttpClient
{
Timeout = TimeSpan.FromSeconds(30)
};
using var client = new CnpjClient(httpClient);
var result = await client.GetAsync("03312791000183");
📊 Modelo de Dados Retornado
public class CnpjData
{
public string Cnpj { get; set; } // CNPJ formatado
public string RazaoSocial { get; set; } // Razão social
public string NomeFantasia { get; set; } // Nome fantasia
public DateTime? DataAbertura { get; set; } // Data de abertura
public string Situacao { get; set; } // Situação cadastral
public DateTime? DataSituacao { get; set; } // Data da situação
public string Tipo { get; set; } // MATRIZ/FILIAL
public string Porte { get; set; } // Porte da empresa
public string NaturezaJuridica { get; set; } // Natureza jurídica
public decimal? CapitalSocial { get; set; } // Capital social
public Endereco Endereco { get; set; } // Endereço completo
public AtividadeEconomica AtividadePrincipal { get; set; }
public List<AtividadeEconomica> AtividadesSecundarias { get; set; }
public List<Socio> QuadroSocietario { get; set; } // QSA
public List<string> Telefones { get; set; } // Telefones
public string Email { get; set; } // Email
public List<InscricaoEstadual> InscricoesEstaduais { get; set; } // Inscrições estaduais (CNPJ.WS)
public SimplesNacional Simples { get; set; } // Info Simples Nacional
public DateTime? UltimaAtualizacao { get; set; } // Data da atualização
public string Provedor { get; set; } // Provedor usado
}
⚙️ Padrões de Projeto Utilizados
- Strategy Pattern: Diferentes implementações de provedores de API
- Chain of Responsibility: Tentativa automática em múltiplos provedores
- Factory Pattern: Criação de instâncias dos provedores
- Repository Pattern: Abstração da lógica de consulta
- DTO Pattern: Padronização dos retornos
- Rate Limiter Pattern: Controle de requisições usando Sliding Window
🔒 Rate Limiting
A biblioteca implementa rate limiting automático de 3 requisições por minuto por provedor, conforme solicitado. Cada provedor tem seu próprio contador independente.
O algoritmo utilizado é o Sliding Window, que garante distribuição uniforme das requisições ao longo do tempo.
🛠️ Arquitetura
GetCNPJ/
├── Models/ # DTOs padronizados
├── Interfaces/ # Contratos da biblioteca
├── Exceptions/ # Exceções customizadas
├── Enums/ # Enumerações
├── Providers/
│ ├── Base/ # Classe base para providers
│ ├── ReceitaWS/ # Provider ReceitaWS
│ ├── BrasilAPI/ # Provider BrasilAPI
│ └── CNPJA/ # Provider CNPJA
├── Services/ # Serviço principal (Chain of Responsibility)
├── RateLimiter/ # Implementação do Rate Limiter
└── CnpjClient.cs # Cliente principal
🧪 Tratamento de Erros
A biblioteca trata erros de forma elegante:
- CNPJ Inválido: Lança
InvalidCnpjException - Provedor Indisponível: Tenta o próximo provedor automaticamente
- Rate Limit Excedido: Aguarda automaticamente antes de fazer nova requisição
- Timeout: Configurável via
CnpjClientOptions - Todos Provedores Falharam: Retorna
CnpjResultcomSuccess = falsee lista de erros
📝 Requisitos
- .NET Framework 4.8+ ou
- .NET 8+ ou
- .NET Standard 2.0+
🤝 Contribuindo
Contribuições são bem-vindas! Sinta-se à vontade para:
- Fazer fork do projeto
- Criar uma branch para sua feature (
git checkout -b feature/AmazingFeature) - Commit suas mudanças (
git commit -m 'Add some AmazingFeature') - Push para a branch (
git push origin feature/AmazingFeature) - Abrir um Pull Request
📄 Licença
Este projeto está licenciado sob a licença MIT - veja o arquivo LICENSE para detalhes.
🔗 APIs Utilizadas
- CNPJ.WS - API padrão ⭐ Único provedor que retorna inscrição estadual
- ReceitaWS - API gratuita de consulta de CNPJ
- BrasilAPI - API pública brasileira
- CNPJA - API aberta de CNPJ
Nota: Por padrão, a biblioteca usa o provedor CNPJ.WS como primeira opção (prioridade 1) pois é o único que fornece dados de inscrição estadual. Os demais provedores são utilizados como fallback em caso de falha.
⚠️ Avisos Importantes
- Rate Limiting: Respeite os limites de requisição das APIs públicas (3 req/min por padrão)
- Uso Responsável: Esta biblioteca é para uso educacional e em aplicações que respeitem os termos de uso das APIs
- Dados Públicos: Os dados retornados são públicos e provenientes da Receita Federal do Brasil
- Sem Garantias: Os provedores podem ter indisponibilidade ou mudanças sem aviso prévio
🎯 Roadmap
- Adicionar cache de consultas
- Suporte a mais provedores
- Métricas e telemetria
- Retry policy configurável
- Suporte a consulta em lote
- Logging integrado
📞 Suporte
Para reportar bugs ou solicitar features, abra uma issue no GitHub.
Desenvolvido com ❤️ seguindo as melhores práticas de Clean Code e SOLID