### Install brfinance Package

Source: https://github.com/eudesrodrigo/brfinance/blob/master/README.md

Install the brfinance library using pip. This command fetches and installs the latest version of the package and its dependencies.

```bash
pip install brfinance
```

--------------------------------

### Fetch Brazilian Company Financial Data with CVMAsyncBackend

Source: https://github.com/eudesrodrigo/brfinance/blob/master/README.md

Use CVMAsyncBackend to retrieve company codes, available search categories, and financial reports. Filter results by date, company code, and report category. This example demonstrates fetching and processing DFP and ITR reports.

```python
from brfinance import CVMAsyncBackend
import pandas as pd
from datetime import datetime, date


cvm_httpclient = CVMAsyncBackend()

# Dict de códigos CVM para todas as empresas
cvm_codes = cvm_httpclient.get_cvm_codes()
print(cvm_codes)

# Dict de todas as categorias de busca disponíveis (Fato relevante, DFP, ITR, etc.)
categories = cvm_httpclient.get_consulta_externa_cvm_categories()
print(categories)

# Realizando busca por Empresa
start_date = date(2020, 1, 1)
end_dt = date.today()
cvm_codes_list = ['21610'] # B3
category = ["EST_4", "EST_3", "IPE_4_-1_-1"] # Códigos de categoria para DFP, ITR e fatos relevantes
last_ref_date = False # Se "True" retorna apenas o último report no intervalo de datas

# Busca
search_result = cvm_httpclient.get_consulta_externa_cvm_results(
    cod_cvm=cvm_codes_list,
    start_date=start_date,
    end_date=end_dt,
    last_ref_date=last_ref_date,
    category=category
    )

# Filtrar dataframe de busca para DFP e ITR apenas
search_result = search_result[
    (search_result['categoria']=='DFP - Demonstrações Financeiras Padronizadas') |
    (search_result['categoria']=='ITR - Informações Trimestrais')]
search_result = search_result[pd.to_numeric(search_result['numero_seq_documento'], errors='coerce').notnull()]

reports_list = [
    'Balanço Patrimonial Ativo',
    'Balanço Patrimonial Passivo',
    'Demonstração do Resultado',
    'Demonstração do Resultado Abrangente',
    'Demonstração do Fluxo de Caixa',
    'Demonstração das Mutações do Patrimônio Líquido',
    'Demonstração de Valor Adicionado'] # Se None retorna todos os demonstrativos disponíveis.

# Obter demonstrativos
for index, row in search_result.iterrows():
    empresa = f"{row['cod_cvm']} - {cvm_codes[row['cod_cvm']]}"
    print("*" * 20, empresa, "*" * 20)
    reports = cvm_httpclient.get_report(row["numero_seq_documento"], row["codigo_tipo_instituicao"], reports_list=reports_list)
    
    for report in reports:
        reports[report]["cod_cvm"] = row["cod_cvm"]
        print(reports[report].head())

```

--------------------------------

### Get Financial Instrument Registry

Source: https://context7.com/eudesrodrigo/brfinance/llms.txt

Retrieves the complete registry of financial instruments traded on B3 for a specific reference date. Returns a DataFrame with detailed information on all available assets.

```python
from brfinance import CVMAsyncBackend
from datetime import date

cvm_client = CVMAsyncBackend()

# Obter cadastro de instrumentos para a data atual
instrumentos = cvm_client.get_cadastro_instrumentos(ref_date=date.today())

# Exibir informações básicas
print(f"Total de instrumentos: {len(instrumentos)}")
print(instrumentos.head())

# Filtrar por tipo de instrumento específico
# Exemplo: filtrar apenas ações
acoes = instrumentos[instrumentos['TpMerc'] == 'EQUITY']
print(f"\nTotal de ações: {len(acoes)}")
```

--------------------------------

### Get Issuer List

Source: https://context7.com/eudesrodrigo/brfinance/llms.txt

Retrieves a complete list of securities issuers registered with B3. Returns a DataFrame containing information such as asset code, description, and CNPJ.

```python
from brfinance import CVMAsyncBackend

cvm_client = CVMAsyncBackend()

# Obter lista de emissores
emissores = cvm_client.get_emissor()

# Exibir estrutura do DataFrame
print("Colunas disponíveis:", emissores.columns.tolist())
# ['Asst', 'descricao', 'cnpj', 'outro']

# Exibir alguns emissores
print(emissores.head(10))

# Buscar emissor específico por CNPJ
cnpj_b3 = 9346601000125  # CNPJ da B3
b3_info = emissores[emissores['cnpj'] == cnpj_b3]
print(f"\nInformações B3: {b3_info}")
```

--------------------------------

### Retrieve CVM Categories

Source: https://context7.com/eudesrodrigo/brfinance/llms.txt

Get available search categories such as DFP and ITR from the CVM system.

```python
from brfinance import CVMAsyncBackend

cvm_client = CVMAsyncBackend()

# Obter categorias disponíveis
categories = cvm_client.get_consulta_externa_cvm_categories()

# Exibir categorias
for code, description in categories.items():
    print(f"{code}: {description}")
```

