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

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

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.

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 — opcional. Sem chave, qualquer ticker responde, um por vez
    (limite por endereço: 60/hora e 150/dia; assistentes de IA, 2.000/hora
    e 20.000/dia); com chave vale o limite da chave. 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.

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.

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.

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 — opcional. Sem chave, qualquer ticker responde, um por vez
    (limite por endereço: 60/hora e 150/dia; assistentes de IA, 2.000/hora
    e 20.000/dia); com chave vale o limite da chave. Deixe "" para usar a
    variável de ambiente DADOS_B3_API_KEY, quando existir.

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 — opcional: qualquer fundo responde sem chave (limite por
    endereço: 60/hora e 150/dia; assistentes de IA, 2.000/hora e 20.000/dia).

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.

Parâmetros:
  chave_api — opcional: o ranking responde sem chave (limite por
    endereço); com chave vale o limite da chave.

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.

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 — opcional. Sem chave, qualquer ticker responde, um por vez
    (limite por endereço: 60/hora e 150/dia; assistentes de IA, 2.000/hora
    e 20.000/dia); com chave vale o limite da chave. Deixe "" para usar a
    variável de ambiente DADOS_B3_API_KEY, quando existir.

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

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.

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 — opcional. Sem chave, qualquer ticker responde, um por vez
    (limite por endereço: 60/hora e 150/dia; assistentes de IA, 2.000/hora
    e 20.000/dia); com chave vale o limite da chave. Deixe "" para usar a
    variável de ambiente DADOS_B3_API_KEY, quando existir.

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 (grátis, 200 consultas/dia, sem cartão).
    Dispensável para WEGE3, aberta em todas as ferramentas; necessária para
    as demais. Deixe "" para usar a variável de ambiente DADOS_B3_API_KEY,
    quando existir.

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.

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 (grátis, 200 consultas/dia, sem cartão).
    Dispensável para WEGE3, aberta em todas as ferramentas; necessária para
    as demais. Deixe "" para usar a variável de ambiente DADOS_B3_API_KEY,
    quando existir.

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.

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.