bacen-ifdata-scraper 0.0.5

Um sistema ETL ponta a ponta para extrair, transformar e carregar relatórios financeiros do portal IF.data do Banco Central do Brasil.

Bacen IF.data AutoScraper & Data Manager

Um sistema ETL ponta a ponta para extrair, transformar e carregar relatórios financeiros do portal IF.data do Banco Central do Brasil.

Este projeto automatiza a coleta, o processamento e a carga dos relatórios financeiros disponibilizados pelo Banco Central do Brasil através do portal IF.data. Diante do desafio de extrair dados valiosos de um formato de CSV não padronizado e de um processo de download manual, esta ferramenta utiliza Selenium para a automação da navegação e download, e scripts Python com Polars, DuckDB e dbt para a limpeza, transformação e modelagem dos dados.

O objetivo é transformar os dados brutos e inconsistentes do Bacen em um conjunto de dados limpo, organizado e pronto para análise, eliminando a necessidade de trabalho manual e garantindo a precisão das informações através de um pipeline ETL (Extract, Transform, Load) completo.

Sumário

• Bacen IF.data AutoScraper & Data Manager
  • Tecnologias Utilizadas
  • Funcionalidades Principais
  • Demonstração de Execução
  • Motivação
  • O Portal IF.Data
  • O Banco Central do Brasil
  • Objetivo Geral
  • Instalação
  • Uso do Pipeline
    • Extração (Scraping)
    • Limpeza (Cleaning)
    • Transformação (Transforming)
    • Carga (Loading)
    • Execução Padrão
  • Arquitetura do Sistema
  • Desafios e Aprendizados
  • Autor
  • Licença

Tecnologias Utilizadas

• Linguagem Principal: Python
• Gerenciador de Dependências e Build: uv
• Automação Web (Scraping): Selenium
• Manipulação de Dados: Polars
• Banco de Dados Analítico: DuckDB
• Validação de Dados: Pydantic, Pandera
• CLI: Fire
• Web Driver: GeckoDriver (para Firefox)

Funcionalidades Principais

• Extração (Extract): Realiza o download automático de todos os relatórios CSV do portal IF.data para um determinado período.
• Limpeza (Clean): Corrige arquivos CSV com formatação não-padrão, removendo cabeçalhos e informações consolidadas indesejadas.
• Transformação (Transform): Estrutura os dados limpos, aplicando schemas e transformações para prepará-los para análise.
• Carga (Load): Carrega os dados transformados em um banco de dados DuckDB para consulta e análise eficientes.
• Analytics (Model): Cria modelos dimencionais (Star Schema) prontos para BI usando dbt.
• Setup Simplificado: Suporte para instalação de dependências e execução com uv.
• Relatório de Execução: Gera um relatório ao final da execução do scraper com o total de arquivos baixados e o tempo de execução.

Demonstração de Execução

Veja o pipeline de automação em ação.

Clique para saber mais sobre o contexto do projeto

Motivação

Embora o Bacen disponibilize dados para o público em geral, com o objetivo de atender ao disposto na Lei 12.527 de 2011 (popularmente conhecida como Lei de Acesso à Informação), a forma como esses dados são apresentados exige a aplicação de métodos especializados para sua interpretação. É necessário empregar uma série de procedimentos e técnicas para extrair informações mais sofisticadas desses dados. A utilização de algoritmos e técnicas de tratamento e mineração de dados é fundamental nesse contexto. Essas abordagens permitem a extração de insights mais complexos dos dados fornecidos pelo Bacen, facilitando análises mais profundas e detalhadas sobre o sistema financeiro brasileiro.

O Portal IF.Data

O Portal IF.Data, criado pelo Banco Central do Brasil (Bacen), atende às exigências da Lei de Acesso à Informação (Lei 12.527 de 2011). Essa legislação obriga o poder público a publicar informações na internet de maneira acessível e em formatos compatíveis com processamento automatizado. O portal se caracteriza por ser interativo, armazenando e disponibilizando uma série de relatórios sobre instituições financeiras. Estes relatórios, que são atualizados trimestralmente, incluem dados abertos e podem ser visualizados online ou baixados em formato .csv.

No Portal IF.Data, é possível encontrar dados relacionados a contabilidade e capital, crédito, câmbio e segmentação das instituições financeiras. O portal abrange dados desde o ano 2000, e também oferece acesso a informações anteriores, de 1994 a 2000, embora em formatos diferentes. Para acessar os dados, o usuário pode selecionar no portal o trimestre de interesse, o tipo de instituição financeira e o relatório desejado.

O Banco Central do Brasil

O Banco Central do Brasil, frequentemente referido como Bacen, é a autoridade monetária principal do Brasil e desempenha um papel crucial na economia do país. Sua principal função é garantir a estabilidade do poder de compra da moeda nacional, o Real, e manter um sistema financeiro sólido e eficiente. Para isso, o Bacen regula a quantidade de dinheiro em circulação, administra as reservas internacionais do país, e atua como um regulador e supervisor do sistema financeiro, controlando e fiscalizando as instituições financeiras. Além disso, é responsável pela formulação e execução da política monetária, buscando controlar a inflação e influenciar as atividades econômicas. Como parte de suas funções, o Bacen também coleta e divulga dados econômicos e financeiros importantes, como os disponibilizados no Portal IF.Data, para garantir transparência e acesso à informação para o público em geral e para instituições financeiras.

