Metadata-Version: 2.4
Name: dadosb3
Version: 0.3.0
Summary: Cliente Python da API Dados B3: fundamentos auditáveis de ações, FIIs e ETFs da bolsa brasileira (CVM/B3), com metodologia pública.
Author-email: Dados B3 <contato@dadosb3.com>
License-Expression: MIT
Project-URL: Homepage, https://dadosb3.com
Project-URL: Documentation, https://dadosb3.com/api
Project-URL: Methodology, https://dadosb3.com/metodologia
Project-URL: MCP connector, https://github.com/Val7h/dados-b3-mcp
Keywords: b3,bovespa,cvm,fundamentos,ações,fii,etf,brasil,finance,api
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24
Dynamic: license-file

# dadosb3

Cliente Python da [API Dados B3](https://dadosb3.com): 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.

```bash
pip install dadosb3
```

```python
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

```python
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](https://dadosb3.com/assinar). Documentação da API, com curl, Python e a resposta real de cada rota, em
[dadosb3.com/api](https://dadosb3.com/api); metodologia em
[dadosb3.com/metodologia](https://dadosb3.com/metodologia); para quem é (e para
quem não é) em [dadosb3.com/para-quem](https://dadosb3.com/para-quem).

## Métodos

| Método | Rota | Chave? |
|---|---|---|
| `empresas()` | `/empresas` | não |
| `empresa(t)` | `/empresas/{t}` | não |
| `indicadores(t)`, `multiplos(t)`, `fatos(t)`, `dividendos(t)`, `scores(t)`, `reapresentacoes(t)`, `trimestres(t)` | `/empresas/{t}/...` | WEGE3 não; demais sim |
| `screener(ano=, as_of=, recibo=, **faixas)` | `/screener` | sim |
| `fii(t)` | `/fiis/{t}` | MXRF11 não; demais sim |
| `fiis_ranking()`, `fiis_screener(**faixas)` | `/fiis`, `/fiis/screener` | sim |
| `etfs_ranking()` | `/etfs` | não |
| `etf(t)` | `/etfs/{t}` | BOVA11 não; demais sim |
| `hoje()`, `saude()`, `dicionario()` | `/hoje`, `/saude`, `/dicionario` | não |
| `auditar_amostra(semente, n=25)` | `/auditoria/amostra/{semente}/{n}` | não |
| `veredito(t)` | `/empresas/{t}/veredito` | não |
| `vigia(ticker=, tipo=, classe=, desde=, limite=)` | `/vigia/eventos` | não |
| `reapresentacoes_fii(t)` | `/fiis/{t}/reapresentacoes` | não |
| `recibo(id)` | `/recibo/{id}.json` | não |

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](https://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](https://github.com/Val7h/dados-b3-mcp).
