Excel com Cotações da B3 em Power Query: Dados Atualizados via API

Por que Power Query é a melhor opção para cotações no Excel

O Excel ainda domina o fluxo de trabalho de investidores e analistas brasileiros que convivem com planilhas de controle, DRE e valuation. A pergunta recorrente é como trazer a cotação atualizada da B3 para dentro desses arquivos sem dependência de scripts externos. Três caminhos competem e cada um tem limites estruturais.

A função nativa AÇÕES ou STOCKHISTORY do Excel 365 tem cobertura parcial de ativos brasileiros, com falhas em papéis de menor liquidez, units e FIIs. Macro VBA com XMLHttpRequest funciona, mas exige habilitar macros, quebra em políticas corporativas restritas e torna o arquivo menos portável. Raspagem de páginas públicas contraria termos de uso de fontes gratuitas e é frágil a mudanças de HTML.

Power Query resolve o problema de forma nativa. Disponível em todas as versões do Excel desde 2016, a linguagem M lida com JSON como tipo primário, monta consultas parametrizadas, suporta autenticação por header e entrega tabelas atualizáveis sob demanda. O resultado é uma planilha que consome uma API REST com o mesmo conforto de um banco de dados local.

Configurando o Excel para consumir a API da bolsai

O Power Query está disponível por padrão no Excel 365 e no Excel 2016 em diante. A conta na bolsai é criada via login Google e a API key aparece no dashboard logo após o cadastro. O plano gratuito libera 200 requisições por dia, suficiente para um dashboard pessoal com até duas dezenas de ativos atualizados diariamente.

Antes da primeira consulta, convém ajustar a configuração de privacidade que costuma travar cabeçalhos customizados. Em Arquivo → Opções → Configurações da Consulta Atual → Privacidade, marcar Ignorar os Níveis de Privacidade evita bloqueios ao misturar fontes. Os endpoints principais ficam em https://api.usebolsai.com/api/v1/: cotação em /stocks/{ticker}/quote, fundamentos em /fundamentals/{ticker}, dividendos em /dividends/{ticker}. A documentação completa lista todos os campos de resposta.

Primeira consulta: cotação de PETR4 via Power Query

A primeira consulta valida a cadeia de autenticação. O fluxo é direto: Dados → Obter Dados → De Outras Fontes → Consulta em Branco. O botão Editor Avançado expõe a definição em M e recebe o código da consulta completa.

