brFinance v2 é uma biblioteca Python projetada para facilitar o acesso e a extração de dados financeiros de empresas brasileiras listadas na B3 e reguladas pela CVM.
Com ela, você pode acessar facilmente:
- Demonstrativos Financeiros (ITR e DFP):
- Balanço Patrimonial (Ativo e Passivo)
- Demonstração do Resultado (DRE)
- Demonstração do Resultado Abrangente (DRA)
- Demonstração do Fluxo de Caixa (DFC)
- Demonstração das Mutações do Patrimônio Líquido (DMPL)
- Demonstração de Valor Adicionado (DVA)
- Dados Cadastrais da CVM e B3
- Informações sobre Emissores e Instrumentos Financeiros
Você pode instalar a biblioteca diretamente do PyPI:
pip install brfinance_v2Abaixo está um exemplo completo de como utilizar a biblioteca para buscar empresas, encontrar documentos e baixar relatórios financeiros.
A classe principal para interação é a CVMBackend.
from brfinance_v2 import CVMBackend
from datetime import date
import pandas as pd
# Inicializa o cliente
cvm_client = CVMBackend()Obtenha um dicionário com todas as empresas registradas e seus respectivos códigos CVM.
# Retorna dict {codigo_cvm: nome_empresa}
cvm_codes = cvm_client.get_cvm_codes()
# Exemplo: Imprimir o código da PETROBRAS
print("Código da PETROBRAS:", {k: v for k, v in cvm_codes.items() if 'PETROBRAS' in v})Você pode buscar por documentos específicos usando códigos CVM e intervalos de datas.
# Parâmetros de busca
start_date = date(2023, 1, 1)
end_date = date.today()
cvm_codes_list = ['9512'] # Código CVM da PETROBRAS (Exemplo)
categories = ["EST_4", "EST_3"] # EST_4 = DFP, EST_3 = ITR
# Realiza a busca
search_results = cvm_client.search_document_results(
cod_cvm=cvm_codes_list,
start_date=start_date,
end_date=end_date,
category=categories,
last_ref_date=False # Se True, retorna apenas o último documento por data de referência
)
# Filtra apenas DFP e ITR válido
search_results = search_results[
search_results['categoria'].isin(["DFP - Demonstrações Financeiras Padronizadas", "ITR - Informações Trimestrais"])
]
search_results = search_results[pd.to_numeric(search_results['numero_seq_documento'], errors='coerce').notnull()]
print(search_results[['data_referencia', 'categoria', 'numero_seq_documento']].head())Com o numero_seq_documento obtido na busca anterior, você pode baixar as tabelas financeiras.
# Lista de relatórios desejados (se None, baixa todos disponíveis)
reports_list = [
'Balanço Patrimonial Ativo',
'Demonstração do Resultado',
'Demonstração do Fluxo de Caixa'
]
# Itera sobre os resultados da busca e baixa os relatórios
for index, row in search_results.iterrows():
print(f"Baixando relatórios para: {row['nome_empresa']} - Ref: {row['data_referencia']}")
financial_reports = cvm_client.get_report(
numero_sequencial_documento=row["numero_seq_documento"],
codigo_tipo_instituicao=row["codigo_tipo_instituicao"],
reports_list=reports_list
)
for report_name, data_frame in financial_reports.items():
print(f"--- {report_name} ---")
print(data_frame.head())| Método | Parâmetros Principais | Descrição |
|---|---|---|
get_cvm_codes() |
Nenhum | Retorna dicionário com códigos CVM de todas as empresas. |
get_search_categories() |
Nenhum | Retorna dicionário com categorias de documentos disponíveis (DFP, ITR, Fato Relevante, etc.). |
get_participant_types() |
Nenhum | Retorna dicionário com tipos de participantes. |
search_document_results(...) |
cod_cvm, start_date, end_date, category |
Realiza a busca de documentos na base da CVM. Retorna um DataFrame. |
get_report(...) |
numero_sequencial_documento, codigo_tipo_instituicao |
Baixa o conteúdo (tabelas) de um documento específico. |
get_b3_instruments(...) |
ref_date |
Baixa o cadastro de instrumentos/ativos da B3 para uma data. |
get_b3_issuers() |
Nenhum | Baixa a lista de emissores da B3. |
get_cvm_public_companies() |
Nenhum | Retorna cadastro completo de cias abertas da CVM. |
Para configurar o ambiente de desenvolvimento:
- Clone o repositório.
- Crie um ambiente virtual:
python -m venv .venv - Instale as dependências:
pip install -r requirements.txt - Execute os testes:
pytest
Distribuído sob a licença MIT. Veja LICENSE para mais informações.