Objetivo Geral

Este projeto visa aprimorar a coleta e o processamento de dados através da automação de atividades em navegadores web, utilizando a biblioteca Selenium. Selenium é uma ferramenta poderosa para a automação de browsers, permitindo a extração eficiente de dados de diversas fontes online. Após a coleta, o projeto focará no agrupamento e tratamento desses dados, organizando-os de maneira sistemática e coerente.

Essa abordagem não só economiza tempo e recursos, eliminando a necessidade de coleta manual de dados, mas também aumenta a precisão e a confiabilidade das informações obtidas. A fase de tratamento dos dados é crucial, pois envolve limpeza, normalização e consolidação de informações de múltiplas fontes, preparando-as para análises mais aprofundadas.

O resultado final será um conjunto de dados estruturado e de fácil acesso, proporcionando uma base sólida para análises futuras. Este conjunto de dados permitirá aos analistas e pesquisadores extrair insights valiosos e realizar avaliações detalhadas em seus respectivos campos de estudo ou indústrias. Além disso, o uso de automação e tratamento avançado de dados representa um passo importante na direção da modernização e eficiência dos processos de coleta e análise de dados.

Instalação

Primeiro, clone o repositório:

git clone https://github.com/alexcamargos/bacen-ifdata-scraper.git

cd bacen-ifdata-scraper

Para criar um ambiente virtual e instalar as dependências com uv:

# Crie o ambiente virtual
uv venv

# Ative o ambiente (Linux/macOS)
source .venv/bin/activate

# Ou no Windows (PowerShell)
.venv\Scripts\Activate.ps1

# Sincronize o ambiente com as dependências
uv sync

Configure as variáveis de ambiente do projeto para permitir execução do dbt via pipeline e standalone:

# Crie o arquivo de variáveis a partir do exemplo
cp .env.example .env

No Windows PowerShell:

Copy-Item .env.example .env

Edite o arquivo .env se necessário para ajustar os caminhos locais dos bancos DuckDB.

Observação: Antes de iniciar o processo de captura, certifique-se de que o GeckoDriver (para Firefox) esteja devidamente instalado e configurado no PATH do seu sistema.

Uso do Pipeline

O ifdata.py é a interface de linha de comando para controlar o pipeline ETL.

Extração (Scraping)

Para baixar os relatórios do portal IF.data, use a flag -s ou --scraper. O script irá navegar pelo portal, selecionar as instituições e relatórios, e baixar os arquivos CSV.

uv run ifdata.py -s

O script exibirá em tempo real quais arquivos estão sendo baixados. Ao final, um relatório detalhará o número total de arquivos baixados e o tempo de execução.

Limpeza (Cleaning)

Os arquivos CSV baixados do Bacen não seguem um padrão consistente, contendo múltiplos cabeçalhos e linhas de resumo. A etapa de limpeza corrige essas inconsistências. Use a flag -c ou --cleaner.

uv run ifdata.py -c

Transformação (Transforming)

Após a limpeza, os dados são transformados para um formato estruturado e analítico, aplicando schemas e preparando-os para serem carregados. Use a flag -t ou --transformer.

uv run ifdata.py -t

Carga (Loading)

Finalmente, os dados transformados são carregados em um banco de dados DuckDB para fácil consulta e análise. Use a flag -l ou --loader.

uv run ifdata.py -l

Analytics (Modeling)

Após a carga, a camada de analytics modela os dados em um Star Schema para Business Intelligence usando dbt. Use a flag -a ou --analytics.

uv run ifdata.py -a

dbt standalone com uv

Também é possível executar apenas a camada analytics sem chamar o pipeline:

cd src/bacen_ifdata/data_analytics
uv run --env-file ../../../.env dbt build

Execução seletiva de modelos e testes:

uv run --env-file ../../../.env dbt run -s view_resumo_financeiro_relatorios
uv run --env-file ../../../.env dbt test -s view_resumo_financeiro_relatorios

Execução Padrão

Se nenhum argumento for fornecido, o pipeline executará as etapas de limpeza e transformação por padrão:

uv run ifdata.py

Arquitetura do Sistema

Para informações detalhadas sobre a arquitetura do projeto, padrões de design utilizados, estrutura de diretórios e guia de contribuição, consulte a documentação de arquitetura.

Para entender o modelo de dados e o processo de transformação (Bronze -> Gold), veja a documentação do pipeline.

Desafios e Aprendizados

