| listar_empresasA | Lista as companhias abertas brasileiras cobertas pelo Dados B3. Devolve, para cada empresa: nome, CNPJ, código CVM e ticker principal,
mais a contagem total. É o ponto de partida para descobrir qual ticker
passar nas outras ferramentas.
Sem parâmetros. Gratuito — não exige chave.
A contagem não fica escrita nesta descrição de propósito: o universo
cresce quando a CVM publica, e um número congelado aqui envelheceria sem
ninguém ver. Para o número de hoje, chame `saude`.
|
| indicadores_anuaisA | Série anual de indicadores fundamentalistas de uma empresa da B3. Cobre de 2010 até o último exercício publicado e devolve, por ano: ROIC,
ROE, margens (bruta, EBIT e líquida), crescimento de receita e de lucro, e
dívida líquida/EBITDA. Para saber como cada um é calculado, chame
`metodologia`.
Parâmetros:
ticker — código da ação na B3, em maiúsculas e com o dígito da classe.
Exemplos: "WEGE3" (ordinária), "PETR4" (preferencial), "SANB11"
(unit). Use `listar_empresas` para descobrir os disponíveis.
chave_api — chave do Dados B3. Dispensável para WEGE3, aberta como
degustação; necessária para qualquer outra empresa. Deixe "" para usar
a variável de ambiente DADOS_B3_API_KEY, quando existir. Sem chave
válida a resposta vem com o campo `erro` explicando como obter uma.
|
| multiplosA | Múltiplos de avaliação ponto-no-tempo de uma empresa da B3. Devolve P/L, P/VP e EV/EBITDA por exercício, mais P/L TTM por trimestre.
O preço usado é o do primeiro pregão A PARTIR da data real de publicação
do balanço (na maioria dos casos, o próprio dia da entrega) — não o
fechamento do exercício, que ninguém conhecia naquela data. É essa escolha que elimina o look-ahead e permite usar a série em
backtest sem contaminar o passado.
Parâmetros:
ticker — código da ação na B3, em maiúsculas e com o dígito da classe.
Exemplos: "WEGE3", "PETR4", "SANB11". Veja `listar_empresas`.
chave_api — chave do Dados B3. Dispensável para WEGE3, aberta como
degustação; necessária para as demais. Deixe "" para usar a variável
de ambiente DADOS_B3_API_KEY, quando existir.
|
| fatos_contabeisA | Contas contábeis padronizadas de uma empresa da B3, com a origem de cada número. Devolve, por período: receita, EBIT, lucro líquido, patrimônio líquido,
caixa, dívida bruta e dívida líquida, entre outras — e, junto de cada
valor, o código da conta CVM de onde ele saiu, para auditoria.
Parâmetros:
ticker — código da ação na B3, em maiúsculas e com o dígito da classe.
Exemplos: "WEGE3", "PETR4", "SANB11". Veja `listar_empresas`.
trimestral — escolhe a granularidade da série, e só isso. False (padrão)
devolve os exercícios ANUAIS, vindos dos formulários DFP; True devolve
os TRIMESTRES, vindos dos ITR. Não é um filtro: os dois modos cobrem o
mesmo histórico, muda apenas o período de cada linha.
chave_api — chave do Dados B3. Dispensável para WEGE3, aberta como
degustação; necessária para as demais. Deixe "" para usar a variável
de ambiente DADOS_B3_API_KEY, quando existir.
|
| dividendosA | Proventos em dinheiro pagos por uma empresa da B3, com dividend yield. Devolve cada provento (dividendo ou JCP) com valor por ação, data-com e
data de aprovação, mais o resumo por ano e o dividend yield dos últimos 12
meses. A fonte é a própria B3, e o registro guarda o tipo original
declarado por ela, não só o normalizado.
Parâmetros:
ticker — código da ação na B3, em maiúsculas e com o dígito da classe.
Exemplos: "WEGE3", "PETR4", "SANB11". Veja `listar_empresas`.
chave_api — chave do Dados B3. Dispensável para WEGE3, aberta como
degustação; necessária para as demais. Deixe "" para usar a variável
de ambiente DADOS_B3_API_KEY, quando existir.
Ausência de provento e ausência de informação são coisas diferentes aqui:
a resposta distingue "a B3 respondeu que não houve" de "não conseguimos
perguntar", em vez de devolver zero para os dois casos.
|
| scoresA | Scores de qualidade e de valor de uma empresa da B3, critério por critério. Devolve o Piotroski F-Score (0 a 9) com **cada um dos nove critérios
aberto**, dizendo qual passou e com que número, e o critério de Graham.
O objetivo é poder discordar do score: você vê a conta, não só a nota.
Parâmetros:
ticker — código da ação na B3, em maiúsculas e com o dígito da classe.
Exemplos: "WEGE3", "PETR4", "SANB11". Veja `listar_empresas`.
chave_api — chave do Dados B3. Dispensável para WEGE3, aberta como
degustação; necessária para as demais. Deixe "" para usar a variável
de ambiente DADOS_B3_API_KEY, quando existir.
|
| reapresentacoesA | Balanços que a empresa republicou depois, com as duas versões lado a lado. Quando uma companhia reapresenta um exercício já publicado, o número
antigo costuma sumir das bases — aqui ele fica. Devolve, por conta
afetada, o valor da versão original e o da versão nova, com as datas das
duas publicações. Serve para auditar mudança de histórico e para saber se
um backtest rodou sobre números que depois foram revistos.
Parâmetros:
ticker — código da ação na B3, em maiúsculas e com o dígito da classe.
Exemplos: "WEGE3", "PETR4", "SANB11". Veja `listar_empresas`.
chave_api — chave do Dados B3. Dispensável para WEGE3, aberta como
degustação; necessária para as demais. Deixe "" para usar a variável
de ambiente DADOS_B3_API_KEY, quando existir.
|
| screenerA | Filtra o universo inteiro da B3 por faixas de indicadores. Parâmetros:
filtros — dicionário de faixas. Cada chave é o nome de um indicador
seguido de `_min` ou `_max`, e o valor é o número da faixa. Frações,
não porcentagens: ROIC de 15% é 0.15.
Exemplo: {"roic_min": 0.15, "dl_ebitda_max": 2}
Indicadores aceitos: roic, roe, margem_bruta, margem_ebit,
margem_liquida, dl_ebitda, cresc_receita_1a, cresc_receita_5a_cagr,
piotroski.
Chame SEM filtros para receber o cardápio: a lista de indicadores
válidos e exemplos de uso.
ano — exercício alvo. 0 (padrão) usa, para cada empresa, o último ano
com dado disponível — que não é o mesmo ano para todas.
as_of — data "AAAA-MM-DD". Responde outra pergunta: o que estava
PÚBLICO naquele dia (balanço já recebido pela CVM, em média ~100 dias
depois do fim do exercício). Use em pesquisa, para não olhar o futuro;
cada empresa traz `disponivel_em`. Não combina com `ano`. O universo
continua o das companhias ativas hoje (viés de sobrevivência, dito na
resposta).
limite — máximo de empresas na resposta. Padrão 100.
recibo — True congela a resposta num endereço permanente, com a
pergunta, a data de corte, a versão do dado e o sha256 do resultado.
Use quando for CITAR a lista: ela muda quando a base é atualizada, o
recibo não. Leia depois com a ferramenta `recibo`.
chave_api — obrigatória aqui, mesmo para WEGE3, porque a consulta
percorre todo o universo. Deixe "" para usar DADOS_B3_API_KEY.
Só entram valores SEM flag, isto é, números que passaram limpos pela
bateria de invariantes. Um indicador marcado como suspeito não é filtrado
silenciosamente: ele simplesmente não participa. Nome de indicador
desconhecido é recusado com erro, nunca ignorado.
|
| reciboA | Lê um RECIBO de pesquisa: uma consulta ao screener congelada num
endereço permanente — a pergunta, a data de corte (as_of), a versão do
dado, o resultado e o sha256 que prova que ele não mudou. O id_recibo vem
do campo do recibo na resposta de screener(recibo=True). Aberto, sem
chave: quem recebe a citação precisa conseguir conferir. |
| vereditoA | Resumo DESCRITIVO de uma ação da B3 em seis números e três perguntas —
ganha dinheiro? (margem líquida, ROIC), está endividada? (dívida
líquida/EBITDA), está cara em relação ao setor e à própria história? (P/L,
P/VP) — cada número com a faixa numérica e a comparação com a mediana do
setor, com a história da própria empresa e com o universo; mais a BANDEIRA
DE CONFIANÇA do dado (verde/amarela/vermelha: houve reapresentação? o
balanço é o mais recente? passou nas conferências?) e uma frase de topo de
até 25 palavras. Fato comparativo, sem adjetivo de julgamento e sem
recomendação. Aberto para qualquer ação, sem chave; traz citacao. |
| desempenhoA | "Valeu a pena?" em poucos números, calculado no servidor: retorno, queda
máxima (com as datas do pico e do fundo), volatilidade e cruzamento de médias
móveis (padrão 21 x 100, últimos 5 anos) de uma AÇÃO, comprar-e-manter contra
o cruzamento. No preço ajustado por eventos societários e, quando há
proventos, também o retorno TOTAL (retorno_total_pct: dividendos e JCP
reinvestidos no data-ex). Sem custos; as premissas vêm na resposta. Medida
do passado, não recomendação. ABERTO para qualquer ticker, sem chave. de/ate
em AAAA-MM-DD; media_curta/media_longa mudam as médias. |
| desempenho_fiiB | O mesmo de desempenho, para um FUNDO IMOBILIÁRIO. Aberto, sem chave. O
preço não tem ajuste de desdobramento: salto diário acima de 35% vem em
saltos_suspeitos com confiavel: false. Os rendimentos mensais entram só
no retorno TOTAL (retorno_total_pct); amortização fica de fora. |
| desempenho_etfB | O mesmo de desempenho, para um ETF (só preço, sem ajuste de desdobramento:
salto diário acima de 35% vem em saltos_suspeitos). Aberto, sem chave. |
| indiceA | O benchmark: desempenho de um ÍNDICE da B3 (IBOV, IFIX, SMLL, IDIV, IBXX...)
num período, como em desempenho (retorno, queda máxima, cruzamento de médias;
últimos 5 anos). Aberto, sem chave. codigo="" lista os índices e a cobertura.
Índice de PREÇO, em pontos: não inclui dividendos. |
| indice_precosA | Fechamento DIÁRIO de um índice da B3, em pontos, do mais antigo ao mais
recente. Sem chave vem uma AMOSTRA (últimos 30 pregões) com aviso; com a
chave grátis em chave_api, a série inteira. |
| bdrA | BDRs negociados na B3: recibos em reais de ações ou ETFs listados lá fora
(AAPL34, NVDC34, IVVB39...). `ticker=""` LISTA os BDRs que negociaram no último ano, com o tipo (DRN não
patrocinado; DR1/DR2/DR3 patrocinado nível I/II/III; DRE BDR de ETF), último
fechamento e liquidez média — aberto, sem chave; `tipo` filtra (ex.: "DRE").
Com `ticker`: cadastro da B3, último pregão, rentabilidade com e sem
proventos (1 mês a 10 anos, em reais, já com o câmbio), proventos por BDR em
R$ e desdobramentos com a conferência pelo preço. AAPL34 é aberto; os demais
exigem `chave_api` (grátis).
NÃO tem o código da ação lá fora nem a proporção BDR:ação. Descritivo, não é
recomendação.
|
| bdr_precosA | Série DIÁRIA de um BDR (fechamento, abertura, máxima, mínima, volume,
negócios), do COTAHIST da B3, sem ajuste. Sem chave vem uma AMOSTRA dos
últimos 30 pregões com aviso (AAPL34 inteiro); com a chave grátis em
chave_api, a série inteira. de/ate em AAAA-MM-DD. |
| precosA | A série DIÁRIA de preços (abertura, máxima, mínima, fechamento, médio,
volume, quantidade, negócios) de uma AÇÃO, do mais antigo ao mais recente, mais
os eventos societários do período. O preço NÃO é ajustado. de/ate em
AAAA-MM-DD. WEGE3 é aberta; nos demais papéis, SEM chave vem uma AMOSTRA (últimos
30 pregões) com um aviso de como ter a série inteira (chave grátis em
chave_api) e de que desempenho responde sem chave. |
| eventosA | Desdobramentos, grupamentos, bonificações e cisões de uma empresa, com a
FONTE de cada um (declarado pela B3 ou achado por nós), o fator declarado e
efeito_liquido_do_dia (eventos do mesmo dia são uma operação: 0,01 x 100 =
1,0). WEGE3 é aberta; os demais papéis exigem chave_api. |
| dicionarioA | Dicionário técnico dos indicadores: fórmula, contas CVM e base do lucro. Devolve, para cada indicador que o Dados B3 publica, a fórmula exata, os
códigos de conta CVM que entram nela, e qual linha de lucro é usada como
base. É o mapa que permite recalcular qualquer número à mão a partir dos
documentos originais.
Sem parâmetros. Gratuito — não exige chave.
Diferença para `metodologia`: aqui vem a definição em JSON, própria para
um programa consumir; lá vem o texto explicativo, próprio para leitura.
|
| metodologiaA | Metodologia pública por trás dos indicadores — como cada número é calculado. Tem dois modos, conforme o argumento:
- sem `nome` (padrão): devolve a LISTA das páginas disponíveis, com o
identificador de cada uma;
- com `nome`: devolve o TEXTO completo daquela página, em Markdown.
Parâmetros:
nome — identificador da página, exatamente como aparece na listagem.
Exemplo: "roic". Deixe "" para listar em vez de ler.
Gratuito — não exige chave. Use quando precisar auditar ou justificar um
número devolvido pelas outras ferramentas.
|
| trimestresA | Série TRIMESTRAL de uma empresa da B3: contas da ITR, preço e indicadores. Use quando a pergunta for sobre o ANO CORRENTE ou sobre o trimestre mais
recente — "como foi o 2T", "a margem melhorou este ano?". A série anual só
responde depois que o exercício fecha, e fica até um ano defasada.
Devolve, por trimestre: as contas publicadas na ITR (receita, resultado
bruto, EBIT, lucro, PL, ativo...), o preço do 1º pregão a partir da
publicação daquela ITR, P/L TTM e P/VP, e os indicadores margem_bruta,
margem_ebit, margem_liquida e roe_ttm no mesmo formato da série anual.
O 4º TRIMESTRE NÃO VEM, e isso é escolha: a ITR publica 1T, 2T e 3T; o
exercício fechado é da DFP. É possível derivar `4T = anual − 9M` (há quem
derive), e não derivamos — número calculado por nós não entra na mesma
lista dos que a companhia reportou. Para o ano fechado use
`indicadores_anuais`.
Instituição financeira (banco/seguradora) recebe só margem líquida e
roe_ttm: não há resultado bruto nem EBIT nesse plano de contas.
Parâmetros:
ticker — código da ação na B3, em maiúsculas. Ex.: "WEGE3", "PETR4".
chave_api — chave do Dados B3. Dispensável para WEGE3.
|
| fiiA | Um fundo imobiliário (FII) da B3, com o histórico auditável. Devolve o cadastro (CNPJ, segmento, mandato, tipo de gestão, público-alvo),
a série de P/VP ponto-no-tempo (preço do 1º pregão a partir da entrega do
informe mensal ÷ valor patrimonial da cota), o dividend yield de 12 meses,
a vacância quando é fundo de tijolo, e os rendimentos recentes.
Rendimento de FII é DISTRIBUIÇÃO DE CAIXA, não lucro — um yield alto pode
ser devolução de capital ou ganho não recorrente. O dado vem dos informes
mensais entregues à CVM, não de agregador.
Parâmetros:
ticker — código do fundo na B3. Ex.: "MXRF11", "HGLG11".
chave_api — chave do Dados B3. MXRF11 é aberto como degustação.
|
| fiisA | Filtra os fundos imobiliários por faixas de P/VP e dividend yield. Todos os parâmetros são opcionais; sem nenhum, devolve o universo ordenado.
Parâmetros:
pvp_min / pvp_max — faixa de P/VP. Ex.: pvp_max=1.0 para fundos abaixo do
valor patrimonial.
dy_min / dy_max — faixa de dividend yield de 12 meses, em FRAÇÃO:
dy_min=0.10 significa 10% ao ano, não 10.
segmento — segmento CVM, casando exato (sem caixa). Ex.: "Shoppings".
cotistas_min — piso de cotistas, para tirar fundo ilíquido. Padrão 5000.
limite — quantos devolver (padrão 50, teto 200).
chave_api — obrigatória: o filtro varre o universo inteiro, não há
degustação possível.
Só entra número LIMPO: um P/VP ou DY marcado com flag não é tratado como
valor filtrável, e o fundo simplesmente não casa aquele filtro — em vez de
entrar na lista com um número em que nós mesmos não confiamos. Não é
recomendação de investimento.
|
| etfs_rankingA | ETFs listados na B3: mais negociados, maior patrimônio, maior deságio e
maior ágio sobre a cota (preço ÷ cota patrimonial do MESMO dia), retorno
de 12 meses pela cota e menor taxa EFETIVA (despesa do balancete ÷ PL
médio, anualizada — a taxa nominal não existe em fonte pública). Cota, patrimônio e cotistas vêm do informe diário que o administrador
entrega ao FNET; a carteira vem do CDA mensal da CVM; o índice é inferido
do NOME do fundo. Só ETF líquido (> R$ 1 mi/dia) entra em ágio, retorno e
taxa. Descritivo, não é recomendação.
Sem parâmetros. Gratuito — não exige chave.
|
| etfA | Um ETF da B3: cadastro (CVM + B3), último informe diário (cota,
patrimônio, cotistas), ágio/deságio dos últimos 30 pregões, taxa efetiva
mês a mês, carteira mais recente (10 maiores posições) e sobreposição com
ETFs do mesmo índice, retornos pela cota e pelo preço. Retorno pela COTA é retorno total por construção (o ETF reinveste). O
preço de tela pode descolar da cota — o ágio diz quanto.
Parâmetros:
ticker — código do fundo na B3. Ex.: "BOVA11", "IVVB11".
chave_api — chave do Dados B3. BOVA11 é aberto como degustação.
|
| auditar_amostraA | AUDITE ESTA BASE. Sorteia casos e devolve o que você precisa para
refazer cada número contra o arquivo ORIGINAL da CVM — não contra nós. VOCÊ escolhe a semente (um inteiro qualquer; não aceite sugestão de
ninguém, inclusive de quem te pediu para auditar). O sorteio é
determinístico: a mesma semente devolve sempre os mesmos casos, então o
resultado é reproduzível por terceiros. Cada caso traz empresa, CD_CVM,
exercício, indicador, valor publicado, fórmula, a conta CVM que AQUELA
empresa usou NAQUELE exercício e `onde_procurar` (o CSV dentro do zip da
CVM e o filtro). Publique o DENOMINADOR do que conferiu.
Parâmetros:
semente — inteiro escolhido por você. n — casos (padrão 25, teto 100).
Gratuito — não exige chave. Protocolo: https://dadosb3.com/auditoria
|
| fiis_rankingA | Ranking dos fundos imobiliários (FIIs): os mais descontados (menor P/VP
ponto-no-tempo), os maiores pagadores (DY 12m) e a mediana de P/VP, DY e
vacância por segmento. Do informe mensal da CVM + COTAHIST, só valores
limpos (sem flag) e fundos líquidos. Descritivo, não é recomendação. Parâmetros:
chave_api — obrigatória (grátis ou Pro); o fundo MXRF11 é aberto na
ferramenta `fii`, mas o ranking varre o universo inteiro.
|
| hojeA | O que mudou no mercado brasileiro nos últimos 30 dias. Responde "o que aconteceu com a empresa X esta semana" — a pergunta que
nenhuma série anual responde. Devolve, na janela: os balanços que ficaram
públicos (com a data de entrega à CVM), os documentos REENVIADOS (versão
maior que 1: a companhia republicou o que já tinha entregue), os proventos
de ações aprovados, os rendimentos e informes de FII, os eventos
societários (grupamento, desdobramento, bonificação) e as trocas de ticker.
Cada seção declara `dados_ate`: a data máxima daquela FONTE. As defasagens
são diferentes — a CVM entrega documento com dias de atraso, a B3 publica
rendimento de FII quase no dia — e a janela é fixa a partir de hoje, então
uma fonte parada aparece como parada em vez de parecer recente.
Sem parâmetros. Gratuito — não exige chave.
|
| saudeA | Estado atual da base do Dados B3: o que está coberto e quão fresco está. Devolve as contagens por tipo de dado (empresas, fatos anuais e
trimestrais, indicadores, múltiplos e preços) e a data-hora da última
ingestão. Serve para saber o tamanho do universo hoje e para conferir se a
base foi atualizada antes de confiar num número.
Sem parâmetros. Gratuito — não exige chave.
|
