Metadata-Version: 2.4
Name: cnpjob
Version: 1.1.0
Summary: SDK oficial para a API cnpj/ob — consulta CNPJ, sócios, CNAE e mais
Author: cnpjob
License: MIT
Project-URL: Homepage, https://cnpjob.com.br
Project-URL: Repository, https://github.com/esdrasjob/cnpjob
Project-URL: Issues, https://github.com/esdrasjob/cnpjob/issues
Keywords: cnpj,receita-federal,brasil,sdk,empresa
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28

# cnpjob

SDK oficial Python para a [API cnpj/ob](https://cnpjob.com.br) — consulte qualquer CNPJ diretamente da Receita Federal com uma linha de código.

## Instalação

```bash
pip install cnpjob
```

## Início rápido

```python
from cnpjob import CNPJob

client = CNPJob('SUA_API_KEY')

empresa = client.lookup('12.345.678/0001-00')
print(empresa['razao_social'])  # EMPRESA EXEMPLO LTDA
```

> Obtenha sua API key gratuita em [app.cnpjob.com.br](https://app.cnpjob.com.br/register)

---

## Métodos

### `lookup(cnpj)`

Consulta completa de uma empresa pelo CNPJ. Aceita qualquer formato (com ou sem máscara).

```python
empresa = client.lookup('12.345.678/0001-00')

print(empresa['razao_social'])        # EMPRESA EXEMPLO LTDA
print(empresa['nome_fantasia'])       # Empresa Exemplo
print(empresa['situacao_cadastral'])  # ATIVA
print(empresa['data_abertura'])       # 2010-03-15
print(empresa['endereco']['municipio'])  # São Paulo
print(empresa['socios'])             # [{'nome': ..., 'qualificacao': ...}]
```

### `batch(cnpjs)`

Consulta múltiplos CNPJs em uma única requisição (até 10 por chamada).

```python
resultado = client.batch([
    '12345678000100',
    '33000167000101',
    '60701190000104',
])

for empresa in resultado['results']:
    print(empresa['cnpj'], empresa['razao_social'])
```

### `validate(cnpj)`

Valida o formato e os dígitos verificadores de um CNPJ. **Não consome cota.**

```python
result = client.validate('12.345.678/0001-00')
print(result['valid'])  # True ou False
```

---

## Resposta completa

```python
{
    "cnpj": "12345678000100",
    "razao_social": "EMPRESA EXEMPLO LTDA",
    "nome_fantasia": "Empresa Exemplo",
    "situacao_cadastral": "ATIVA",
    "data_abertura": "2010-03-15",
    "natureza_juridica": "Sociedade Empresária Limitada",
    "porte": "MICRO EMPRESA",
    "capital_social": 10000.00,
    "endereco": {
        "logradouro": "Rua das Flores",
        "numero": "100",
        "complemento": "Sala 1",
        "bairro": "Centro",
        "municipio": "São Paulo",
        "uf": "SP",
        "cep": "01310-100"
    },
    "atividade_principal": {
        "codigo": "6201-5/01",
        "descricao": "Desenvolvimento de programas de computador sob encomenda"
    },
    "socios": [
        {
            "nome": "JOÃO DA SILVA",
            "qualificacao": "Sócio-Administrador",
            "pais_origem": "Brasil"
        }
    ]
}
```

---

## Tratamento de erros

```python
from cnpjob import CNPJob

client = CNPJob('SUA_API_KEY')

try:
    empresa = client.lookup('00000000000000')
except Exception as e:
    print(e)
    # "CNPJ não encontrado"      → HTTP 404
    # "Limite de requisições"    → HTTP 429 (upgrade de plano)
    # "Chave de API inválida"    → HTTP 401
```

| Código | Causa |
|--------|-------|
| `401`  | API key inválida ou ausente |
| `403`  | IP bloqueado pela allowlist |
| `404`  | CNPJ não encontrado |
| `429`  | Limite de requisições atingido |

---

## Uso com Django / FastAPI

```python
# Django view
from cnpjob import CNPJob
from django.http import JsonResponse

client = CNPJob(settings.CNPJOB_API_KEY)

def consulta_cnpj(request, cnpj):
    empresa = client.lookup(cnpj)
    return JsonResponse(empresa)
```

```python
# FastAPI endpoint
from cnpjob import CNPJob
from fastapi import FastAPI

app = FastAPI()
client = CNPJob('SUA_API_KEY')

@app.get('/empresa/{cnpj}')
def get_empresa(cnpj: str):
    return client.lookup(cnpj)
```

---

## Opções avançadas

```python
client = CNPJob(
    api_key='SUA_API_KEY',
    base_url='https://api.cnpjob.com.br/api',  # padrão
)
```

---

## Compatibilidade

- Python 3.7+
- Django, Flask, FastAPI
- Scripts avulsos e notebooks Jupyter

Dependência única: [`requests`](https://pypi.org/project/requests/)

---

## Planos

| Plano    | Req/dia   | Req/min | Preço         |
|----------|-----------|---------|---------------|
| Free     | 10        | 2       | Grátis        |
| Pro      | 10.000    | 60      | R$ 99/mês     |
| Business | 100.000   | 300     | R$ 299/mês    |

[Ver todos os planos →](https://cnpjob.com.br#pricing)

---

## Links

- [Documentação completa](https://cnpjob.com.br/docs)
- [Portal do desenvolvedor](https://app.cnpjob.com.br)
- [Issues & suporte](https://github.com/esdrasjob/cnpjob/issues)

## Licença

MIT