--------------------------------

### Get Public Company Search Results

Source: https://context7.com/eudesrodrigo/brfinance/llms.txt

Retrieves a list of all public companies registered with CVM, including detailed information like name, CNPJ, CVM code, participant type, and registration status.

```python
from brfinance import CVMAsyncBackend

cvm_client = CVMAsyncBackend()

# Obter lista de companhias abertas
cias = cvm_client.get_pesquisa_cia_aberta()

# Exibir estrutura do DataFrame
print("Colunas disponíveis:", cias.columns.tolist())
# ['nome', 'cnpj', 'cod_cvm', 'tipo_participante', 'situacao_registro']

# Filtrar apenas empresas com registro ativo
ativas = cias[cias['situacao_registro'] == 'ATIVO']
print(f"\nTotal de companhias ativas: {len(ativas)}")
```

--------------------------------

### Search Company Data by CVM Code

Source: https://github.com/eudesrodrigo/brfinance/blob/master/simple.ipynb

Use this function to retrieve external CVM consultation results. Specify start and end dates, CVM codes, participant type, and categories. Set last_ref_date to True to get only the last report within the date range.

```python
from datetime import date

start_date = date(2021, 1, 1)
end_date = date.today()
cvm_codes_list = [21610] # B3
category = ["EST_3","EST_4","IPE_4_-1_-1"] # Códigos de categoria para DFP, ITR e fatos relevantes
last_ref_date = False # Se "True" retorna apenas o último report no intervalo de datas
participant_type = [1] # Companhia aberta

search_result = cvm_httpclient.get_consulta_externa_cvm_results(
    start_date=start_date,
    end_date=end_date,
    cod_cvm=cvm_codes_list,
    participant_type=participant_type,
    category=category,
    last_ref_date=last_ref_date
    )
display(search_result)
```

--------------------------------

### Get Financial Report Details

Source: https://context7.com/eudesrodrigo/brfinance/llms.txt

Retrieves detailed financial statements for a specific document. Requires document sequence number and institution type code. Returns a dictionary of DataFrames, one for each statement.

```python
from brfinance import CVMAsyncBackend
from datetime import date
import pandas as pd

cvm_client = CVMAsyncBackend()

# Primeiro, realizar busca para obter os identificadores
cvm_codes_list = ['21610']  # B3 S.A.
search_result = cvm_client.get_consulta_externa_cvm_results(
    cod_cvm=cvm_codes_list,
    start_date=date(2023, 1, 1),
    end_date=date(2023, 12, 31),
    category=['EST_4'],  # DFP
    last_ref_date=True  # Apenas o mais recente
)

# Filtrar documentos válidos
search_result = search_result[
    search_result['categoria'] == "DFP - Demonstrações Financeiras Padronizadas"
]
search_result = search_result[
    pd.to_numeric(search_result['numero_seq_documento'], errors='coerce').notnull()
]

# Definir lista de demonstrativos desejados
reports_list = [
    'Balanço Patrimonial Ativo',
    'Balanço Patrimonial Passivo',
    'Demonstração do Resultado',
    'Demonstração do Resultado Abrangente',
    'Demonstração do Fluxo de Caixa',
    'Demonstração das Mutações do Patrimônio Líquido',
    'Demonstração de Valor Adicionado'
]

# Obter demonstrativos do primeiro documento encontrado
if not search_result.empty:
    row = search_result.iloc[0]

    reports = cvm_client.get_report(
        NumeroSequencialDocumento=row['numero_seq_documento'],
        CodigoTipoInstituicao=row['codigo_tipo_instituicao'],
        reports_list=reports_list,
        previous_results=False  # Apenas dados mais recentes
    )

    # Exibir cada demonstrativo
    for report_name, df in reports.items():
        print(f"\n{'='*50}")
        print(f"Demonstrativo: {report_name}")
        print(f"{'='*50}")
        print(df.head(10))
        print(f"\nUnidade monetária: {df['currency_unit'].iloc[0]}")
```

--------------------------------

### Initialize CVMAsyncBackend

Source: https://context7.com/eudesrodrigo/brfinance/llms.txt

Initialize the main client class to manage HTTP connections to CVM and B3 systems.

```python
from brfinance import CVMAsyncBackend
from datetime import date
import pandas as pd

# Inicializar o cliente
cvm_client = CVMAsyncBackend()
```

--------------------------------

### CVMAsyncBackend Initialization

Source: https://context7.com/eudesrodrigo/brfinance/llms.txt

Demonstrates how to initialize the CVMAsyncBackend client, which is the main class for accessing all library functionalities.

```APIDOC
## CVMAsyncBackend Initialization

### Description
Initializes the CVMAsyncBackend client, which manages HTTP connections and makes requests to CVM and B3 systems.

### Method
Instantiation

### Endpoint
N/A

### Request Example
```python
from brfinance import CVMAsyncBackend

# Initialize the client
cvm_client = CVMAsyncBackend()
```

### Response
N/A
```

