Automação de alertas de ações com n8n, IA e API da B3 (2026)

Por que usar o n8n para alertas de ações

Quem acompanha a bolsa costuma cair em uma de duas armadilhas: checar cotações e múltiplos manualmente todo dia, o que consome tempo e é fácil de esquecer, ou escrever um script Python com cron em um servidor, o que funciona mas exige manter máquina, ambiente e logs. O n8n fica no meio-termo: agendamento, chamada de API, transformação e notificação vivem em um único fluxo visual, versionável e fácil de editar.

A ideia central é combinar duas peças complementares. A API da bolsai entrega dados oficiais da B3, CVM e BCB em JSON, com cotações, fundamentos, dividendos e um screener. O n8n orquestra: decide quando chamar, o que fazer com a resposta e para onde mandar o resultado. O nó de IA entra como camada opcional, transformando números crus em um texto curto e legível, montado com seus próprios critérios.

Antes de detalhar os nós, vale fixar uma restrição que molda todo o desenho do fluxo: a bolsai fornece dados de fim de dia. Preços e indicadores macro são atualizados diariamente às 20:30 BRT, após o fechamento do pregão da B3. Não há cotação intradiária. Isso significa que faz sentido rodar o alerta uma vez por dia, à noite, e não a cada minuto. Um fluxo que dispara às 21:00 BRT recebe os dados do pregão que acabou de fechar; um que dispara às 15:00 recebe os dados do dia anterior.

Anatomia do fluxo: quatro nós

O fluxo mínimo tem quatro nós encadeados. Cada um tem uma responsabilidade única, e a saída de um alimenta a entrada do seguinte. A tabela abaixo resume o papel de cada nó e o que confirmar na documentação do n8n antes de configurar.

Segundo a documentação do n8n, o Schedule Trigger substituiu o antigo nó Cron e aceita tanto intervalos prontos (a cada hora, a cada dia, a cada semana) quanto expressões cron de cinco campos. O HTTP Request é o nó genérico para consumir qualquer API REST. O AI Agent é o nó de IA que se conecta a um sub-nó de modelo de linguagem (Chat Model). E o nó do Telegram opera no modo "Send Message" para a notificação. Os nomes exatos e as telas de configuração podem mudar entre versões do n8n, então confirme sempre na documentação oficial ao montar.

Nó 1 — Schedule Trigger depois do fechamento

O primeiro nó define quando o fluxo roda. Adicione um Schedule Trigger como nó inicial. Para um alerta diário após o fechamento, uma expressão cron de cinco campos é a forma mais precisa. O objetivo é rodar às 21:00 em dias úteis, com folga de meia hora depois da atualização das 20:30 BRT.

# Schedule Trigger — modo "Cron Expression"
# Formato de cinco campos: minuto hora dia-do-mês mês dia-da-semana

0 21 * * 1-5

# -> roda às 21:00, de segunda (1) a sexta (5)
# Confirme o campo "Timezone" do nó como America/Sao_Paulo,
# senão o horário seguirá o fuso do servidor n8n.

Um detalhe operacional apontado pela documentação do n8n é que o fuso horário é uma fonte comum de erro. Por padrão, o Schedule Trigger usa o fuso do servidor. Se o seu n8n roda em UTC, "21:00" significaria 18:00 em Brasília. Ajuste o campo de fuso do nó para America/Sao_Paulo ou defina a variável de ambiente GENERIC_TIMEZONE em instalações self-hosted. Depois de configurar, o painel do nó mostra os próximos cinco horários de execução, o que permite conferir o agendamento sem esperar o primeiro disparo.

Vale lembrar que o Schedule Trigger só funciona com o fluxo ativado (toggle "Active" no canto superior do editor). E, em instalações self-hosted, se o servidor reiniciar, disparos perdidos durante a indisponibilidade não são reexecutados. Para um alerta diário isso raramente é problema, mas é bom saber.

Nó 2 — HTTP Request para a API da bolsai

