redeshub / receita Goto Github PK

Este repositório busca facilitar o acesso às informações publicadas pela Receita Federal do Brasil sobre o Cadastro Nacional de Pessoa Jurídica, na medida em que fornece uma solução para a criação de uma base de dados relacional local unificada para consultas.

Dessa forma, é possível realizar análises mais profundas com os dados que estão acessíveis através DESTE SERVIÇO. Caso o serviço deixe de estar online ou mude de endereço, o código deverá refletir as alterações. O serviço contém uma listagem com arquivos comprimidos tipo .ZIP que contém, cada um, um arquivo tabular do tipo .CSV (comma-separated-values), representando os dados modelados disponíveis para as seguintes entidades:

1. Empresas
2. Estabelecimentos
3. Sócios
4. CNAEs (Cadastro Nacional de Atividade Empresarial)
5. Simples
6. Municípios
7. Países
8. Natureza (Jurídica)
9. Qualificações (dos Sócios)
10. Motivo (da situação cadastral)

Para cada entidade, pode haver um ou mais arquivos .ZIP correspondentes ao total de informações disponíveis na base, ordenados em sequência. A relação entre as entidades encontra-se descrita textualmente através do Arquivo de Layout) fornecido no próprio endereço e datado de 2018.

As regras de negócio do Cadastro Nacional de Pessoa Jurídica (CNPJ) podem ser compreendidas de modo simplificado como a representação de um empreendimento do mundo real através de uma entidade do tipo empresa, que é única e recebe da Receita Federal um código de 8 dígitos conhecido como o CNPJ base, ou CNPJ básico.

Além do CNPJ base, a empresa, quando criada, possui apenas o estabelecimento matriz, que recebe um código de 4 dígitos, conhecido como ordem do CNPJ, que era normalmente sequencial, iniciando em 0001. Além disso, o estabelecimento recebe um terceiro código de 2 dígitos conhecido como dígito verificador, gerado através de um algoritmo da Receita que calcula uma espécie de código hash utilizando a combinação cnpj base e ordem, gerando assim o dígito verificador.

Assim, uma empresa pode possuir múltiplos estabelecimentos, todos compartilhando o mesmo cnpj base, entretanto cada estabelecimento com um código de ordem individual e um dígito verificador correspondente. O estabelecimento possui informações complementares às informações de empresa, definidos pelas outras entidades a que chamaremos de dimensões complementares. Segue abaixo a sugestão adotada para a modelagem das tabelas no projeto:

Este projeto está dividido portanto em três fases fundamentais, de acordo com o fluxo normal de processos de ETL (Extract, Transform, Load). Neste escopo, o fluxo pode ser definido como:

0. Preparar o banco de dados PostgreSQL executando o arquivo inicial de configuração do banco;
1. Verificar se os arquivos foram atualizados no servidor; Baixar os arquivos do serviço online, salvando os arquivos antigos em diretório local; Descompactar os arquivos .CSV de dentro dos arquivos .ZIP baixados;
2. Carregar os arquivos tabulares como dados brutos estruturando-os em tabelas no banco de dados PostgreSQL;
3. Processar os dados disponíveis nas tabelas, realizando validação, formatação e limpeza, produzindo um documento único chamado resposta_cnpj que consolida em uma tabela os dados de CNPJ de estabelecimentos e empresas, bem como em outra chamada resposta_socio que consolida os dados do quadro de sócios, que é aquilo que está disponibilizado para o usuário final através dos pontos de acesso de estabelecimentos e de sócios da API do Querido Diário.

Para instalar o projeto, utilize Python 3+. Recomenda-se a criação e ativação de um ambiente virtual python.

$ python3 -m venv meu_ambiente
$ source meu_ambiente/bin/activate

Para instalar as dependências, basta acessar o diretório do projeto e instalar com pip:

$ cd receita
$ pip3 install -r requirements.txt

Caso aconteça algum erro de instalação das dependências, verifique se está utilizando Python3 ou o ambiente virtual correto, se está no diretório raiz do projeto e se houve algum erro em um dos pacotes, tentando abordar o erro pontual que causou o problema de instalação.

A escolha de SGBD para o projeto é a alternativa PostgreSQL. Uma vez instalado o cliente psql e inicializado o servidor postgres na sua máquina, realize a criação das tabelas e relações do banco de dados PostgreSQL local "localhost" via linha de comando (shell/bash/etc), dando permissão a um usuário chamado "postgres" e a uma base chamada "qd_receita". Basta seguir as orientações no cabeçalho do próprio arquivo startdb.sql:

$ psql -U postgres -d qd_receita -h localhost -f sql/startdb.sql

Para executar a partir do diretório principal (raiz) do projeto, basta:

Acessar o diretório de tarefas do projeto:

$ cd tasks/

Acessar o arquivo e alterar as informações de acesso ao banco (usuário, senha, endereço, etc) de acordo com a sua especificação.

Chamar a execução do python via linha de comando:

i) Executa o script que baixa os arquivos .ZIP, caso sejam uma versão mais nova dos dados disponíveis, evitando assim baixar uma versão já disponível em disco. Caso seja uma versão mais nova, a versão anterior em disco é movida para outro diretório e os novos arquivos são baixados.

$ python3 download.py

ii) Realiza a extração dos arquivos tabulares de dentro dos arquivos .ZIP, carregando os dados em memória por bloco para cada entidade e persistindo a informação original (raw) em tabelas do banco de dados.

$ python3 ingest.py

iii) Realiza as operações de validação, formatação e limpeza dos dados brutos, salvando um único registro na tabela resposta_cnpj para cada estabelecimento, com todas as informações das tabelas complementares sintetizadas no registro, bem como um registro na tabela resposta_socios para cada sócio de um determinado CNPJ.

$ python3 process_cnpjs.py

Os dados da RFB, após processados pela OKBR utilizando este fluxo, podem ser acessados online gratuitamente através dos seguintes pontos de acesso da API pública do Querido Diário:

• Endpoint de estabelecimentos
• Endpoint de sócios