--------------------------------

### Initialize CVMAsyncBackend

Source: https://github.com/eudesrodrigo/brfinance/blob/master/simple.ipynb

Initializes the asynchronous backend for CVM operations. Ensure pandas is imported.

```python
import pandas as pd

from brfinance import CVMAsyncBackend
from brfinance.utils import get_enet_download_url

from datetime import datetime, date


cvm_httpclient = CVMAsyncBackend()
```

--------------------------------

### Retrieve and Process Financial Statements

Source: https://context7.com/eudesrodrigo/brfinance/llms.txt

Demonstrates the complete workflow for fetching, filtering, and consolidating financial statements for multiple companies.

```python
from brfinance import CVMAsyncBackend
from datetime import date
import pandas as pd

# Inicializar cliente
cvm_client = CVMAsyncBackend()

# 1. Obter dicionário de códigos CVM
cvm_codes = cvm_client.get_cvm_codes()

# 2. Definir empresas de interesse
empresas_interesse = ['21610', '9512', '4170']  # B3, Petrobras, Bradesco

# 3. Configurar busca
search_result = cvm_client.get_consulta_externa_cvm_results(
    cod_cvm=empresas_interesse,
    start_date=date(2023, 1, 1),
    end_date=date(2023, 12, 31),
    category=['EST_4'],  # DFP apenas
    participant_type=[1],
    last_ref_date=True
)

# 4. Filtrar resultados válidos
search_result = search_result[
    search_result['categoria'] == "DFP - Demonstrações Financeiras Padronizadas"
]
search_result = search_result[
    pd.to_numeric(search_result['numero_seq_documento'], errors='coerce').notnull()
]

# 5. Lista de demonstrativos
reports_list = [
    'Balanço Patrimonial Ativo',
    'Demonstração do Resultado'
]

# 6. Processar cada empresa
all_results = {}
for index, row in search_result.iterrows():
    empresa_nome = cvm_codes.get(row['cod_cvm'], 'Desconhecida')
    print(f"\nProcessando: {empresa_nome}")

    try:
        reports = cvm_client.get_report(
            NumeroSequencialDocumento=row['numero_seq_documento'],
            CodigoTipoInstituicao=row['codigo_tipo_instituicao'],
            reports_list=reports_list
        )

        # Adicionar metadados aos DataFrames
        for report_name, df in reports.items():
            df['cod_cvm'] = row['cod_cvm']
            df['empresa'] = empresa_nome
            df['ref_date'] = row['ref_date']

        all_results[row['cod_cvm']] = reports
        print(f"  ✓ {len(reports)} demonstrativos obtidos")

    except Exception as e:
        print(f"  ✗ Erro: {e}")

# 7. Consolidar resultados em um único DataFrame
consolidated_data = []
for cod_cvm, reports in all_results.items():
    for report_name, df in reports.items():
        df['demonstrativo'] = report_name
        consolidated_data.append(df)

if consolidated_data:
    final_df = pd.concat(consolidated_data, ignore_index=True)
    print(f"\nDataFrame consolidado: {len(final_df)} linhas")
    print(final_df.groupby(['empresa', 'demonstrativo']).size())
```

--------------------------------

### Iterate and Fetch Financial Reports

Source: https://github.com/eudesrodrigo/brfinance/blob/master/simple.ipynb

Iterates through filtered search results, constructs an 'empresa' string, fetches detailed reports using an HTTP client, and processes each report.

```python
for index, row in search_result.iterrows():
    empresa = f"{row['cod_cvm']} - {cvm_codes[row['cod_cvm']]} - {row['numero_seq_documento']} - {row['codigo_tipo_instituicao']}"
    print("*" * 20, empresa, "*" * 20)
    
    reports = cvm_httpclient.get_report(row["numero_seq_documento"], row["codigo_tipo_instituicao"], reports_list=reports_list)
    for report in reports:
        print(report)
        reports[report]["cod_cvm"] = row["cod_cvm"]
        reports[report]["ref_date"] = row["ref_date"]
        reports[report]["numSequencia"] = row["numSequencia"]
        display(reports[report].head())
```

--------------------------------

### List of Financial Reports in Python

Source: https://github.com/eudesrodrigo/brfinance/blob/master/simple.ipynb

This list defines the available financial reports. If no specific report is requested, all available reports will be returned.

```python
# Obter demonstrativos

reports_list = [
    'Balanço Patrimonial Ativo',
    'Balanço Patrimonial Passivo',
    'Demonstração do Resultado',
    'Demonstração do Resultado Abrangente',
    'Demonstração do Fluxo de Caixa',
    'Demonstração das Mutações do Patrimônio Líquido',
    'Demonstração de Valor Adicionado'] # Se None retorna todos os demonstrativos disponíveis.

```

--------------------------------

### Retrieve CVM Codes

Source: https://context7.com/eudesrodrigo/brfinance/llms.txt

Fetch a dictionary mapping CVM codes to company names.