let
    ApiKey = "sk_sua_chave_aqui",
    Url = "https://api.usebolsai.com/api/v1/stocks/PETR4/quote",
    Resposta = Json.Document(
        Web.Contents(
            Url,
            [Headers = [#"X-API-Key" = ApiKey]]
        )
    ),
    Tabela = Record.ToTable(Resposta),
    Transposta = Table.Transpose(Tabela),
    Promovida = Table.PromoteHeaders(Transposta, [PromoteAllScalars=true])
in
    Promovida

Web.Contents envia a requisição HTTP com o header X-API-Key. Json.Document converte a resposta em um registro M. Record.ToTable transforma o registro em tabela de duas colunas (Nome, Valor); Table.Transpose gira para que os campos virem colunas; Table.PromoteHeaders promove a primeira linha a cabeçalho. Ao clicar em Fechar e Carregar, a tabela ganha as colunas ticker, trade_date, open, high, low, close, volume, traded_amount e num_trades, referenciáveis por qualquer fórmula Excel.

O mesmo padrão funciona para qualquer ticker da B3, incluindo FIIs terminados em 11. Trocar PETR4 por VALE3, HGLG11 ou MXRF11 reaproveita a consulta. A próxima etapa parametriza o código para atender qualquer papel sem edição manual.

Fórmula M: buscar dados de múltiplos tickers em loop

Uma consulta serve para um ticker; uma carteira real tem dezenas. A solução canônica em M é transformar a consulta em função e invocá-la para cada item de uma lista. A função GetFundamentos abaixo recebe um ticker como texto e devolve preço, P/L, P/VP, ROE e dividend yield dos últimos 12 meses.

// Função: recebe um ticker, retorna preço + P/L + DY
let
    ApiKey = "sk_sua_chave_aqui",
    BaseUrl = "https://api.usebolsai.com/api/v1",

    GetFundamentos = (ticker as text) as record =>
        let
            Fund = Json.Document(Web.Contents(
                BaseUrl,
                [
                    RelativePath = "fundamentals/" & ticker,
                    Headers = [#"X-API-Key" = ApiKey]
                ]
            )),
            Div = Json.Document(Web.Contents(
                BaseUrl,
                [
                    RelativePath = "dividends/" & ticker,
                    Headers = [#"X-API-Key" = ApiKey]
                ]
            )),
            Saida = [
                ticker       = ticker,
                preco        = Record.FieldOrDefault(Fund, "current_price", null),
                pl           = Record.FieldOrDefault(Fund, "pl", null),
                pvp          = Record.FieldOrDefault(Fund, "pvp", null),
                roe          = Record.FieldOrDefault(Fund, "roe", null),
                dy_ttm       = Record.FieldOrDefault(Div, "dividend_yield_ttm", null)
            ]
        in
            Saida
in
    GetFundamentos

RelativePath separa a base da URL do caminho variável, permitindo ao Power Query cachear a raiz. Record.FieldOrDefault devolve null quando um campo não existe, em vez de quebrar a consulta em papéis com fundamentos incompletos. A assinatura (ticker as text) as record documenta o contrato da função para outros usuários.

O terceiro exemplo recebe uma coluna de tickers vinda da planilha e devolve uma tabela consolidada com os fundamentos de cada um. A lista vem de uma tabela nomeada Tickers na aba Entrada, padrão comum em controles de carteira.

// Loop sobre uma lista de tickers e agregação em tabela única
let
    Fonte = Excel.CurrentWorkbook(){[Name="Tickers"]}[Content],
    Lista = Table.Column(Fonte, "ticker"),

    Enriquecida = Table.AddColumn(
        Fonte,
        "dados",
        each GetFundamentos([ticker])
    ),

    Expandida = Table.ExpandRecordColumn(
        Enriquecida,
        "dados",
        {"preco", "pl", "pvp", "roe", "dy_ttm"}
    ),

    Tipada = Table.TransformColumnTypes(
        Expandida,
        {
            {"preco", type number},
            {"pl", type number},
            {"pvp", type number},
            {"roe", type number},
            {"dy_ttm", type number}
        }
    )
in
    Tipada

O resultado é uma tabela com uma linha por papel, expandida com preço e indicadores. Um ciclo de cinco tickers consome dez requisições (fundamentos + dividendos por papel), dentro do plano gratuito. Uma carteira de vinte papéis com refresh diário consome quarenta chamadas por dia.

Criando uma tabela dinâmica de fundamentos

Tabelas dinâmicas do Excel trabalham bem sobre resultados do Power Query desde que o cabeçalho seja estável. Ao carregar a consulta como tabela e não como conexão, o intervalo fica nomeado e a tabela dinâmica aponta para ele sem ajustes manuais. Um exemplo útil é agrupar papéis por faixa de P/L (<8, 8–15, 15–25, >25), com contagem e soma do valor de mercado em cada faixa. A cada refresh, a tabela dinâmica reflete os novos fundamentos sem reconstruir o agrupamento.

Quem já conhece o fluxo de dados fundamentalistas da B3 via API em Python encontra no Excel o mesmo contrato: JSON idêntico, mesmos campos, mesmo tratamento de null. Apenas a linguagem muda.

Agendando atualização automática (refresh)

Tabelas do Power Query não atualizam sozinhas: por padrão o dado carregado fica congelado até um clique em Dados → Atualizar Tudo. O Excel resolve com refresh automático por consulta em Dados → Consultas e Conexões → clique direito → Propriedades. A caixa Atualizar a cada N minutos dispara uma nova requisição enquanto o arquivo estiver aberto. 60 minutos costuma bastar para cotação de fechamento, já que a bolsai atualiza o dado uma vez por dia útil após as 20h30 de Brasília. A opção Atualizar ao abrir o arquivo garante que a primeira leitura do dia já traga o fechamento do pregão anterior.

Para intervalos mais curtos durante o pregão, convém recordar que a bolsai entrega fechamento diário, não intradiário. Refresh a cada cinco minutos não devolve preços diferentes entre 10h e 17h do mesmo dia útil. Esse uso exige feed ao vivo, fora do escopo do plano atual.

Segurança da API key no Excel

A API key é credencial privada. Hardcoding de sk_ dentro da consulta M funciona em protótipo local, mas vira problema quando a planilha é compartilhada por e-mail, subida no SharePoint ou anexada a um ticket. Qualquer pessoa com acesso ao Editor Avançado passa a ter acesso à chave.

O padrão recomendado isola a chave em um parâmetro do Power Query ou em célula nomeada dentro de uma aba oculta. Em Página Inicial → Gerenciar Parâmetros → Novo Parâmetro, basta criar ApiKey do tipo texto e referenciá-lo como Headers = [#"X-API-Key" = ApiKey]. A chave fica separada da lógica e pode ser trocada em um único lugar.

// Leitura segura: API key a partir de célula nomeada em aba oculta
let
    Config = Excel.CurrentWorkbook(){[Name="TabelaConfig"]}[Content],
    ApiKey = Config{[parametro="api_key"]}[valor],

    Resp = Json.Document(Web.Contents(
        "https://api.usebolsai.com/api/v1",
        [
            RelativePath = "stocks/PETR4/quote",
            Headers = [#"X-API-Key" = ApiKey]
        ]
    ))
in
    Resp

A aba Config hospeda uma tabela TabelaConfig com duas colunas (parametro, valor) e uma linha para a chave. Ocultar a aba reduz acidentes, mas não substitui controle de acesso ao arquivo. Para planilhas multiusuário reais, a chave deve ficar em gateway ou cofre externo, nunca dentro do workbook.

Exemplo completo: dashboard de carteira em Excel

A combinação de consulta parametrizada, função M e refresh automático habilita um dashboard pessoal bastante próximo do que um investidor veria em plataformas pagas. A estrutura recomendada divide o arquivo em três abas com responsabilidades claras.

Aba Entrada

Contém uma tabela nomeada Tickers com pelo menos duas colunas: ticker e quantidade. Uma terceira coluna opcional preco_medio permite calcular ganho percentual frente ao preço corrente. A aba funciona como única fonte de verdade da composição da carteira; adicionar ou remover linhas atualiza o dashboard na próxima execução do refresh.

Aba PowerQuery

Recebe o carregamento da consulta consolidada de fundamentos apresentada na seção anterior. A tabela resultante inclui ticker, preço atual, P/L, P/VP, ROE e DY 12M para cada papel declarado na aba Entrada. Essa aba é o destino do Power Query e alimenta todas as fórmulas subsequentes via PROCV ou ÍNDICE/CORRESP.

Aba Dashboard

Consolida métricas agregadas da carteira. Valor total investido é SOMARPRODUTO(quantidade; preco_medio); valor de mercado atual é SOMARPRODUTO(quantidade; PROCV(ticker; TabelaFundamentos; 2; 0)). Ganho percentual surge por diferença simples entre os dois. Formatação condicional em verde para ganho e vermelho para perda torna a leitura visual imediata, e gráficos de rosca por setor mostram a concentração da carteira em ao menos um eixo.

O dashboard ganha profundidade ao consumir também o endpoint /dividends/{ticker} para exibir renda passiva projetada dos últimos 12 meses, e o /fundamentals/{ticker}/history para mostrar evolução trimestral de P/L e ROE em gráficos de linha. Para quem vem do Google Sheets, o tutorial irmão de cotações no Google Sheets cobre a mesma lógica com IMPORTJSON e App Script. Para quem prefere Python em vez de M, o tutorial de cotação em Python mostra o mesmo contrato via requests e httpx. E para a visão geral do plano gratuito e dos endpoints disponíveis, o guia da API gratuita da B3 em Python consolida a documentação em um lugar só. A decisão entre bolsai e brapi em cenários específicos está no comparativo ponto a ponto.

A documentação oficial do Power Query da Microsoft traz referência completa da linguagem M, e o site da B3 lista convenções de tickers e calendário de pregões.

Perguntas frequentes

Excel for Mac suporta Power Query?

O Excel for Mac recebeu suporte a Power Query em versões do Microsoft 365 a partir de 2019, com paridade de recursos crescente, porém ainda inferior à versão Windows. Conexões Web.Contents com cabeçalhos customizados funcionam nas builds atuais, mas configurações de privacidade e gateways corporativos têm interface reduzida. Para uso intensivo em Mac, vale validar a build específica antes de montar uma rotina crítica.

Precisa de VBA para integrar a API no Excel?

Não. O Power Query substitui integralmente o uso histórico de VBA com XMLHttpRequest para consumir APIs REST. Toda a lógica de autenticação, parsing JSON e transformação de dados acontece dentro do editor do Power Query em linguagem M, sem habilitar macros nem bibliotecas externas. Isso torna a planilha mais portável e menos bloqueada por políticas corporativas.

A atualização é em tempo real?

A bolsai entrega a cotação de fechamento do último pregão, atualizada diariamente após o encerramento da B3 por volta das 20h30 de Brasília. O Power Query pode ser configurado para refazer a consulta em intervalos regulares enquanto o arquivo está aberto, mas o dado por trás é diário, não intradiário. Cotação tick a tick exige fornecedor de feed ao vivo, fora do escopo da API.

Qual a diferença entre Power Query no Excel e no Power BI?

A linguagem M e o editor de consultas são idênticos entre as duas ferramentas. A diferença aparece no agendamento: no Excel, o refresh automático só roda enquanto o arquivo está aberto; no Power BI Service, consultas são atualizadas por gateway na nuvem em horários programados, independentemente de sessão de usuário. Para dashboards compartilhados, o Power BI é mais robusto; para planilha pessoal, o Excel resolve.

Comece agora

Excel cotação b3 atualizada deixou de exigir macros VBA frágeis ou scraping contra termos de uso. Power Query conectado à API da bolsai entrega OHLC, fundamentos e dividendos em uma tabela que se atualiza com um clique, respeita o padrão de autenticação por header e escala de uma planilha pessoal a um dashboard completo de carteira. Os três exemplos deste tutorial, da consulta simples ao loop parametrizado, passando pela função reutilizável, cobrem a maioria absoluta dos casos de uso de quem acompanha a carteira dentro do Excel. O plano gratuito com 200 requisições por dia valida a abordagem antes de qualquer upgrade.

Leia também

Este conteúdo é educativo e não constitui recomendação de investimento. Os exemplos numéricos refletem fechamentos próximos a 17 de abril de 2026 e mudam a cada pregão. Performance passada não garante resultados futuros.