• Desafio: Construção de um Pipeline de Dados de Ponta a Ponta

  • Problema: As informações financeiras do Bacen, apesar de públicas, não são disponibilizadas através de uma API. Elas estão "presas" em um portal web que exige navegação manual e os arquivos para download estão em um formato inconsistente e "sujo". Para realizar qualquer análise séria e replicável, era necessário um sistema que superasse essas barreiras.
  • Solução: Projetei e implementei um pipeline de dados em quatro etapas (ETL): 1. Extração (Extract): Um scraper automatizado com Selenium que simula a interação humana com o portal IF.data, navegando pelos menus e realizando o download sistemático de todos os relatórios necessários. 2. Limpeza (Clean): Um módulo de pré-processamento que recebe os arquivos brutos e corrige a formatação não-padrão. 3. Transformação (Transform): Um módulo que estrutura os dados limpos usando Polars, aplicando schemas de dados com Pydantic para garantir a consistência e o formato correto para análise. 4. Carga (Load): Um módulo que carrega os dados transformados em um banco de dados DuckDB, criando tabelas otimizadas para consultas analíticas rápidas.
  • Aprendizado: Este projeto foi um exercício prático completo de Engenharia de Dados (ETL - Extract, Transform, Load). Aprendi a decompor um problema complexo em etapas lógicas, selecionar as ferramentas adequadas para cada fase (Selenium, Polars, DuckDB) e a construir um fluxo de trabalho automatizado e confiável. O resultado final não é apenas um conjunto de dados, mas um sistema replicável que transforma uma fonte de dados manual e não confiável em um ativo de informação pronto para análise.

• Desafio: Parsing de CSVs Não-Padronizados

  • Problema: Os arquivos CSV disponibilizados pelo Bacen não seguem o padrão convencional. Eles incluem múltiplos cabeçalhos, linhas de resumo e agrupamentos de dados dentro do mesmo arquivo, tornando a importação direta com bibliotecas padrão inviável.
  • Solução: Desenvolvi um script de processamento em Python que lê cada arquivo linha por linha. Utilizando lógica condicional, o script identifica e ignora os cabeçalhos secundários e as linhas de resumo. Ele localiza o cabeçalho principal correto e extrai apenas as linhas de dados pertencentes às instituições financeiras, reescrevendo um novo arquivo CSV limpo e bem formatado.
  • Aprendizado: Este desafio aprofundou minhas habilidades em manipulação de arquivos e parsing de texto em baixo nível. Aprendi a importância de não confiar cegamente em formatos de arquivo e a desenvolver soluções robustas para lidar com dados sujos e inconsistentes, uma habilidade fundamental em qualquer projeto de engenharia ou ciência de dados.

• Desafio: Modelagem Dimensional para BI a Partir de Dados Heterogêneos

  • Problema: Com os dados já carregados no DuckDB (camada Silver), o próximo desafio era transformá-los em um formato adequado para análise de Business Intelligence. Os dados Silver, embora limpos, apresentavam diversos obstáculos para análises transversais:
    • Fragmentação por tipo de instituição: Ativos, passivos e resultados estavam em tabelas separadas por tipo (Conglomerados Prudenciais, Financeiros, Instituições Individuais), impossibilitando comparações diretas entre o sistema financeiro como um todo.
    • Ausência de chaves padronizadas: Não existiam chaves surrogadas ou dimensões compartilhadas; cada tabela operava de forma isolada.
    • Inconsistência de schemas entre períodos: Relatórios de diferentes épocas possuíam estruturas distintas (colunas extras ou ausentes), exigindo tratamento especial para unificação temporal.
    • Dados desnormalizados e repetidos: Informações de instituições (nome, código, segmento) eram replicadas em cada tabela de fato, gerando redundância e risco de inconsistência.
  • Solução: Projetei e implementei um Star Schema (Esquema Estrela) usando dbt sobre DuckDB, criando uma camada Gold analítica:
    1. Dimensões unificadas (dim_instituicao): Consolidei instituições de 3 fontes distintas em uma única dimensão com chave surrogada (MD5), permitindo análises transversais independentes do tipo de instituição.
    2. Dimensão de tempo (dim_tempo): Criei uma dimensão temporal com chave numérica (YYYYMMDD), extraindo ano, trimestre e mês para facilitar filtros e agregações sem funções de data complexas.
    3. Fatos compostos (fato_balanco_patrimonial): Unifiquei Ativos e Passivos via FULL OUTER JOIN, utilizando COALESCE para resiliência contra dados ausentes, consolidando o balanço patrimonial completo em uma única tabela.
    4. Dimensões estáticas via Seeds: Mapeei categorias de crédito, risco e localização como arquivos CSV (Seeds do dbt), garantindo consistência e versionamento dessas tabelas de referência.
  • Aprendizado: Este desafio consolidou minha experiência em modelagem dimensional (Kimball) e no uso de dbt como ferramenta de transformação analítica. Aprendi que a construção de um Data Warehouse eficiente não se resume a mover dados — exige decisões conscientes sobre granularidade, unificação de entidades e design de chaves. A separação clara entre Silver (dados operacionais) e Gold (dados analíticos) provou ser essencial para manter a rastreabilidade e permitir reprocessamento sem impactar a ingestão.

Autor

Alexsander Lopes Camargos

Engenheiro de dados e inteligência artificial focado em soluções de alta performance para o mercado financeiro. Este projeto reflete meu interesse em automação de processos, engenharia de dados e análise financeira.

Fique à vontade para entrar em contato para discussões técnicas, sugestões ou oportunidades:

Licença

Este projeto está sob a licença MIT.