Este é o coração do fluxo e a única parte que exige atenção aos detalhes da API. O nó HTTP Request monta uma chamada GET para a bolsai. Há duas decisões de projeto: qual endpoint chamar e como autenticar.

Escolhendo o endpoint

Para um alerta baseado em critérios (por exemplo, "quais ações pagam bom dividendo e estão baratas"), o endpoint ideal é o /screener. Ele aceita operadores como _gt, _gte, _lt, _lte e _eq sobre qualquer campo de fundamentos, além de sort, order e limit. Para um alerta de acompanhamento de um ativo específico (por exemplo, "como fechou PETR4 hoje"), o endpoint é o /stocks/{ticker}/quote, que devolve abertura, máxima, mínima, fechamento, volume e a trade_date.

Vamos usar o /screener como exemplo principal, porque ele resolve o caso de uso mais interessante: varrer o universo da B3 e trazer só o que atende aos seus critérios, em uma única requisição. Isso também economiza cota, já que uma chamada retorna vários ativos.

Autenticação: cabeçalho Authorization

A API da bolsai aceita a chave de duas formas: como query param api_key ou no cabeçalho Authorization: Bearer SUA_CHAVE. No n8n, a forma limpa é adicionar um header. No nó HTTP Request, habilite "Send Headers", adicione um header com nome Authorization e valor Bearer SUA_CHAVE. O ideal é guardar a chave como uma credencial ou variável de ambiente do n8n, em vez de deixá-la escrita no nó.

A chamada HTTP exata

Abaixo está exatamente a requisição que o nó HTTP Request faz. É a mesma chamada que você pode testar no terminal com curl antes de montar o nó, o que ajuda a validar os parâmetros isoladamente. A URL base da API é https://api.usebolsai.com/api/v1.

# A requisição que o nó HTTP Request executa
# Method: GET

GET https://api.usebolsai.com/api/v1/screener?dividend_yield_gt=6&roe_gt=10&pl_lt=15&sort=dividend_yield&order=desc&limit=10

# Header:
Authorization: Bearer SUA_CHAVE

# Equivalente em curl (para testar antes de montar o nó):
curl -H "Authorization: Bearer SUA_CHAVE" \
  "https://api.usebolsai.com/api/v1/screener?dividend_yield_gt=6&roe_gt=10&pl_lt=15&sort=dividend_yield&order=desc&limit=10"

Traduzindo os parâmetros: dividend_yield_gt=6 pega ações com dividend yield (TTM) acima de 6%, roe_gt=10 exige ROE acima de 10%, pl_lt=15 limita o P/L a menos de 15, e o resultado vem ordenado por dividend yield decrescente, limitado a 10 ativos. Todos esses são campos reais de fundamentos da bolsai. Você troca os limiares pelos seus próprios critérios. A lista completa de campos do screener está em /docs.

A resposta do /screener é um JSON com a lista de ativos que atendem aos filtros, cada um com seus indicadores. O formato é semelhante a este (valores abaixo são ilustrativos, apenas para mostrar a estrutura; os números reais vêm da chamada):

# Formato ilustrativo da resposta (a chamada devolve os valores reais)
{
  "results": [
    {
      "ticker": "XXXX4",
      "dividend_yield": 8.x,
      "roe": 1x.x,
      "pl": x.x,
      "pvp": x.x
    }
    // ... demais ativos que atendem aos critérios
  ]
}

Se o seu alerta é sobre um ativo específico em vez de um screening, troque a URL do nó HTTP Request por uma chamada de cotação. O resto do fluxo permanece idêntico:

# Variante: alerta de cotação de um ticker específico
GET https://api.usebolsai.com/api/v1/stocks/PETR4/quote

# Header:
Authorization: Bearer SUA_CHAVE

# Resposta traz: open, high, low, close, volume, trade_date

Para acompanhar vários tickers, uma opção é usar o nó "Split In Batches" (ou o modo de iteração de itens do n8n) para percorrer uma lista e fazer uma chamada por ticker. Só lembre do impacto na cota: dez tickers por execução são dez requisições. Para fluxos assim, o endpoint /screener costuma ser mais econômico, pois entrega vários ativos em uma chamada só.