```python
from brfinance import CVMAsyncBackend

cvm_client = CVMAsyncBackend()

# Obter todos os códigos CVM
cvm_codes = cvm_client.get_cvm_codes()

# Exibir algumas empresas
for code, nome in list(cvm_codes.items())[:5]:
    print(f"Código CVM: {code} - Empresa: {nome}")
```

--------------------------------

### Fetch CVM Company Codes

Source: https://github.com/eudesrodrigo/brfinance/blob/master/simple.ipynb

Retrieves a dictionary of CVM codes for all companies. Requires an initialized CVMAsyncBackend instance.

```python
# Dict de códigos CVM para todas as empresas
cvm_codes = cvm_httpclient.get_cvm_codes()
display(cvm_codes)
```

--------------------------------

### Demonstração de Valor Adicionado

Source: https://github.com/eudesrodrigo/brfinance/blob/master/simple.ipynb

Displays a financial statement with account details, descriptions, and values. Includes currency unit, CVM code, reference date, and sequence number.

```python
     Conta                                        Descrição      Valor  
0     7.01                                         Receitas  9463674.0   
1  7.01.01       Vendas de Mercadorias, Produtos e Serviços  9048337.0   
2  7.01.02                                  Outras Receitas   279058.0   
3  7.01.03   Receitas refs. à Construção de Ativos Próprios   142661.0   
4  7.01.04  Provisão/Reversão de Créds. Liquidação Duvidosa    -6382.0   

  currency_unit cod_cvm   ref_date numSequencia  
0     Reais Mil  021610 2020-12-31       100673  
1     Reais Mil  021610 2020-12-31       100673  
2     Reais Mil  021610 2020-12-31       100673  
3     Reais Mil  021610 2020-12-31       100673  
4     Reais Mil  021610 2020-12-31       100673  
```

--------------------------------

### CVMAsyncBackend API Methods

Source: https://github.com/eudesrodrigo/brfinance/blob/master/README.md

Methods available within the CVMAsyncBackend class to interact with CVM data.

```APIDOC
## get_cvm_codes

### Description
Retrieves the CVM codes available for all companies.

### Response
- **Returns** (dict) - A dictionary where keys are CVM codes and values are company names.

## get_consulta_externa_cvm_categories

### Description
Retrieves the codes for available search categories (e.g., DFP, ITR).

### Response
- **Returns** (dict) - A dictionary with search category codes and their descriptions.

## get_consulta_externa_cvm_results

### Description
Performs a search for financial reports based on provided criteria.

### Parameters
- **cod_cvm** (list) - Required - List of CVM codes.
- **start_date** (date) - Required - Start date for the search.
- **end_date** (date) - Required - End date for the search.
- **last_ref_date** (bool) - Optional - If True, returns only the latest report in the interval.
- **report_type** (str) - Optional - Type of report to filter.

### Response
- **Returns** (DataFrame) - A pandas DataFrame containing the search results.

## get_report

### Description
Retrieves specific financial statements for a company document.

### Parameters
- **numero_seq_documento** (str) - Required - The sequence number of the document.
- **codigo_tipo_instituicao** (str) - Required - The institution type code.
- **reports_list** (list) - Optional - List of specific reports to retrieve.
- **previous_results** (any) - Optional - Previous results for reference.

### Response
- **Returns** (dict) - A dictionary containing report names as keys and their data as pandas DataFrames.
```

--------------------------------

### Fetch CVM Search Categories

Source: https://github.com/eudesrodrigo/brfinance/blob/master/simple.ipynb

Retrieves a dictionary of all available search categories (e.g., Fato relevante, DFP, ITR) from CVM. Requires an initialized CVMAsyncBackend instance.

```python
# Dict de todas as categorias de busca disponíveis (Fato relevante, DFP, ITR, etc.)
categories = cvm_httpclient.get_consulta_externa_cvm_categories()
display(categories)
```

--------------------------------

### Retrieve Participant Types

Source: https://context7.com/eudesrodrigo/brfinance/llms.txt

Fetch participant types like public companies or investment funds for filtering search results.

```python
from brfinance import CVMAsyncBackend

cvm_client = CVMAsyncBackend()

# Obter tipos de participante
tipos = cvm_client.get_consulta_externa_cvm_tipo_participante()

# Exibir tipos disponíveis
for code, descricao in tipos.items():
    print(f"Código: {code} - Tipo: {descricao}")
```

--------------------------------

### get_consulta_externa_cvm_tipo_participante

Source: https://context7.com/eudesrodrigo/brfinance/llms.txt

Retrieves the types of market participants available for filtering searches.

```APIDOC
## GET /cvm/consulta-externa/participant-types

### Description
Obtém os tipos de participantes do mercado disponíveis para filtrar as buscas, como Companhias Abertas, Fundos de Investimento, entre outros.

### Method
GET

### Endpoint
/cvm/consulta-externa/participant-types

### Parameters
N/A

### Request Example
```python
from brfinance import CVMAsyncBackend

cvm_client = CVMAsyncBackend()

# Get participant types
tipos = cvm_client.get_consulta_externa_cvm_tipo_participante()

