Metadata-Version: 2.4
Name: simplesnacional
Version: 0.1.5
Summary: Biblioteca e CLI para consulta e atualização da base de dados do Simples Nacional.
Author-email: David Silva <david.emery.silva@gmail.com>
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Requires-Dist: rich
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# Simples Nacional Lib
<div align="center">
  <img alt="image" src="https://github.com/user-attachments/assets/b4a11a93-2f85-431c-86d9-ed0f647f241f" />
</div>

<p align="center">
  <img src="https://static.pepy.tech/badge/simplesnacional" />
  <img src="https://img.shields.io/pypi/v/simplesnacional" />
  <img src="https://img.shields.io/github/stars/DaavidSiilva/simplesnacional" />
</p>


Biblioteca e CLI em Python para consulta e atualização da base de dados pública do Simples Nacional (CNPJs).

## Instalação

Do PyPI:

```bash
pip install simplesnacional
```

Ou a partir do código-fonte:

```bash
pip install .
```

Para desenvolvimento (inclui o pytest):

```bash
pip install -e ".[dev]"
pytest
```

## Uso via Linha de Comando (CLI)

Após a instalação, o comando `simplesnacional` estará disponível no seu terminal.
Também funciona via `python -m simplesnacional`.

### 1. Atualizar a Base de Dados
Antes de realizar consultas, é necessário baixar e atualizar a base de dados local. O comando abaixo verifica se existe uma nova versão no site da Receita Federal e realiza o download e importação se necessário.

```bash
simplesnacional atualizar
```
Este processo pode demorar alguns minutos dependendo da velocidade da internet e do processamento, pois a base é volumosa.

### 2. Verificar Status
Para ver informações sobre a base de dados local, como a data de referência e o total de registros importados:

```bash
simplesnacional info
```

### 3. Consultar um CNPJ
Para consultar os dados do Simples Nacional de um CNPJ específico:

```bash
simplesnacional consultar 00000000000191
```
Ou com formatação:
```bash
simplesnacional consultar 00.000.000/0001-91
```

**Saída Exemplo:**
```text
Dados do CNPJ: 00000000
+-----------------------+------------+
|                 Campo | Valor      |
+-----------------------+------------+
|         Opção Simples | S          |
|    Data Opção Simples | 20070701   |
| Data Exclusão Simples |            |
|             Opção MEI | N          |
|        Data Opção MEI |            |
|     Data Exclusão MEI |            |
+-----------------------+------------+
```

### 4. Subir a API HTTP

Sobe um servidor local (somente leitura, sem dependências extras) para consultar
a base por HTTP — útil para integrar com outros sistemas ou com o navegador:

```bash
simplesnacional serve                    # http://127.0.0.1:5000
simplesnacional serve --port 8080        # outra porta
simplesnacional serve --host 0.0.0.0     # expõe na rede local
simplesnacional serve --cors             # libera CORS para chamadas do navegador
simplesnacional serve --strict-404       # 404 para CNPJ ausente
```

`simplesnacional server` continua funcionando como alias.

**Rotas:**

| Método | Rota                       | Descrição                                     |
| ------ | -------------------------- | --------------------------------------------- |
| GET    | `/`                        | Índice da API (HTML no navegador, JSON fora)  |
| GET    | `/health`                  | Estado do servidor e da base local            |
| GET    | `/campos`                  | Lista os campos disponíveis                   |
| GET    | `/api/{cnpj}`              | Dados do CNPJ em JSON                         |
| GET    | `/api/{cnpj}/{campo}`      | Valor de um único campo (texto puro)          |
| GET    | `/api/{cnpj}?fields=a,b`   | Vários campos separados por `;`               |
| GET    | `/api/{cnpj}?format=csv`   | Dados em CSV                                  |
| GET    | `/json/{cnpj}`             | Alias de `/api/{cnpj}`                        |

O CNPJ pode ir com ou sem pontuação, e `?format=text` devolve o resumo em texto puro.

```bash
curl http://127.0.0.1:5000/api/00.000.000/0001-91
```

```json
{
  "status": "sucesso",
  "cnpj": "00000000",
  "opcao_simples": "S",
  "data_opcao_simples": "01/07/2007",
  "data_exclusao_simples": "",
  "opcao_mei": "N",
  "data_opcao_mei": "",
  "data_exclusao_mei": ""
}
```

Códigos de status:

| Status | Quando acontece                                                        |
| ------ | ---------------------------------------------------------------------- |
| `200`  | Consulta respondida — inclusive `status: "nao_encontrado"`             |
| `400`  | CNPJ com menos de 8 dígitos                                            |
| `404`  | Rota desconhecida (ou CNPJ ausente, com `--strict-404`)                |
| `503`  | Base local ausente (rode `simplesnacional atualizar`)                  |