Nó 3 — nó de IA para resumir os dados

Aqui entra a camada que transforma JSON em linguagem. O n8n tem o nó AI Agent, que precisa de um sub-nó de modelo de linguagem conectado (um Chat Model, como OpenAI Chat Model ou Anthropic Chat Model). Segundo a documentação do n8n, a partir da versão 1.82.0 o AI Agent passou a operar sempre como "Tools Agent", então não é mais preciso escolher o tipo de agente manualmente.

A configuração tem duas partes. Primeiro, conecte o sub-nó de Chat Model e informe as credenciais do provedor de IA (a conta da OpenAI, da Anthropic ou de outro provedor suportado). Segundo, escreva um system prompt que defina o tom e o escopo do resumo, e passe o JSON da bolsai como entrada do agente. O prompt abaixo é um ponto de partida.

# System prompt sugerido para o nó de IA
Você é um assistente que resume dados de ações da B3.
Receberá um JSON com uma lista de ações e seus
indicadores (dividend_yield, roe, pl, pvp).

Escreva um alerta curto em português (máx. 6 linhas):
- liste os tickers encontrados e seus principais números
- destaque o de maior dividend_yield
- NÃO dê recomendação de compra ou venda
- deixe claro que os dados são de fechamento do dia

# Entrada do agente: o JSON vindo do nó HTTP Request
# (referencie a saída do nó anterior via expressão do n8n)

O resultado é um parágrafo curto e legível, do tipo que cabe bem em uma notificação. A instrução explícita de não dar recomendação é importante: a bolsai é fonte de dados, não de aconselhamento, e o alerta deve refletir isso. Se você prefere um alerta puramente factual, sem IA, pode pular este nó e formatar o texto com o nó "Set" ou "Edit Fields", montando a mensagem diretamente a partir dos campos do JSON. O nó de IA agrega valor quando você quer contexto e leitura, não só os números.

Um ponto a ter em mente: chamadas ao modelo de linguagem têm latência de alguns segundos e custo próprio, cobrado pelo provedor de IA (OpenAI, Anthropic etc.), separado da bolsai. Para um alerta que roda uma vez por dia, isso é irrelevante. Para fluxos que disparam muitas vezes, monitore o custo do provedor de IA.

Nó 4 — notificação no Telegram ou por e-mail

O último nó entrega o alerta. O caminho mais popular é o Telegram. Você cria um bot pelo BotFather do Telegram, obtém o token e adiciona o nó do Telegram no modo "Send Message", apontando para o seu chat. Um detalhe prático da documentação do n8n: para descobrir o chat.id de destino, adicione temporariamente um Telegram Trigger, ative o fluxo e mande uma mensagem ao bot; a saída do trigger traz o campo chat.id que você precisa. Sempre use o ID numérico, não o nome de usuário, porque nomes podem mudar.

# Nó do Telegram — modo "Send Message"
Chat ID:  123456789          # seu chat.id numérico
Text:     {{ saída do nó de IA }}  # o texto do resumo

# Referencie a saída do nó anterior via expressão do n8n,
# ex.: {{ $json.output }} conforme o campo retornado pelo AI Agent.

Se você prefere e-mail, troque o nó do Telegram pelo nó Send Email (via SMTP) ou pelo nó do Gmail. A estrutura do fluxo não muda: o texto vem do nó de IA e vai para o assunto e corpo do e-mail. Dá até para conectar Telegram e e-mail em paralelo, recebendo o mesmo alerta pelos dois canais. A documentação de cada nó de notificação, com os campos exatos, está no site oficial do n8n.

Limites de requisição: dimensionando a frequência

Todo fluxo agendado consome cota da API. Vale planejar isso antes de ativar, para não esbarrar no limite no meio do mês. A bolsai tem dois planos, e a escolha depende de quantas chamadas o seu fluxo faz por dia.