# Display available types
for code, descricao in tipos.items():
    print(f"Código: {code} - Tipo: {descricao}")
```

### Response
#### Success Response (200)
- **dict** - A dictionary where keys are participant type codes (string) and values are participant type descriptions (string).

#### Response Example
```json
{
  "-1": "Todos",
  "1": "Companhia Aberta",
  "2": "Companhia Estrangeira",
  "4": "Fundo de Investimento"
}
```
```

--------------------------------

### Display Balance Sheet (Assets)

Source: https://github.com/eudesrodrigo/brfinance/blob/master/simple.ipynb

Shows the 'Balanço Patrimonial Ativo' (Balance Sheet - Assets) data, including account details, description, value, currency, CVM code, reference date, and sequence number.

```text
Output:
******************** 021610 - BRASIL, BOLSA, BALCÃO (REGISTRO ATIVO) - 109787 - 1 ********************
Balanço Patrimonial Ativo

Result:
        Conta                                          Descrição       Valor  \
0           1                                        Ativo Total  54807451.0   
1        1.01                                   Ativo Circulante  25600841.0   
2     1.01.01                      Caixa e Equivalentes de Caixa   3777045.0   
3     1.01.02                             Aplicações Financeiras  20196891.0   
4  1.01.02.01  Aplicações Financeiras Avaliadas a Valor Justo...  19265137.0   

  currency_unit cod_cvm   ref_date numSequencia  
0     Reais Mil  021610 2021-09-30       109787  
1     Reais Mil  021610 2021-09-30       109787  
2     Reais Mil  021610 2021-09-30       109787  
3     Reais Mil  021610 2021-09-30       109787  
4     Reais Mil  021610 2021-09-30       109787  
```

--------------------------------

### get_pesquisa_cia_aberta

Source: https://context7.com/eudesrodrigo/brfinance/llms.txt

Retrieves a comprehensive list of publicly traded companies registered with the CVM.

```APIDOC
## get_pesquisa_cia_aberta

### Description
Obtém a lista completa de companhias abertas registradas na CVM com informações detalhadas como nome, CNPJ, código CVM, tipo de participante e situação do registro.

### Method
GET

### Endpoint
/get_pesquisa_cia_aberta

### Parameters
None

### Request Example
```python
from brfinance import CVMAsyncBackend

cvm_client = CVMAsyncBackend()

# Get list of publicly traded companies
cias = cvm_client.get_pesquisa_cia_aberta()

# Display DataFrame structure
print("Colunas disponíveis:", cias.columns.tolist())
# ['nome', 'cnpj', 'cod_cvm', 'tipo_participante', 'situacao_registro']

# Filter for companies with active registration
ativas = cias[cias['situacao_registro'] == 'ATIVO']
print(f"\nTotal de companhias ativas: {len(ativas)}")
```

### Response
#### Success Response (200)
- **cias** (DataFrame) - A pandas DataFrame containing detailed information about publicly traded companies, including name, CNPJ, CVM code, participant type, and registration status.

#### Response Example
```
Colunas disponíveis: ['nome', 'cnpj', 'cod_cvm', 'tipo_participante', 'situacao_registro']

Total de companhias ativas: 500
```
```

--------------------------------

### Display Income Statement

Source: https://github.com/eudesrodrigo/brfinance/blob/master/simple.ipynb

Displays the 'Demonstração do Resultado' (Income Statement) data, including account, description, value, currency, CVM code, reference date, and sequence number.

```text
Output:
Demonstração do Resultado

Result:
     Conta                                   Descrição      Valor  \
0     3.01      Receita de Venda de Bens e/ou Serviços  2513222.0   
1  3.01.01                            Segmento Listado  1751542.0   
2  3.01.02                             Segmento Balcão   292436.0   
3  3.01.03  Segmento Infraestrutura para Financiamento   123599.0   
4  3.01.04       Segmento Tecnologia, Dados e Serviços   345352.0   

  currency_unit cod_cvm   ref_date numSequencia  
0     Reais Mil  021610 2021-09-30       109787  
1     Reais Mil  021610 2021-09-30       109787  
2     Reais Mil  021610 2021-09-30       109787  
3     Reais Mil  021610 2021-09-30       109787  
4     Reais Mil  021610 2021-09-30       109787  
```

--------------------------------

### get_cvm_codes

Source: https://context7.com/eudesrodrigo/brfinance/llms.txt

Retrieves a dictionary of all available CVM codes for Brazilian listed companies.

```APIDOC
## GET /cvm/codes

### Description
Obtém um dicionário com todos os códigos CVM disponíveis para empresas brasileiras listadas. Retorna um dicionário onde a chave é o código CVM e o valor é o nome da empresa.

### Method
GET

### Endpoint
/cvm/codes

### Parameters
N/A

### Request Example
```python
from brfinance import CVMAsyncBackend

cvm_client = CVMAsyncBackend()

# Get all CVM codes
cvm_codes = cvm_client.get_cvm_codes()

