A instância está criada, o painel responde, e o quadrado onde deveria estar o QR code fica em branco, girando, ou devolve um erro genérico. Se te serve de consolo: “evolution api não gera qr code” é uma das buscas mais frequentes de todo o ecossistema da ferramenta, com centenas de buscas mensais só no Brasil. O problema é comum, as causas são poucas e a ordem de verificação abaixo resolve a maioria dos casos em menos de meia hora.
TL;DR: Quando a Evolution API não gera QR code, as causas em ordem de probabilidade são: (1) versão desatualizada frente a mudança no protocolo do WhatsApp, (2) instância em estado corrompido que precisa ser deletada e recriada, (3) recursos insuficientes na VPS (RAM no limite), (4) configuração de integração interferindo na geração e (5) onda coletiva de instabilidade, que só o tempo e uma release nova resolvem. Verifique nessa ordem e você cobre do mais provável ao menos controlável.
Passo 1: confirme se o problema é seu ou de todo mundo
Antes de mexer em qualquer configuração, gaste cinco minutos nos grupos e nas issues do repositório do projeto. Quando a Meta altera o protocolo web, a geração de QR quebra para milhares de instâncias ao mesmo tempo, os canais da comunidade explodem e a única correção real é a release que a equipe do projeto publica em resposta. Se a onda é coletiva, pare aqui: reconfigurar a sua VPS durante uma onda é procurar vazamento na sua casa durante a enchente do bairro.
Passo 2: versão
Se o problema é só seu, a causa mais provável é defasagem: a sua versão da Evolution API fala um dialeto do protocolo que o WhatsApp já abandonou. Compare a sua versão com a última release do repositório. Atualize com método: backup do banco antes, leitura das notas da release (payloads mudam, como avisamos no artigo de problemas comuns da Evolution API) e teste em instância de homologação se a operação for de produção.
Passo 3: recrie a instância (do jeito certo)
Instância que já teve sessão e a perdeu de forma suja pode ficar num estado em que pede QR mas não consegue gerá-lo. A correção não é reiniciar: é deletar a instância (incluindo os dados de sessão persistidos) e criar uma nova com outro nome. Nome novo importa: resíduo de sessão antiga com o mesmo identificador é uma causa conhecida de recriação que nasce quebrada.
Passo 4: olhe a máquina
A geração da sessão é um dos momentos de maior consumo do ciclo de vida da instância. VPS com RAM no talo falha exatamente aí: o processo tenta subir a sessão, o sistema mata por falta de memória, o painel mostra o quadrado vazio. Cheque o uso de memória no momento da tentativa (não a média do dia). Se estiver acima de 85%, o QR é o sintoma e a máquina é a doença, e o dimensionamento correto está em VPS para Evolution API.
Passo 5: desligue integrações e tente de novo
Configurações de integração ativas na instância (Chatwoot, typebot, webhooks com URL inválida) podem atrapalhar o ciclo de conexão em algumas combinações de versão. O teste limpo: crie uma instância nova sem nenhuma integração configurada e tente o QR. Se funcionar, o conflito está numa das integrações; reative uma a uma até achar a culpada.
Se conectou e caiu em seguida
QR gerado, escaneado, conectado por segundos e derrubado: esse é outro problema, com outras causas (sessão anterior não encerrada no celular, número em observação pela plataforma). O diagnóstico está em Evolution API desconectando. E se as quedas viram rotina, vale ler o aviso honesto do próprio repositório do projeto (2026), que descreve o modo web como sujeito a limitações: gerar QR code é a cerimônia de entrada de uma conexão que a plataforma não reconhece, e parte da fragilidade mora aí, não na sua configuração. A rota que elimina a cerimônia por completo (API oficial, sem QR, com o app do celular preservado pelo modo coexistência) está em migração com coexistência, e é o desenho nativo do Cubo Suite.
Por que o QR code da Evolution API expira tão rápido?
O QR de pareamento do WhatsApp tem validade curta por desenho de segurança da plataforma, e o painel gera novos em ciclo. Se todos expiram antes de você escanear, o problema não é a validade: é lentidão na geração (recursos) ou falha do ciclo (versão).
Preciso deixar o celular ligado para gerar o QR?
Para gerar, o celular precisa escanear, então sim, com o número ativo no aparelho. Depois de pareada, a sessão web funciona com o celular offline por períodos, mas a saúde da sessão degrada com o aparelho muito tempo fora do ar.
Recriar a instância apaga minhas conversas?
Apaga os dados de sessão e o que estiver persistido da instância no seu banco. As conversas no celular continuam intactas: o aplicativo é a fonte, a instância é um espelho. É mais um motivo para não deixar histórico importante existindo apenas no lado da API.
Deixe um comentário