dadosb3

Cliente Python da API Dados B3: fundamentos auditáveis das companhias abertas brasileiras (2010–hoje), fundos imobiliários (FIIs) e ETFs, com metodologia pública. Cada número carrega a conta CVM de origem; os múltiplos são ponto-no-tempo (preço do 1º pregão a partir da chegada do balanço à CVM); nada é publicado sem a bateria de invariantes passar.

pip install dadosb3

from dadosb3 import DadosB3

api = DadosB3()                        # sem chave: WEGE3, BOVA11, MXRF11, rankings de ETF, /hoje, /saude
api.indicadores("WEGE3")["anos"]       # ROE, ROIC, margens... com a conta CVM de cada número
api.multiplos("WEGE3")                 # P/L, P/VP, EV/EBITDA ponto-no-tempo
api.etf("BOVA11")                      # cota diária, ágio/deságio, taxa efetiva, carteira
api.auditar_amostra(semente=4242)      # sorteie a SUA amostra e confira contra a CVM

api = DadosB3(chave="sua-chave")       # ou DADOS_B3_API_KEY no ambiente
api.screener(roic_min=0.15, dl_ebitda_max=2, ano=2024)
api.fiis_screener(pvp_max=0.9, dy_min=0.10)

Novo na 0.2.0

api = DadosB3()

# a companhia: quem é, os códigos e o endereço de cada recurso
api.empresa("WEGE3")["recursos"]["indicadores"]["url"]

# o retrato do último balanço em fatos comparados, com a bandeira de confiança
v = api.veredito("WEGE3")
v["frase_topo"], v["bandeira"]["cor"]

# o vigia: o que mudou de faixa, período contra período, com os dois números
for e in api.vigia(ticker="WEGE3", limite=5)["eventos"]:
    print(e["data"], e["texto"])
api.vigia(tipo="reapresentacao")                    # todas as reapresentações recentes
api.vigia(classe="fiis", tipo="faixa_pvp")          # o vigia dos fundos imobiliários

# informes de FII reenviados à CVM (versão vigente; antes e depois quando visto)
api.reapresentacoes_fii("HGLG11")["versoes"]

# "valeu a pena?" em poucos números, sem chave, para qualquer ação, FII ou ETF
d = api.desempenho("PETR4")                         # últimos 5 anos; cruzamento de médias 21 x 100
d["buy_and_hold"]["retorno_pct"], d["buy_and_hold"]["retorno_total_pct"]   # preço e com proventos
api.fii_desempenho("MXRF11"); api.etf_desempenho("BOVA11")                  # só preço; rendimentos fora (FII: total à parte)
api.indice_desempenho("IBOV"); api.indices()                                # o benchmark (índice de preço, sem dividendos)

# a série diária: amostra de 30 pregões sem chave; completa com chave
amostra = api.precos("PETR4")                       # amostra=True e um `aviso` dizendo como ter tudo
api = DadosB3(chave="sua-chave")
serie = api.precos("PETR4", de="2021-10-04")["serie"]
api.eventos("PETR4")                                # desdobramentos e grupamentos, com a fonte de cada um

# screener ponto-no-tempo e com recibo citável (exige chave)
api = DadosB3(chave="sua-chave")
tela = api.screener(roic_min=0.15, dl_ebitda_max=2, as_of="2023-06-30", recibo=True)
tela["recibo"]["url"]                               # quem recebe o link confere o hash
api.recibo(tela["recibo"]["id"])["sha256"]

Os testes do pacote rodam sem rede, contra respostas REAIS da API gravadas em tests/respostas/ (e regravadas pelo mesmo cliente quando a API muda).

Chave grátis (200 consultas/dia, sem cartão) ou Pro em dadosb3.com/assinar. Documentação da API, com curl, Python e a resposta real de cada rota, em dadosb3.com/api; metodologia em dadosb3.com/metodologia; para quem é (e para quem não é) em dadosb3.com/para-quem.

Métodos

Erros: ChaveNecessaria (401), NaoEncontrado (404), ErroDadosB3 (demais), todos com .status e .detalhe (o corpo da resposta da API).

Limites, ditos antes

Preço só de fim de dia (COTAHIST); sem tratamento de viés de sobrevivência (companhia que saiu da bolsa não está na base); sem composição histórica de índice; a base começa em 2010. A lista completa está em dadosb3.com/o-que-nao-resolvemos.

Não é recomendação de investimento. Fontes: CVM (dados abertos, ODbL) e B3 (COTAHIST). Projeto independente, não afiliado à B3 nem à CVM. Licença deste cliente: MIT. Conector MCP: Val7h/dados-b3-mcp.