# Display some companies
for code, nome in list(cvm_codes.items())[:5]:
    print(f"Código CVM: {code} - Empresa: {nome}")
```

### Response
#### Success Response (200)
- **dict** - A dictionary where keys are CVM codes (string) and values are company names (string).

#### Response Example
```json
{
  "21610": "B3 S.A. - BRASIL, BOLSA, BALCÃO",
  "9512": "PETRÓLEO BRASILEIRO S.A. - PETROBRAS",
  "4170": "BANCO BRADESCO S.A.",
  "2453": "AMBEV S.A.",
  "14311": "ITAÚ UNIBANCO HOLDING S.A."
}
```
```

--------------------------------

### Filter Company Data

Source: https://context7.com/eudesrodrigo/brfinance/llms.txt

Filters a list of companies by name using string matching.

```python
petrobras = cias[cias['nome'].str.contains('PETROBRAS', case=False)]
print(f"\nPetrobras:\n{petrobras}")
```

--------------------------------

### get_emissor

Source: https://context7.com/eudesrodrigo/brfinance/llms.txt

Retrieves the complete list of securities issuers registered with B3.

```APIDOC
## get_emissor

### Description
Obtém a lista completa de emissores de valores mobiliários cadastrados na B3. Retorna um DataFrame com informações como código do ativo, descrição e CNPJ.

### Method
GET

### Endpoint
/get_emissor

### Parameters
None

### Request Example
```python
from brfinance import CVMAsyncBackend

cvm_client = CVMAsyncBackend()

# Get list of issuers
emissores = cvm_client.get_emissor()

# Display DataFrame structure
print("Colunas disponíveis:", emissores.columns.tolist())
# ['Asst', 'descricao', 'cnpj', 'outro']

# Display some issuers
print(emissores.head(10))

# Search for a specific issuer by CNPJ
cnpj_b3 = 9346601000125  # CNPJ of B3
b3_info = emissores[emissores['cnpj'] == cnpj_b3]
print(f"\nInformações B3: {b3_info}")
```

### Response
#### Success Response (200)
- **emissores** (DataFrame) - A pandas DataFrame containing information about securities issuers, including asset code, description, and CNPJ.

#### Response Example
```
Colunas disponíveis: ['Asst', 'descricao', 'cnpj', 'outro']
     Asst                 descricao       cnpj  outro
0  100001  BANCO DO BRASIL S.A.  16700000000000    NaN
1  100002  BANCO DO BRASIL S.A.  16700000000000    NaN
...

Informações B3:      Asst       descricao         cnpj  outro
123  9346601000125  B3 S.A. - BRASIL BOLSA BALCAO  9346601000125    NaN
```
```

--------------------------------

### get_cadastro_instrumentos

Source: https://context7.com/eudesrodrigo/brfinance/llms.txt

Retrieves the complete registry of financial instruments traded on B3 for a specific reference date.

```APIDOC
## get_cadastro_instrumentos

### Description
Obtém o cadastro completo de instrumentos financeiros negociados na B3 para uma data de referência específica. Retorna um DataFrame com informações detalhadas sobre todos os ativos disponíveis.

### Method
GET

### Endpoint
/get_cadastro_instrumentos

### Parameters
#### Query Parameters
- **ref_date** (date) - Required - The reference date for the instrument registry.

### Request Example
```python
from brfinance import CVMAsyncBackend
from datetime import date

cvm_client = CVMAsyncBackend()

# Get instrument registry for the current date
instrumentos = cvm_client.get_cadastro_instrumentos(ref_date=date.today())

# Display basic information
print(f"Total de instrumentos: {len(instrumentos)}")
print(instrumentos.head())

# Filter by specific instrument type
# Example: filter only stocks
acoes = instrumentos[instrumentos['TpMerc'] == 'EQUITY']
print(f"\nTotal de ações: {len(acoes)}")
```

### Response
#### Success Response (200)
- **instrumentos** (DataFrame) - A pandas DataFrame containing detailed information about all available financial instruments.

#### Response Example
```
Total de instrumentos: 1500
  TpMerc  ...  
0  EQUITY  ...  
1  BDR     ...  
2  FII     ...  
...

Total de ações: 1000
```
```

--------------------------------

### Display Statement of Comprehensive Income

Source: https://github.com/eudesrodrigo/brfinance/blob/master/simple.ipynb

Shows the 'Demonstração do Resultado Abrangente' (Statement of Comprehensive Income) data, including account, description, value, currency, CVM code, reference date, and sequence number.

```text
Output:
Demonstração do Resultado Abrangente

Result:
     Conta                                          Descrição    Valor  \
0     4.01               Lucro Líquido Consolidado do Período  1176097   
1     4.02                      Outros Resultados Abrangentes  -125820   
2  4.02.01  Variação Cambial sobre Investimento em Control...     5479   
3  4.02.02  Valor dos Instrumentos de Hedge de Fluxo de Ca...   -93751   
4  4.02.03  Transferência de Instrumento de Hedge para o R...    11501   

  currency_unit cod_cvm   ref_date numSequencia  
0     Reais Mil  021610 2021-09-30       109787  
1     Reais Mil  021610 2021-09-30       109787  
2     Reais Mil  021610 2021-09-30       109787  
3     Reais Mil  021610 2021-09-30       109787  
4     Reais Mil  021610 2021-09-30       109787  
```

