{"id":13405683,"url":"https://github.com/turicas/socios-brasil","last_synced_at":"2025-05-15T10:00:33.713Z","repository":{"id":37663432,"uuid":"119871139","full_name":"turicas/socios-brasil","owner":"turicas","description":"Captura os dados de sócios das empresas brasileiras na Receita Federal e exporta para um formato legível por humanos","archived":false,"fork":false,"pushed_at":"2025-04-11T05:51:42.000Z","size":311,"stargazers_count":583,"open_issues_count":12,"forks_count":132,"subscribers_count":50,"default_branch":"master","last_synced_at":"2025-05-10T14:12:12.459Z","etag":null,"topics":["brazil","data-driven-journalism","datascience","economic-data","empresas","hacktoberfest","opendata","python","socios"],"latest_commit_sha":null,"homepage":"https://brasil.io/dataset/socios-brasil","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/turicas.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"custom":"https://apoia.se/brasilio"}},"created_at":"2018-02-01T17:43:14.000Z","updated_at":"2025-04-24T16:38:45.000Z","dependencies_parsed_at":"2023-11-15T20:28:46.334Z","dependency_job_id":"f4c36a2f-ea69-40ea-b01f-2131d00de5e3","html_url":"https://github.com/turicas/socios-brasil","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turicas%2Fsocios-brasil","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turicas%2Fsocios-brasil/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turicas%2Fsocios-brasil/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turicas%2Fsocios-brasil/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/turicas","download_url":"https://codeload.github.com/turicas/socios-brasil/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254319715,"owners_count":22051072,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["brazil","data-driven-journalism","datascience","economic-data","empresas","hacktoberfest","opendata","python","socios"],"created_at":"2024-07-30T19:02:08.389Z","updated_at":"2025-05-15T10:00:32.663Z","avatar_url":"https://github.com/turicas.png","language":"Python","funding_links":["https://apoia.se/brasilio"],"categories":["Python"],"sub_categories":[],"readme":"# Sócios de Empresas Brasileiras\n\nScript que baixa todos os dados de sócios das empresas brasileiras [disponíveis\nno site da Receita\nFederal](https://receita.economia.gov.br/orientacao/tributaria/cadastros/cadastro-nacional-de-pessoas-juridicas-cnpj/dados-publicos-cnpj),\nextrai, limpa e converte para CSV. Para entender melhor sobre quais dados estão\ndisponíveis, consulte a [história desse dataset](historia-do-dataset.md).\n\n\n## Licença\n\nA licença do código é [LGPL3](https://www.gnu.org/licenses/lgpl-3.0.en.html) e\ndos dados convertidos [Creative Commons Attribution\nShareAlike](https://creativecommons.org/licenses/by-sa/4.0/). Caso utilize os\ndados, **cite a fonte original e quem tratou os dados**, como: **Fonte: Receita\nFederal do Brasil, dados tratados por Álvaro\nJusten/[Brasil.IO](https://brasil.io/)**. Caso compartilhe os dados, **utilize\na mesma licença**.\n\n\n## Dados\n\n### Entrada\n\nOs dados publicados pela Receita Federal do Brasil contemplam as seguintes\ntabelas:\n\n- Cadastro das empresas, incluindo CNPJ, razão social, nome fantasia, endereço,\n  CNAE fiscal e outros;\n- Cadastro de sócios, contendo CNPJ da empresa, documento do sócio, nome do\n  sócio e outros;\n- CNAEs secundários para cada CNPJ.\n\nOs dados originalmente estão em um formato [fixed-width\nfile](http://www.softinterface.com/Convert-XLS/Features/Fixed-Width-Text-File-Definition.htm)\ne cada linha possui um tipo diferente de registro (empresa, sócio, CNAE\nsecundária, header ou trailler), que dificulta qualquer tipo de análise, sendo\nnecessária a conversão para formatos mais amigáveis.\n\nO campo de qualificação do sócio foi definido com base [na tabela\ndisponibilizada pela Receita\nFederal](http://idg.receita.fazenda.gov.br/orientacao/tributaria/cadastros/cadastro-nacional-de-pessoas-juridicas-cnpj/Qualificacao_socio.pdf)\ne está disponível no arquivo\n[`qualificacao-socio.csv`](qualificacao-socio.csv). Em breve também teremos\narquivos com os nomes dos CNAEs e situação cadastral ([veja mais detalhes\naqui](https://github.com/turicas/socios-brasil/issues/20)).\n\n\n### Saída\n\nAlém de extrair os dados do arquivo origingal, o script gera uma nova tabela\ncontendo as empresas que são sócias de outras empresas (para facilitar buscas\nde *holdings*).\n\nCaso você não queira/possa rodar o script, **[acesse diretamente os dados\nconvertidos no Brasil.IO](https://brasil.io/dataset/socios-brasil)**.\n\nSe esse programa e/ou os dados resultantes foram úteis a você ou à sua empresa,\nconsidere [fazer uma doação ao projeto Brasil.IO](https://brasil.io/doe), que é\nmantido voluntariamente.\n\nComo resultado temos os seguintes arquivos:\n\n- `empresa.csv.gz`: cadastro das empresas;\n- `socio.csv.gz`: cadastro dos sócios;\n- `cnae-secundaria.csv.gz`: lista de CNAEs secundárias;\n- `holding.csv.gz`: cadastro das empresas que são sócias de outras\n  empresas (é o arquivo `socio.csv.gz` filtrado por sócios do tipo PJ).\n\nAlém disso, os arquivos contidos nas pastas [schema](schema/) e\n[schema-full](schema-full/) podem te ajudar a importar os dados para um banco\nde dados (veja comandos para [SQLite](#sqlite) e [PostgreSQL](#postgresql)\nabaixo).\n\n\u003e Nota 1: a extensão `.gz` quer dizer que o arquivo foi compactado usando gzip.\n\u003e Para descompactá-lo execute o comando `gunzip arquivo.gz` (**não é necessário\n\u003e descompactá-los** caso você siga as instruções de importação em\n\u003e [SQLite](#sqlite) e [PostgreSQL](#postgresql)).\n\n\u003e Nota 2: a codificação de caracteres original é ISO-8859-15, mas o script gera\n\u003e os arquivos CSV em UTF-8.\n\n\u003e Nota 3: se você estava usando os dados no formato anterior, veja como\n\u003e converter os novos para o padrão antigo no arquivo\n\u003e `sql/04-create-old-views.sql`.\n\n\n### Privacidade\n\nPara garantir a privacidade, evitar SPAM e publicar apenas dados corretos, o\nscript deleta/limpa algumas colunas com informações sensíveis ou incorretas.\nEssa é a forma padrão de funcionamento para não facilitar a exposição desses\ndados. Os dados censurados são:\n\n- Na tabela `empresa`:\n  - Deletadas as colunas `codigo_pais` e `nome_pais`, pois os dados contidos\n    nelas estão incorretos;\n  - Deletada a coluna `correio_eletronico`, para evitar SPAM;\n- Na tabela `socio`:\n  - Deletadas as colunas `codigo_pais` e `nome_pais`, pois os dados contidos\n    nelas estão incorretos;\n  - As colunas `complemento`, `ddd_fax`, `ddd_telefone_1`, `ddd_telefone_2`,\n    `descricao_tipo_logradouro`, `logradouro`, `numero` terão seus dados\n    deletados (ficarão em branco) para empresas que são empreendedores\n    individuais (MEI, EI, EIRELI etc.) e, provavelmente, correspondem aos dados\n    do sócio (endereço residencial, por exemplo);\n  - Para os casos de empresas individuais que constarem o CPF na razão social\n    (como é comum no caso de MEIs), o CPF será deletado.\n\nCaso queira rodar o script sem o modo censura, altere o script `run.sh` e\nadicione a opção `--no_censorship` para o script `extract_dump.py`.\n\n\n### Dados auxiliares\n\n- Cadastro Nacional de Atividades Empresariais (CNAE): existe um spider que\n  baixa os metadados das [atividades empresariais (CNAEs) do site do\n  IBGE](https://cnae.ibge.gov.br). Veja a função `extract_cnae` no arquivo\n  `run.sh`, ela baixará os dados para as versões 1.0, 1.1, 2.0, 2.1, 2.2 e 2.3\n  e salvará em `data/output`. **Nota**: esse script será melhorado/alterado,\n  veja a [issue #36](https://github.com/turicas/socios-brasil/issues/36).\n- Natureza jurídica: o arquivo `data/natureza-juridica.csv` contém o cadsatro\n  de naturezas jurídicas das empresas (coluna `codigo_natureza_juridica` da\n  tabela `empresa`).  Esse arquivo é gerado pelo script `natureza_juridica.py`,\n  que baixa os [dados do site da Receita\n  Federal](https://www.receita.fazenda.gov.br/pessoajuridica/cnpj/tabelas/natjurqualificaresponsavel.htm).\n\n\n## Rodando\n\n### Instalando as Dependências\n\nEsse script depende de Python 3.7, de algumas bibliotecas e do software\n[aria2](https://aria2.github.io/). Depois de instalar o Python 3.7 e o aria2,\ninstale as bibliotecas executando:\n\n```bash\npip install -r requirements.txt\n```\n\n### Executando\n\nEntão basta executar o script `run.sh` para baixar os arquivos necessários e\nfazer as conversões:\n\n```bash\n./run.sh\n```\n\nVocê poderá rodar etapas separadamente também (leia o script [run.sh](run.sh)\npara mais detalhes).\n\n#### Agilizando o Download\n\n[O servidor da Receita Federal onde os dados estão hospedados é **muito\nlento**](https://twitter.com/turicas/status/1114185311372873729) e, por isso, o\n[Brasil.IO](https://brasil.io/) disponibiliza um *mirror* de onde o download\npode ser feito mais rapidamente. Para executar o script baixando os dados do\n*mirror*, execute:\n\n```bash\n./run.sh --use-mirror\n```\n\n\u003e Nota: os *mirrors* do Brasil.IO ainda estão em fase de testes e não é\n\u003e garantido que estejam sempre atualizados.\n\n\n## Importando em Bancos de Dados\n\nDepois de executar o script ou baixar os dados já convertidos, o ideal é\nimportá-los em um banco de dados para facilitar consultas. Com a [interface de\nlinha de comando da rows](http://turicas.info/rows/cli/) é possível importá-los\nrapidamente em bancos SQLite e PostgreSQL.\n\n\u003e Nota 1: depois de importar os dados em um banco de dados é recomendável a\n\u003e criação de índices para agilizar as consultas. Um índice bem comum é na\n\u003e coluna `cnpj` (de todas as tabelas), para facilitar encontrar uma determinada\n\u003e empresa, seus sócios e CNAEs secundários através do CNPJ. Exemplo:\n\u003e `CREATE INDEX IF NOT EXISTS idx_empresa_cnpj ON empresa (cnpj);`. Veja o\n\u003e arquivo [sql/create-indexes.sql](sql/create-indexes.sql) para uma lista de\n\u003e índices sugeridos; veja também os outros arquivos da pasta `sql/` para\n\u003e criação de tabelas auxiliares, chaves primárias e estrangeiras e o arquivo\n\u003e `import-postgresql.sh` para automatizar o processo de importação e criação\n\u003e dos índices.\n\n\u003e Nota 2: caso utilize a opção `--no_censorship`, utilize os arquivos da pasta\n\u003e `schema-full` em vez da pasta `schema`, pois a versão \"sem censura\" possui\n\u003e mais colunas.\n\n### SQLite\n\nInstale a CLI da rows e a versão de desenvolvimento da biblioteca rodando\n(requer Python 3.7+):\n\n```bash\npip install rows[cli]\npip install -U https://github.com/turicas/rows/archive/develop.zip\n```\n\nAgora, com os arquivos na pasta `data/output` basta executar os seguintes\ncomandos:\n\n```bash\nDB_NAME=\"data/output/socios-brasil.sqlite\"\nrows csv2sqlite --schemas=schema/empresa.csv data/output/empresa.csv.gz \"$DB_NAME\"\nrows csv2sqlite --schemas=schema/holding.csv data/output/holding.csv.gz \"$DB_NAME\"\nrows csv2sqlite --schemas=schema/socio.csv data/output/socio.csv.gz \"$DB_NAME\"\nrows csv2sqlite --schemas=schema/cnae-secundaria.csv data/output/cnae-secundaria.csv.gz \"$DB_NAME\"\n```\n\nPegue um café, aguarde alguns minutos e depois desfrute do banco de dados em\n`data/output/socios-brasil.sqlite`. :)\n\n\n### PostgreSQL\n\nInstale a CLI da rows, as dependências do PostgreSQL e a versão de\ndesenvolvimento da biblioteca rodando (requer Python 3.7+):\n\n```bash\npip install rows[cli]\npip install rows[postgresql]\npip install -U https://github.com/turicas/rows/archive/develop.zip\n```\n\nAgora, com os arquivos na pasta `data/output` basta executar os seguintes\ncomandos (não esqueça de preencher a variável `POSTGRESQL_URI` corretamente):\n\n```bash\nPOSTGRESQL_URI=\"postgres://\u003cuser\u003e:\u003cpass\u003e@\u003chost\u003e:\u003cport\u003e/\u003cdbname\u003e\"  # PREENCHA!\nrows pgimport --schema=schema/empresa.csv data/output/empresa.csv.gz $POSTGRESQL_URI empresa\nrows pgimport --schema=schema/socio.csv data/output/empresa-socia.csv.gz $POSTGRESQL_URI empresa_socia\nrows pgimport --schema=schema/socio.csv data/output/socio.csv.gz $POSTGRESQL_URI socio\nrows pgimport --schema=schema/cnae-secundaria.csv data/output/cnae-secundaria.csv.gz $POSTGRESQL_URI cnae_secundaria\n```\n\nPegue um café, aguarde alguns minutos e depois desfrute do banco de dados em\n`$POSTGRESQL_URI`. :)\n\n\n## Outras Implementações\n\nEm R:\n\n- [qsacnpj](https://github.com/georgevbsantiago/qsacnpj/)\n- [RFBCNPJ](http://curso-r.com/blog/2018/05/13/2018-05-13-rfbcnpj/)\n\nEm Python:\n\n- [CNPJ-full](https://github.com/fabioserpa/CNPJ-full)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fturicas%2Fsocios-brasil","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fturicas%2Fsocios-brasil","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fturicas%2Fsocios-brasil/lists"}