Simples Nacional Lib

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

Instalação

Do PyPI:

pip install simplesnacional

Ou a partir do código-fonte:

pip install .

Para desenvolvimento (inclui o pytest):

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.

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:

simplesnacional info

3. Consultar um CNPJ

Para consultar os dados do Simples Nacional de um CNPJ específico:

simplesnacional consultar 00000000000191

Ou com formatação:

simplesnacional consultar 00.000.000/0001-91

Saída Exemplo:

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:

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.

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

{
  "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.

{
  "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:

=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:

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

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

=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:

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:

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.

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:

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.