--------------------------------

### Retrieve CVM Participant Types

Source: https://github.com/eudesrodrigo/brfinance/blob/master/simple.ipynb

Fetches the list of external participants from the CVM and displays the result.

```python
tipo_participante = cvm_httpclient.get_consulta_externa_cvm_tipo_participante()
display(tipo_participante)
```

--------------------------------

### Display Balance Sheet (Liabilities)

Source: https://github.com/eudesrodrigo/brfinance/blob/master/simple.ipynb

Presents the 'Balanço Patrimonial Passivo' (Balance Sheet - Liabilities) data, detailing accounts, descriptions, values, currency, CVM code, reference date, and sequence number.

```text
Output:
Balanço Patrimonial Passivo

Result:
        Conta                          Descrição       Valor currency_unit  \
0           2                      Passivo Total  54807451.0     Reais Mil   
1        2.01                 Passivo Circulante  15654356.0     Reais Mil   
2     2.01.01  Obrigações Sociais e Trabalhistas         NaN     Reais Mil   
3  2.01.01.01                 Obrigações Sociais         NaN     Reais Mil   
4  2.01.01.02            Obrigações Trabalhistas         NaN     Reais Mil   

  cod_cvm   ref_date numSequencia  
0  021610 2021-09-30       109787  
1  021610 2021-09-30       109787  
2  021610 2021-09-30       109787  
3  021610 2021-09-30       109787  
4  021610 2021-09-30       109787  
```

--------------------------------

### Display Statement of Cash Flows

Source: https://github.com/eudesrodrigo/brfinance/blob/master/simple.ipynb

Presents the 'Demonstração do Fluxo de Caixa' (Statement of Cash Flows) data, including account, description, value, currency, CVM code, reference date, and sequence number.

```text
Output:
Demonstração do Fluxo de Caixa

Result:
        Conta                               Descrição      Valor  \
0        6.01   Caixa Líquido Atividades Operacionais  -916604.0   
1     6.01.01              Caixa Gerado nas Operações  5516672.0   
2  6.01.01.01                Lucro Líquido do Período  3625435.0   
3  6.01.01.02               Depreciação e Amortização   801416.0   
4  6.01.01.03  Redução ao Valor Recuperável de Ativos        0.0   

  currency_unit cod_cvm   ref_date numSequencia  
0     Reais Mil  021610 2021-09-30       109787  
1     Reais Mil  021610 2021-09-30       109787  
2     Reais Mil  021610 2021-09-30       109787  
3     Reais Mil  021610 2021-09-30       109787  
4     Reais Mil  021610 2021-09-30       109787  
```

--------------------------------

### Search CVM Documents

Source: https://context7.com/eudesrodrigo/brfinance/llms.txt

Perform a filtered search for documents and return the results as a Pandas DataFrame.

```python
from brfinance import CVMAsyncBackend
from datetime import date
import pandas as pd

cvm_client = CVMAsyncBackend()

# Configurar parâmetros de busca
start_date = date(2023, 1, 1)
end_date = date(2023, 12, 31)
cvm_codes_list = ['21610']  # B3 S.A.
category = ['EST_4', 'EST_3']  # DFP e ITR
participant_type = [1]  # Companhia Aberta
last_ref_date = False  # Retornar todos os documentos no período

# Realizar busca
search_result = cvm_client.get_consulta_externa_cvm_results(
    cod_cvm=cvm_codes_list,
    start_date=start_date,
    end_date=end_date,
    category=category,
    participant_type=participant_type,
    last_ref_date=last_ref_date
)

# Exibir colunas disponíveis
print("Colunas disponíveis:")
print(search_result.columns.tolist())
```

--------------------------------

### get_consulta_externa_cvm_results

Source: https://context7.com/eudesrodrigo/brfinance/llms.txt

Performs searches in CVM documents with filters for company, date, category, and participant type, returning results as a Pandas DataFrame.

```APIDOC
## POST /cvm/consulta-externa/results

### Description
Realiza buscas nos documentos disponíveis na CVM com filtros por empresa, data, categoria e tipo de participante. Retorna um DataFrame com os resultados da busca contendo informações como empresa, categoria, data de referência e identificadores dos documentos.

### Method
POST

### Endpoint
/cvm/consulta-externa/results

### Parameters
#### Query Parameters
- **cod_cvm** (list[str]) - Required - List of CVM codes for companies.
- **start_date** (date) - Optional - Start date for the search period.
- **end_date** (date) - Optional - End date for the search period.
- **category** (list[str]) - Optional - List of document categories (e.g., 'EST_4', 'EST_3').
- **participant_type** (list[int]) - Optional - List of participant types (e.g., 1 for 'Companhia Aberta').
- **last_ref_date** (bool) - Optional - If True, returns only the latest reference date documents. Defaults to False.

### Request Body
N/A (Parameters are passed as query parameters)

### Request Example
```python
from brfinance import CVMAsyncBackend
from datetime import date
import pandas as pd

