PHPackages                             droumillac/brazil-taxid - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Validation & Sanitization](/categories/validation)
4. /
5. droumillac/brazil-taxid

ActiveLibrary[Validation & Sanitization](/categories/validation)

droumillac/brazil-taxid
=======================

Biblioteca para validação de CPF/CNPJ (com suporte a matriz alfanumérica) e consulta em provedores com sistema de fallback

09PHP

Since Apr 6Pushed 2mo agoCompare

[ Source](https://github.com/droumillac/brazil-taxid)[ Packagist](https://packagist.org/packages/droumillac/brazil-taxid)[ RSS](/packages/droumillac-brazil-taxid/feed)WikiDiscussions main Synced today

READMEChangelogDependenciesVersions (1)Used By (0)

CPF & CNPJ Validator/API Consultant
=======================================

[](#cpf--cnpj-validatorapi-consultant)

Uma biblioteca PHP robusta focada em ecossistemas modernos do Brasil. Além de realizar a **validação híbrida matemática de CNPJs** (incluindo o novo padrão alfanumérico estipulado para Julho/2026) e **CPFs**, possui uma inteligência de **fallback (contingência)** nativa para realizar consultas cadastrais em diferentes APIs públicas, garantindo alta disponibilidade e a entrega de um JSON padronizado.

✨ Funcionalidades Principais
----------------------------

[](#-funcionalidades-principais)

- **Validação de CNPJ Híbrido:** Suporte integral ao padrão de CNPJ alfanumérico que entra em vigor em 2026 utilizando cálculos avançados (Tabela ASCII).
- **Validação de CPF.**
- **Alta Disponibilidade (Fallback System):** Se uma API estiver inoperante (HTTP Error, Rate Limit, etc), a biblioteca consulta automaticamente a próxima disponível na fila.
- **Payload Normalizado (DTO Padrão SERPRO):** O retorno dos dados da empresa ou pessoa física é perfeitamente unificado e inspirado na arquitetura da API do SERPRO, em Data Transfer Objects de fácil controle (`CompanyData` para CNPJ e `PersonData` para CPF).
- **Configurável:** Você define qual será a sua primeira opção de resposta e quais os pesos de contingência.

🚀 Provedores de API Suportados
------------------------------

[](#-provedores-de-api-suportados)

**Para CNPJ:**

- **[BrasilAPI](https://brasilapi.com.br/)** *(Prioridade padrão 1)*
- **[MinhaReceita](https://minhareceita.org/)** *(Prioridade padrão 2)*
- **[CnpjWS](https://cnpj.ws/)** *(Prioridade padrão 3)*
- **[ReceitaWS](https://receitaws.com.br/)** *(Prioridade padrão 4 - Restrito)*
- **[Serpro (Oficial)](https://www.serpro.gov.br)** *(Exige Token)*

**Para CPF:**

- **[Serpro (Oficial)](https://www.serpro.gov.br)** *(Exige Token)*

📦 Instalação
------------

[](#-instalação)

Como o pacote usa PSR-4 e GuzzleHttp para as requisições, adicione-o via composer:

```
composer require droumillac/brazil-taxid
```

🛠️ Como Utilizar
----------------

[](#️-como-utilizar)

### Validação de Documentos

[](#validação-de-documentos)

```
use BrazilTaxId\Validators\CnpjValidator;
use BrazilTaxId\Validators\CpfValidator;

// Novo cenário Alfanumérico!
$validoStr = CnpjValidator::isValid('12ABC34501DE35'); // bool(true/false)

$validoCpf = CpfValidator::isValid('111.222.333-44'); // bool(true/false)
```

### Consultando CNPJ ou CPF (Modo Padrão Falback)

[](#consultando-cnpj-ou-cpf-modo-padrão-falback)

```
use BrazilTaxId\DocumentConsultant;

// Se não passar nada, ele usará a lista gratuita de CNPJ (BrasilAPI, MinhaReceita, CnpjWS, ReceitaWS)
$consultant = new DocumentConsultant();
$respostaCnpj = $consultant->consultCnpj('00.000.000/0001-91');
$respostaCpf = $consultant->consultCpf('111.222.333-44'); // Vai falhar se não houver provedores de CPF configurados

if ($respostaCnpj['success']) {
    print_r($respostaCnpj['data']); // Array padronizado padrão Serpro!
} else {
    echo $respostaCnpj['message'];
}

// Para ver qual provedor funcionou:
echo "Fornecido por: " . json_encode($respostaCnpj['message']);
```

### Alterando as Prioridades das APIs (Injetando Provedores API)

[](#alterando-as-prioridades-das-apis-injetando-provedores-api)

Você possui a liberdade de injetar a classe provedora preterida passando instâncias no construtor. O primeiro array é dedicado a provedores de CNPJ, e o segundo a provedores de CPF.

```
use BrazilTaxId\DocumentConsultant;
use BrazilTaxId\Providers\MinhaReceitaProvider;
use BrazilTaxId\Providers\BrasilApiProvider;
use BrazilTaxId\Providers\SerproProvider;

// Define a ordem customizada!
// O Serpro emitirá automaticamente um Token Oauth2 e fará o Cache Inteligente disso
// na temporária do Sistema Operacional de forma 100% autônoma para economizar suas cotas.
$customConsultant = new DocumentConsultant(
    [ // Array de CNPJs
        new SerproProvider('SUA_CONSUMER_KEY', 'SEU_CONSUMER_SECRET'), // Tenta o SERPRO Oficial primeiro
        new MinhaReceitaProvider(), // Cai pra Minha Receita se falhar
    ],
    [ // Array de CPFs
        new SerproProvider('SUA_CONSUMER_KEY', 'SEU_CONSUMER_SECRET')
    ]
);

$resultado = $customConsultant->consultCnpj('06.990.590/0001-23');
$resultadoCpf = $customConsultant->consultCpf('111.222.333-44');
```

🗃️ Estrutura do DTO de Retorno (Baseado na Identidade SERPRO)
-------------------------------------------------------------

[](#️-estrutura-do-dto-de-retorno-baseado-na-identidade-serpro)

Sempre que a key `success` for `true`, o escopo `data` terá a composição espelhada do SERPRO para altíssima confiabilidade e adoção governamental, independentemente de qual API (CnpjWS, BrasilAPI) retornou os dados.

### Exemplo do Data retornado de CNPJ (`CompanyData` DTO)

[](#exemplo-do-data-retornado-de-cnpj-companydata-dto)

```
{
    "ni": "00000000000191",
    "tipoEstabelecimento": "1",
    "nomeEmpresarial": "BANCO DO BRASIL SA",
    "nomeFantasia": "DIRECAO GERAL",
    "situacaoCadastral": {
        "codigo": "2",
        "data": "2005-11-03",
        "motivo": ""
    },
    "naturezaJuridica": {
        "codigo": "2038",
        "descricao": "Sociedade de Economia Mista"
    },
    ...
}
```

### Exemplo do Data retornado de CPF (`PersonData` DTO)

[](#exemplo-do-data-retornado-de-cpf-persondata-dto)

```
{
    "ni": "00000000001",
    "nome": "JOAO DAS COUVES",
    "situacao": {
        "codigo": "0",
        "descricao": "REGULAR"
    },
    "nascimento": "29021999",
    "dataInscricao": "04072000"
}
```

---

*Requer PHP 8.1 ou superior e GuzzleHTTP.*

###  Health Score

20

—

LowBetter than 13% of packages

Maintenance55

Moderate activity, may be stable

Popularity5

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity12

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/60153048?v=4)[Diego Roumillac](/maintainers/droumillac)[@droumillac](https://github.com/droumillac)

---

Top Contributors

[![droumillac](https://avatars.githubusercontent.com/u/60153048?v=4)](https://github.com/droumillac "droumillac (9 commits)")

### Embed Badge

![Health badge](/badges/droumillac-brazil-taxid/health.svg)

```
[![Health](https://phpackages.com/badges/droumillac-brazil-taxid/health.svg)](https://phpackages.com/packages/droumillac-brazil-taxid)
```

###  Alternatives

[marcosh/php-validation-dsl

A DSL for validating data in a functional fashion

483.9k](/packages/marcosh-php-validation-dsl)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)