GetCNPJ para PHP

Consulte dados públicos de empresas brasileiras com resposta padronizada,
validação de CNPJ e fallback automático entre múltiplos provedores.

PHP puro · Laravel · CodeIgniter 4

Instalação

Comece em 30 segundos

O CNPJ pode ser informado com ou sem máscara. A biblioteca valida os dígitos verificadores antes de realizar qualquer chamada HTTP.

Por que usar?

• Fallback automático: se um serviço estiver indisponível, o próximo provedor é consultado.
• Resposta padronizada: trabalhe com o mesmo modelo de dados, independentemente da API utilizada.
• Quatro provedores: CNPJ.WS, ReceitaWS, BrasilAPI e CNPJA.
• Inscrição estadual: retornada pelo CNPJ.WS quando disponível.
• Rate limiting: limite independente por provedor, com Sliding Window.
• Validação local: CNPJs inválidos não consomem requisições externas.
• Integrações nativas: PHP puro, container e Facade no Laravel e Service Discovery no CodeIgniter 4.
• Extensível e testável: cliente HTTP PSR-18 injetável e objetos tipados serializáveis em JSON.

Compatibilidade

O núcleo é testado em PHP 8.1. As integrações com as versões atuais de Laravel e CodeIgniter 4 são testadas em PHP 8.2, 8.3 e 8.4.

Provedores e fallback

Os provedores são consultados nesta ordem:

Quando um provedor falha, a exceção é registrada em $result->errors e a consulta segue para o próximo. Se todos falharem, o resultado contém os detalhes de cada tentativa.

Sumário

• PHP puro
• Laravel
• CodeIgniter 4
• Provedor específico
• Configuração avançada
• Modelo retornado
• Tratamento de erros
• Rate limiting
• Desenvolvimento e testes
• Publicação de versões

PHP puro

Laravel

O Laravel encontra automaticamente o Service Provider e a Facade declarados no pacote. Não é necessário editar bootstrap/providers.php ou config/app.php.

Injeção de dependência

O cliente é registrado como singleton e também pode ser resolvido diretamente:

Facade

Configuração do Laravel

Publique o arquivo config/getcnpj.php:

Configure pelo .env:

Se houver uma implementação de Psr\Http\Client\ClientInterface registrada no container, ela será utilizada automaticamente. Caso contrário, o pacote usa o Guzzle incluído.

CodeIgniter 4

Com o Service Discovery padrão habilitado, o CodeIgniter encontra automaticamente GetCNPJ\Config\Services:

service('getCnpj') retorna uma instância compartilhada. Para criar uma nova instância:

Também é possível acessar o serviço diretamente:

Configure pelo .env do CodeIgniter:

Se discoverInComposer estiver desabilitado em app/Config/Modules.php, use \GetCNPJ\Config\Services::getCnpj() ou permita azumamagus/get-cnpj na descoberta de pacotes.

Provedor específico

Use o enum para evitar erros de digitação:

Também são aceitas as strings CNPJWS, ReceitaWS, BrasilAPI e CNPJA, sem diferenciação entre maiúsculas e minúsculas.

Configuração avançada

Cliente HTTP customizado

Qualquer cliente PSR-18 pode ser injetado:

Isso também facilita testes, observabilidade, proxies e políticas HTTP próprias da aplicação.

Modelo retornado

Uma consulta sempre retorna GetCNPJ\Models\CnpjResult:

Em caso de sucesso, CnpjData oferece:

Datas são instâncias de DateTimeImmutable. Todos os modelos implementam JsonSerializable:

Exemplo resumido:

Tratamento de erros

CNPJ inválido

Um CNPJ com tamanho ou dígitos verificadores inválidos lança InvalidCnpjException antes da consulta:

Falha dos provedores

Erros de rede ou respostas inválidas não interrompem o fallback. Se todos os provedores falharem:

Rate limiting

O Sliding Window mantém um contador separado para cada provedor. Por padrão são permitidas três requisições por minuto para cada serviço. Quando o limite é atingido, a chamada aguarda até a requisição mais antiga sair da janela.

O controle permanece em memória durante a vida da instância de CnpjClient. Em aplicações distribuídas, configure limites também na infraestrutura ou implemente RateLimiterInterface com armazenamento compartilhado.

Uso responsável

Este pacote consulta APIs públicas de terceiros. Portanto:

• respeite os termos e limites de cada provedor;
• espere indisponibilidades e mudanças externas de contrato;
• não trate os dados como substitutos de uma certidão oficial;
• use cache quando realizar consultas repetidas;
• observe a legislação aplicável ao tratamento e armazenamento de dados.

Desenvolvimento e testes

A suíte usa respostas HTTP simuladas para validar CNPJ, mapeamento, fallback e rate limiting. Também inicializa ambientes reais dos frameworks para testar container e Facade do Laravel e serviços do CodeIgniter 4.

O GitHub Actions executa:

• instalação de produção e validação de sintaxe no PHP 8.1;
• suíte completa com integrações nos PHP 8.2, 8.3 e 8.4.

Publicação de versões

O pacote está disponível em packagist.org/packages/azumamagus/get-cnpj.

Novas versões são publicadas automaticamente ao enviar uma tag semântica:

O workflow valida a tag, o Composer e os testes antes de notificar a API oficial do Packagist. Pré-lançamentos como v1.1.0-beta.1 também são aceitos.

Uma versão estável publicada no Packagist é imutável. Para corrigir uma versão, crie uma nova tag; nunca mova ou recrie uma tag existente.

Contribuindo

Issues e pull requests são bem-vindos. Ao contribuir:

1. crie uma branch para a alteração;
2. adicione ou atualize os testes;
3. execute composer test;
4. abra um pull request descrevendo o comportamento alterado.

Licença

Distribuído sob a licença MIT. Consulte LICENSE.

Feito para tornar consultas de CNPJ simples, resilientes e independentes de framework.