cvm_client = CVMAsyncBackend()

# Set search parameters
start_date = date(2023, 1, 1)
end_date = date(2023, 12, 31)
cvm_codes_list = ['21610']  # B3 S.A.
category = ['EST_4', 'EST_3']  # DFP and ITR
participant_type = [1]  # Companhia Aberta
last_ref_date = False  # Return all documents in the period

# Perform search
search_result = cvm_client.get_consulta_externa_cvm_results(
    cod_cvm=cvm_codes_list,
    start_date=start_date,
    end_date=end_date,
    category=category,
    participant_type=participant_type,
    last_ref_date=last_ref_date
)

# Display available columns
print("Available columns:")
print(search_result.columns.tolist())
```

### Response
#### Success Response (200)
- **pd.DataFrame** - A Pandas DataFrame containing the search results. Columns include:
  - **cod_cvm** (str): CVM code of the company.
  - **empresa** (str): Name of the company.
  - **categoria** (str): Document category.
  - **tipo** (str): Document type.
  - **especie** (str): Document species.
  - **ref_date** (str): Reference date of the document.
  - **data_entrega** (str): Submission date of the document.
  - **status** (str): Status of the document.
  - **version** (str): Version of the document.
  - **modalidade** (str): Modality of the document.
  - **acoes** (str): Actions related to the document.
  - **outros** (str): Other information.
  - **view_url** (str): URL to view the document.
  - **numero_seq_documento** (str): Sequential document number.
  - **codigo_tipo_instituicao** (str): Institution type code.
  - **numSequencia** (str): Sequence number.
  - **numVersao** (str): Version number.
  - **numProtocolo** (str): Protocol number.
  - **descTipo** (str): Description of the type.

#### Response Example
```json
{
  "cod_cvm": ["21610", "21610"],
  "empresa": ["B3 S.A. - BRASIL, BOLSA, BALCÃO", "B3 S.A. - BRASIL, BOLSA, BALCÃO"],
  "categoria": ["DFP", "ITR"],
  "tipo": ["BPA", "BPA"],
  "especie": ["ANUAL", "TRIMESTRAL"],
  "ref_date": ["2023-12-31", "2023-09-30"],
  "data_entrega": ["2024-03-27", "2023-11-09"],
  "status": ["Completo", "Completo"],
  "version": ["1", "1"],
  "modalidade": ["", ""],
  "acoes": ["", ""],
  "outros": ["", ""],
  "view_url": ["http://cvm.b3.com.br/...", "http://cvm.b3.com.br/..."],
  "numero_seq_documento": ["...", "..."],
  "codigo_tipo_instituicao": ["1", "1"],
  "numSequencia": ["...", "..."],
  "numVersao": ["...", "..."],
  "numProtocolo": ["...", "..."],
  "descTipo": ["Companhia Aberta", "Companhia Aberta"]
}
```
```

--------------------------------

### get_consulta_externa_cvm_categories

Source: https://context7.com/eudesrodrigo/brfinance/llms.txt

Retrieves the available search categories from the CVM system, such as DFP, ITR, and Relevant Facts.

```APIDOC
## GET /cvm/consulta-externa/categories

### Description
Obtém as categorias de busca disponíveis no sistema da CVM, incluindo tipos de documentos como DFP (Demonstrações Financeiras Padronizadas), ITR (Informações Trimestrais) e Fatos Relevantes.

### Method
GET

### Endpoint
/cvm/consulta-externa/categories

### Parameters
N/A

### Request Example
```python
from brfinance import CVMAsyncBackend

cvm_client = CVMAsyncBackend()

# Get available categories
categories = cvm_client.get_consulta_externa_cvm_categories()

# Display categories
for code, description in categories.items():
    print(f"{code}: {description}")
```

### Response
#### Success Response (200)
- **dict** - A dictionary where keys are category codes (string) and values are category descriptions (string).

#### Response Example
```json
{
  "EST_3": "ITR - Informações Trimestrais",
  "EST_4": "DFP - Demonstrações Financeiras Padronizadas",
  "IPE_4_-1_-1": "Fato Relevante"
}
```
```

--------------------------------

### Filter DFP and ITR with Valid Document

Source: https://context7.com/eudesrodrigo/brfinance/llms.txt

Filters search results to include only DFP and ITR categories with a valid document number. Ensures the 'numero_seq_documento' can be converted to a number.

```python
search_result = search_result[
    (search_result['categoria'] == "DFP - Demonstrações Financeiras Padronizadas") |
    (search_result['categoria'] == "ITR - Informações Trimestrais")
]
search_result = search_result[
    pd.to_numeric(search_result['numero_seq_documento'], errors='coerce').notnull()
]

# Exibir resultados
print(search_result[['empresa', 'categoria', 'ref_date', 'numero_seq_documento']].head())
```