A conta é direta. Um alerta diário com uma chamada ao /screener consome cerca de 1 requisição por dia, folgadíssimo no plano gratuito. Um fluxo que percorre 20 tickers com uma cotação cada consome 20 requisições por execução; rodando uma vez ao dia, são 20 por dia, ainda dentro do gratuito. O Pro (R$49/mês, 10.000 requisições/dia) é indicado para vários fluxos, varredura de muitos ativos ou histórico completo. Os limites resetam à meia-noite UTC.

Uma boa prática apontada pela própria documentação do n8n para chamadas agendadas é evitar rodar exatamente no minuto zero de horários "redondos", quando muitos sistemas disparam ao mesmo tempo. Em vez de 0 21 * * 1-5, algo como 7 21 * * 1-5 (21:07) distribui melhor a carga. Para monitorar o consumo, a bolsai expõe o endpoint /keys/usage, que retorna uso e cota da sua chave; você pode até criar um segundo fluxo no n8n só para vigiar isso.

Testando o fluxo antes de ativar

Antes de deixar o fluxo rodando sozinho, teste cada nó isoladamente. O editor do n8n permite executar um nó por vez e inspecionar a saída, o que facilita achar onde algo quebrou.

1. Teste a chamada HTTP fora do n8n primeiro. Rode o curl mostrado acima no terminal. Se ele retorna o JSON esperado, a URL, os parâmetros e a chave estão corretos. Um erro 401 aqui indica problema na chave; um 429 indica cota esgotada.
2. Execute o nó HTTP Request no editor. Confira que a saída traz a lista de ativos. Verifique se o header Authorization está sendo enviado.
3. Execute o nó de IA. Veja se o resumo faz sentido e respeita o system prompt (sem recomendação, com aviso de dado de fechamento).
4. Execute o nó de notificação. Confirme que a mensagem chega no Telegram ou no e-mail.
5. Confira o "Next execution". No Schedule Trigger, valide que o próximo horário bate com o esperado no fuso America/Sao_Paulo, e só então ative o fluxo.

Se preferir explorar os dados de forma conversacional antes de automatizar, o servidor MCP da bolsai permite consultar a B3 em linguagem natural direto do Claude Desktop, útil para descobrir quais filtros do screener fazem sentido antes de fixá-los no fluxo do n8n. O passo a passo está no post MCP Server para B3: conecte Claude à bolsa.

Erros comuns e como resolver

O fluxo não dispara no horário certo

Quase sempre é fuso horário. Confirme que o campo de fuso do Schedule Trigger está em America/Sao_Paulo ou que GENERIC_TIMEZONE está definida. Verifique também se o fluxo está ativado (toggle "Active") e se a sintaxe cron está correta. O painel "Next execution" do nó é a fonte de verdade: se ele mostra o horário certo, o agendamento está bom.

Erro 401 na chamada HTTP

O cabeçalho Authorization está ausente ou a chave está errada. Cheque se o valor é exatamente Bearer seguido de espaço e da chave, sem espaços invisíveis no início ou fim (copiar do dashboard com cuidado resolve). Teste a mesma chave no curl para isolar o problema.

Erro 429 (rate limit)

A cota diária acabou. No plano gratuito são 200 requisições em 24h. Se um fluxo que varre muitos tickers consome rápido, reduza a lista, migre para o /screener (uma chamada para vários ativos) ou passe para o plano Pro. Os limites resetam à meia-noite UTC.

Os dados parecem "atrasados"

Não é atraso, é o modelo de dados. A bolsai fornece dados de fim de dia, atualizados às 20:30 BRT. Se o fluxo roda antes desse horário, ele recebe o fechamento do dia anterior, o que é esperado. Agende para depois das 20:30 BRT. Se você precisa de intradiário, a bolsai não é a fonte adequada, ela cobre o mercado brasileiro com granularidade diária.

Indo além: variações do fluxo

O esqueleto de quatro nós comporta muitas variações. Alguns caminhos naturais a partir daqui, todos usando endpoints reais da bolsai documentados em /docs:

• Alerta de dividendos: use /dividends/{ticker} para checar novos proventos anunciados e avisar quando uma ação da sua lista declarar dividendo, incluindo ex_date e valor.
• Alerta de FIIs: troque o screener de ações pelo /fiis/screener, que filtra fundos imobiliários por P/VP, dividend yield e vacância, entre outros campos.
• Contexto macro: some uma chamada a /macro/selic ou /macro/cdi para o nó de IA comparar o dividend yield das ações com a taxa livre de risco no resumo.
• Ramificação condicional: use o nó "IF" do n8n para só enviar o alerta quando o screener retornar pelo menos um ativo, evitando mensagens vazias em dias sem novidade.
• Exportar para planilha: anexe ?format=csv a endpoints de lista e mande o resultado para o Google Sheets, montando um histórico dos alertas.

Se o seu objetivo evoluir de "alertas simples" para "análise que raciocina sobre a carteira", vale conhecer duas abordagens complementares. Para montar filtros mais sofisticados em Python antes de portá-los ao n8n, veja como construir um screener de ações em Python com a API. E para um agente de IA que acompanha sua carteira de forma mais autônoma, o post agente de IA para monitorar sua carteira de ações mostra o padrão em Python.

Perguntas frequentes

Preciso saber programar para montar alertas de ações no n8n?

Não é obrigatório. O n8n é low-code: o fluxo é montado arrastando nós no editor visual, um Schedule Trigger para o horário, um HTTP Request para chamar a API da bolsai, um nó de IA para resumir e um nó de notificação. O único ponto técnico é montar a URL da chamada HTTP com os parâmetros corretos e colocar a chave no cabeçalho Authorization. Nenhum código Python é necessário, embora o nó Code do n8n permita transformações em JavaScript quando você quiser.

Em que horário devo agendar o fluxo de alertas?

Os dados de preços e macro da bolsai são atualizados diariamente às 20:30 BRT, após o fechamento da B3. Agende o Schedule Trigger para depois desse horário, por exemplo às 21:00 BRT em dias úteis. Rodar antes das 20:30 retornaria a cotação do pregão anterior. Como a bolsai fornece dados de fim de dia, não faz sentido montar alertas intradiários com essa fonte.

Quantas requisições esse fluxo consome do plano da bolsai?

Depende de quantas chamadas HTTP o fluxo faz por execução. Um alerta diário com uma chamada ao /screener consome cerca de 1 requisição por dia. Se o fluxo percorre dez tickers com uma chamada cada, são dez requisições por execução. O plano gratuito oferece 200 requisições por dia e o Pro (R$49/mês), 10.000 por dia. Para fluxos frequentes ou que varrem muitos ativos, o Pro dá folga confortável.

Consigo enviar os alertas por e-mail em vez de Telegram?

Sim. Em vez do nó do Telegram, use o nó Send Email (SMTP) ou o nó do Gmail. A estrutura do fluxo permanece igual: Schedule Trigger, HTTP Request para a bolsai, nó de IA para resumir e, por fim, o nó de e-mail no lugar do Telegram. Você pode até conectar os dois em paralelo e receber pelos dois canais.

A bolsai envia notificações push por conta própria?

Não. A bolsai é uma API de dados: responde a requisições HTTP com dados da B3, CVM e BCB, mas não dispara alertas sozinha. Esse é o papel do n8n neste tutorial, orquestrar a chamada à API em um horário definido e transformar a resposta em notificação. A bolsai também não é corretora, não executa ordens e não é fonte de recomendação de investimento.

Leia também

O conteúdo deste artigo tem caráter educacional e técnico. Os dados da bolsai refletem valores públicos de fim de dia (atualizados às 20:30 BRT) e podem mudar. Nada aqui constitui recomendação de compra ou venda de ativos financeiros. Nomes de produtos e marcas pertencem aos respectivos titulares; n8n é marca da n8n GmbH e Telegram é marca da Telegram FZ-LLC.