O arquivo da Receita lista **apenas optantes**, então um CNPJ sem linha na base
significa *não optante* — por isso o padrão é `200` com
`"status": "nao_encontrado"` e `"opcao_simples": "N"`. Use `--strict-404` se
preferir semântica REST estrita.

```json
{
  "status": "nao_encontrado",
  "cnpj": "99999999",
  "opcao_simples": "N",
  "data_opcao_simples": "",
  "data_exclusao_simples": "",
  "opcao_mei": "N",
  "data_opcao_mei": "",
  "data_exclusao_mei": ""
}
```

## Usando no Excel

### `WEBSERVICE()` — um campo por célula

O `WEBSERVICE()` devolve texto puro (não entende JSON), então use a rota de
campo único — ela responde **só o valor**, sem aspas nem quebra de linha:

```excel
=WEBSERVICE("http://127.0.0.1:5000/api/81099491003863/opcao_simples")
```

Resultado na célula: `N`

Campos disponíveis (veja também `GET /campos`):

| Campo                    | Exemplo      |
| ------------------------ | ------------ |
| `cnpj`                   | `81099491`   |
| `opcao_simples`          | `S` / `N`    |
| `data_opcao_simples`     | `01/07/2007` |
| `data_exclusao_simples`  | ``           |
| `opcao_mei`              | `S` / `N`    |
| `data_opcao_mei`         | ``           |
| `data_exclusao_mei`      | ``           |

Uma fórmula por campo, referenciando o CNPJ da própria planilha:

```excel
=WEBSERVICE("http://127.0.0.1:5000/api/" & $A2 & "/opcao_simples")
```

Para vários campos numa célula só (Excel 365, com `TEXTSPLIT`):

```excel
=TEXTSPLIT(WEBSERVICE("http://127.0.0.1:5000/api/" & $A2 & "?fields=opcao_simples,opcao_mei"), ";")
```

> O `WEBSERVICE()` limita a URL a 255 caracteres e devolve `#VALUE!` em respostas
> que não sejam `2xx` — por isso CNPJ ausente da base responde `200` com `N`
> (não optante) em vez de `404`. Evite máscara no CNPJ: use só os dígitos.

### Power Query — a ficha inteira

`Dados → Obter Dados → De Outras Fontes → Da Web` e cole a URL. Para virar tabela:

```m
let
    Json  = Json.Document(Web.Contents("http://127.0.0.1:5000/api/81099491003863")),
    Tabela = Record.ToTable(Json)
in
    Tabela
```

Ou consuma direto o CSV, que o Power Query já lê como tabela:

```m
let
    Fonte = Csv.Document(
        Web.Contents("http://127.0.0.1:5000/api/81099491003863?format=csv"),
        [Delimiter = ";", Encoding = 65001]
    ),
    ComCabecalho = Table.PromoteHeaders(Fonte, [PromoteAllScalars = true])
in
    ComCabecalho
```

## Uso como Biblioteca Python

Você pode utilizar a biblioteca diretamente em seu código Python para realizar consultas.

```python
from simplesnacional import consulta

# Realizar a consulta
# O CNPJ pode ser passado como string (com ou sem pontuação) ou inteiro
dados = consulta("00.000.000/0001-91")

if dados:
    print(f"CNPJ Base: {dados.cnpj_base}")
    print(f"Optante Simples: {dados.opcao_simples}")
    print(f"Data Opção: {dados.data_opcao_simples}")
    print(f"Optante MEI: {dados.opcao_mei}")
else:
    print("CNPJ não encontrado na base local.")
```

### Estrutura do Objeto Retornado
A função `consulta` retorna um objeto `DadosSimples` com os seguintes atributos:

- `cnpj_base`: Os 8 primeiros dígitos do CNPJ
- `opcao_simples`: Indicador de opção pelo Simples ('S' ou 'N')
- `data_opcao_simples`: Data da opção pelo Simples
- `data_exclusao_simples`: Data da exclusão do Simples (se houver)
- `opcao_mei`: Indicador de opção pelo MEI ('S' ou 'N')
- `data_opcao_mei`: Data da opção pelo MEI
- `data_exclusao_mei`: Data da exclusão do MEI (se houver)

O método `to_dict()` devolve todos esses campos em um dicionário pronto para
serializar em JSON.

### Servidor embutido

O servidor HTTP também pode ser iniciado por código:

```python
from simplesnacional.server import run_server

run_server(host="127.0.0.1", port=5000, cors=False)
```

## Licença

MIT License

### Aviso Legal e Isenção de Responsabilidade

Este software é um projeto **independente e de código aberto**.

Esta biblioteca e CLI **não possuem qualquer vínculo, afiliação, endosso ou parceria** com a Receita Federal do Brasil ou qualquer outra entidade governamental.

O objetivo deste projeto é estritamente facilitar o acesso técnico e a consulta automatizada à base de dados pública do Simples Nacional. Embora a ferramenta utilize dados públicos oficiais, ela não substitui os canais oficiais de consulta para fins legais, fiscais ou tributários.
