Evolution API: o que é e como usar com n8n passo a passo

Evolution API: o que é e como usar com n8n

A Evolution API é uma API aberta para integração com modelos de linguagem e IA, focada em custo baixo e latência reduzida para aplicações brasileiras. Ela permite enviar prompts e receber respostas estruturadas via HTTP, semelhante ao funcionamento da OpenAI, mas com preços até 90% menores em alguns casos. Para usá-la no n8n, você configura um node HTTP Request com a URL da API e autenticação via token ou OAuth2.

Se você já usa n8n para automações, integrar a Evolution API é direto: basta substituir a URL do endpoint da OpenAI (por exemplo) pela da Evolution, ajustar o payload e pronto. A API é ideal para quem busca alternativas locais ou open-source sem abrir mão de performance. A documentação oficial detalha todos os endpoints e exemplos de requisições.

Por que usar Evolution API no n8n? Benefícios e casos de uso

A Evolution API se destaca por três vantagens principais no n8n: custo 80-90% menor que APIs como OpenAI ou Gemini em requisições de alto volume, latência baixa (geralmente <500ms) por servidores brasileiros, e personalização de modelos para contextos locais. Isso é ideal para automações em negócios pequenos que não podem pagar por APIs premium.

Exemplos de uso no n8n:

Atendimento automatizado via WhatsApp com respostas em português natural.
Análise de sentimentos em comentários de redes sociais em tempo real.
Geração de relatórios personalizados com dados de bancos ou planilhas.

Para comparar com outras plataformas de automação, veja como o n8n se sai frente ao Make ou Zapier: n8n vs Make vs Zapier.

Pré‑requisitos: configurando seu ambiente n8n

Antes de integrar a Evolution API, seu n8n precisa estar atualizado (versão 1.0+). Se você usa n8n auto-hosted, verifique os requisitos: Node.js 18+, Docker (opcional), e 2GB de RAM para workloads leves. Para instalação gratuita, siga os guias oficiais:

Método	Recursos	Link
Instalação local (Windows/macOS/Linux)	Node.js + npm, 1GB RAM	Instalar n8n de graça
VPS com Docker	Ubuntu 22.04, 2GB RAM, 10GB SSD	Instalar n8n na VPS com Docker

Curiosidade: o n8n auto-hosted permite usar credenciais seguras para tokens da Evolution API, sem expor chaves no código ou em serviços terceiros.

Passo a passo: criando o workflow com Evolution API

Para criar um workflow no n8n que use a Evolution API, siga estes passos. O coração do processo é o node HTTP Request, que envia prompts e recebe respostas. Abaixo, uma tabela com os campos obrigatórios:

Crie um novo workflow no n8n e adicione um node HTTP Request.
Configure o método e URL: Use POST e a URL base da Evolution API (ex.: https://api.evolutionapi.com/v1/chat/completions).
Adicione o cabeçalho de autenticação: Insira Authorization: Bearer SEU_TOKEN nos headers.

Defina o payload no corpo da requisição (exemplo para texto):

{
  "model": "gpt-4o-mini",
  "messages": [
    {"role": "user", "content": "Olá, como posso ajudar?"}
  ]
}

Teste e execute: Clique em "Execute" e confira a resposta no node seguinte (ex.: Set ou Function).

Campo	Valor obrigatório	Exemplo
URL	Endpoint da Evolution API	`https://api.evolutionapi.com/v1/chat/completions`
Método	`POST`	`POST`
Authorization	`Bearer SEU_TOKEN`	`Bearer abc123...`
Body (raw JSON)	Payload com model e messages	`{"model": "gpt-4o-mini", "messages": [...]}`
Headers	`Content-Type: application/json`	`application/json`

Resultado esperado: uma resposta JSON com a mensagem gerada pela IA, pronta para ser usada em nodes subsequentes. Para mais detalhes sobre o node HTTP Request, confira o guia completo.

Curiosidade: a Evolution API aceita requisições em lote (batch), ideal para processar múltiplos prompts em um único request e reduzir custos.

Trabalhando com autenticação e tokens na Evolution API

Você deve usar credenciais do tipo OAuth2 ou JWT para acessar a Evolution API. No n8n, crie uma credencial “API Key” segura e referencie‑a nos nodes HTTP Request.

Passo a passo para criar a credencial:

Abra Credentials > New Credential > API Key.
Insira Authorization como nome e cole Bearer SEU_TOKEN no campo “API Key”.
Marque “Encrypt” para que o token seja armazenado criptografado.
Salve e selecione a credencial no node HTTP Request → “Authentication”.

Campo	Valor esperado	Exemplo
Tipo	OAuth2 ou JWT	Bearer
Header	Authorization	Bearer abc123def456
Expiração	Segundos	3600
Refresh URL	Opcional	https://api.evolutionapi.com/oauth/token

Curiosidade: ao usar “OAuth2 Client Credentials”, o n8n renova o token automaticamente antes da expiração, evitando falhas inesperadas.

Tratando erros e depurando chamadas HTTP no n8n

Quando a Evolution API devolve erro, o n8n captura o código e permite retry ou fallback. Use o recurso “Error Workflow” para redirecionar falhas e registrar logs detalhados.

Configure tratamento de erro:

Arraste um node Set após o HTTP Request.
Ative a opção “Continue On Fail”.
Adicione um node Function que verifica items[0].json.error?.code.
Use Retry (max 3 tentativas) no HTTP Request se o código for 429 ou 500.

Código	Significado	Ação recomendada
400	Bad Request	Verifique payload JSON.
401	Unauthorized	Renove token ou credencial.
429	Too Many Requests	Aplicar backoff e retry.
500	Internal Server Error	Retry após 2 s.
503	Service Unavailable	Verificar disponibilidade da API.

Para detalhes completos dos códigos, veja a documentação oficial de erros.

Curiosidade: o node HTTP Request permite habilitar “Response Size Limit” para evitar gargalos quando a API devolve respostas gigantes.

Melhores práticas e otimizações avançadas

Para escalar seu workflow, cache respostas, paralelize requisições e respeite limites de taxa. Essas táticas reduzem custos e melhoram a latência.

Estratégias recomendadas:

Cache de respostas: use o node Cache (Redis ou memória) para armazenar resultados por chave de prompt.
Paralelismo: divida lotes de prompts em múltiplos nodes HTTP Request com “Execute Once” desativado.
Rate limiting: configure “Throttle” (ex.: 20 req/s) antes de enviar ao endpoint.
Escala na VPS: reserve 4 GB RAM e CPU 2 cores para workloads intensos; ajuste o parâmetro “MAX_CONCURRENCY”.

Otimização	Configuração	Benefício
Cache (Redis)	TTL 300 s	Reduz chamadas em 40 %.
Paralelismo	5 workers simultâneos	Acelera processamento em lote.
Throttle	20 req/s	Evita 429.
Docker Swarm	Replicas 3	Alta disponibilidade.

Para aprofundar, veja o n8n guia completo com exemplos de cache e paralelismo.

Curiosidade: a Evolution API aceita o parâmetro stream que devolve tokens em tempo real; combinar isso com “WebSocket” no n8n permite respostas instantâneas em dashboards.

Perguntas frequentes sobre Evolution API e como usar com n8n

O que é Evolution API?

Evolution API é uma API de inteligência artificial que disponibiliza modelos de linguagem com foco em baixo custo e latência para o Brasil, permitindo enviar prompts e receber respostas estruturadas via HTTP.

É necessário pagar para usar Evolution API?

Sim, a Evolution API possui planos pagos, mas oferece preços significativamente menores que concorrentes como OpenAI, além de um plano gratuito com limites de uso mensais.

Qual a diferença entre Evolution API e outras APIs de IA?

Além do custo reduzido, a Evolution API oferece servidores localizados no Brasil, menor latência e a possibilidade de personalizar modelos para contextos regionais, algo menos comum em APIs como OpenAI ou Gemini.

Posso usar Evolution API em um workflow n8n auto‑hosted?

Sim, a API pode ser consumida em qualquer ambiente n8n, inclusive auto‑hosted, bastando configurar o node HTTP Request com a URL e autenticação adequadas.

Como configurar autenticação na Evolution API dentro do n8n?

Crie uma credencial do tipo API Key ou OAuth2 no n8n, armazenando o token (ex.: Bearer SEU_TOKEN) de forma criptografada e selecione‑a no node HTTP Request na seção “Authentication”.

Quais limites de taxa (rate limits) a Evolution API impõe?

A Evolution API geralmente permite até 20 requisições por segundo por chave, retornando código 429 quando o limite é excedido; recomenda‑se usar throttling ou retry exponencial.

É possível depurar chamadas da Evolution API no n8n?

Sim, o n8n captura o código de status e o corpo da resposta, permitindo visualizar logs, usar nodes “Set” com “Continue On Fail” e criar workflows de erro para inspeção detalhada.

Existe suporte oficial para Evolution API no n8n?

Não há um plugin oficial, mas a comunidade n8n fornece exemplos e o próprio node HTTP Request cobre todas as necessidades de integração.

Desbrave a Automação com Evolution API e n8n

Integrar a Evolution API ao n8n permite criar fluxos de trabalho inteligentes, econômicos e de baixa latência, aproveitando o poder da IA localmente. Com as etapas apresentadas, você já pode enviar prompts, tratar respostas e escalar suas automações com segurança.

Configuração rápida usando o node HTTP Request.
Autenticação segura via credenciais n8n.
Tratamento de erros e retry automático.
Otimizações como cache, paralelismo e controle de taxa.

Explore mais artigos sobre automação no n8n e descubra novas possibilidades na nossa categoria de automação n8n.

Quer mais sobre o assunto? Veja todos os artigos de n8n ou a lista completa de artigos.