Evolution QRCode Connector (Next.js)

Aplicação Next.js 14 que centraliza o fluxo de conexão do WhatsApp com a Evolution API via QR Code. Todo o tráfego sensível (URL base e chave privada) passa pelo backend do Next, garantindo que o navegador nunca tenha contato direto com os segredos da Evolution.

Índice

• Visão geral
• Principais recursos
• Stack utilizada
• Requisitos
• Variáveis de ambiente
• Configuração e execução
• Scripts npm disponíveis
• Estrutura do projeto
• Fluxo de conexão
• Integração com Evolution API
• Execução com Docker
• Documentação adicional
• Solução de problemas
• Próximos passos sugeridos

Visão geral

O conector foi pensado para ser uma camada fina entre o usuário final e a Evolution API. Ele expõe uma interface única onde o operador informa o nome da instância e, a partir daí, o aplicativo se encarrega de:

1. Verificar o estado atual da instância.
2. Gerar QR Code e/ou código de pareamento quando necessário.
3. Acompanhar o estado de conexão até a confirmação de sucesso.
4. Exibir métricas e dados do número conectado, permitindo desconectar ou reiniciar a instância.

Principais recursos

• Fluxo orientado por etapas com estados instance, qrcode e connected.
• Geração automática do QR Code e código de pareamento a cada 45 segundos.
• Monitoramento do estado (instance/connectionState) com polling a cada 5 segundos.
• Exibição de foto, nome e número do perfil conectado (com fallback seguro).
• Métricas de contatos, chats e mensagens, com formatação localizada (pt-BR).
• Ações administrativas rápidas: atualizar dados, reiniciar ou desconectar a instância.
• Proxy backend que encapsula API_BASE_URL e API_KEY, evitando vazamentos no frontend.

Stack utilizada

• Next.js 14 (App Router) e React 18.
• TypeScript para tipagem estática.
• CSS module global (app/globals.css) com design responsivo básico.
• Node.js 20 nas imagens Docker multi-stage.

Requisitos

• Node.js 18 ou 20.
• npm 9+.
• Chave válida da Evolution API e endpoint acessível.
• Acesso às dependências no primeiro npm install (caso esteja em ambiente restrito, execute a instalação fora dele e replique a pasta node_modules).

Variáveis de ambiente

Variável	Obrigatório	Descrição	Exemplo
API_BASE_URL	Sim	URL interna da Evolution API acessível somente pelo backend Next.js.	http://evolution-api:3000
API_KEY	Sim	Chave privada que autoriza as chamadas à Evolution API.	minha-chave-secreta
PORT	Não	Porta exposta pelo Next.js (usada no Docker e Traefik).	3000 (padrão)

Copie .env.example para .env.local (desenvolvimento) ou .env (produção/Docker) e ajuste os valores conforme o ambiente.

Configuração e execução

1. Instalar dependências

   npm install

2. Rodar em desenvolvimento

   npm run dev

   O aplicativo ficará disponível em http://localhost:3000.

3. Gerar build de produção

   npm run build
   npm run start

4. Rodar lint (opcional, recomendado antes de commits)

   npm run lint

Scripts npm disponíveis

Script	Descrição
npm run dev	Inicia o servidor Next.js com hot reload.
npm run build	Gera a build otimizada de produção.
npm run start	Sobe o servidor Next em modo produção.
npm run lint	Executa as regras de lint do Next/ESLint.

Estrutura do projeto

.
├── app/
│   ├── api/whatsapp/[...path]/route.ts   # Proxy de todas as rotas Evolution API
│   ├── components/Connector.tsx          # SPA principal com todo o fluxo de conexão
│   ├── globals.css                       # Estilos globais da interface
│   ├── layout.tsx                        # Fonte Roboto + metadados padrão
│   └── page.tsx                          # Entrada que renderiza o Connector
├── lib/utils.ts                          # Normalização de instâncias, contadores e QR
├── docs/                                 # Referências da Evolution API (Postman + markdown)
├── Dockerfile                            # Build multi-stage com imagem enxuta para produção
├── docker-compose.yml                    # Stack de exemplo com Traefik e rede bridge local
└── .env.example                          # Modelo das variáveis de ambiente

Fluxo de conexão

1. O usuário informa o nome da instância e submete o formulário.
2. O backend checa /instance/connectionState; se já estiver conectada, exibe a tela de sucesso imediatamente.
3. Para instâncias desconectadas, a aplicação aciona /instance/connect e renderiza o QR Code/código de pareamento, renovando a cada 45s.
4. Enquanto o QR Code está visível, um polling periódico verifica o estado da instância.
5. Quando a Evolution API retorna CONNECTED/OPEN, o app busca detalhes adicionais (fetchInstances, fetchProfilePictureUrl) e atualiza a tela de métricas.
6. A partir da tela conectada é possível atualizar os dados, reiniciar (/instance/restart) ou desconectar (/instance/logout) a instância.

Integração com Evolution API

O arquivo app/api/whatsapp/[...path]/route.ts funciona como um proxy genérico. Ele:

• Valida a presença de API_BASE_URL e API_KEY antes de processar qualquer requisição.
• Monta a URL de destino respeitando os segmentos e querystring informados pelo frontend.
• Encaminha somente cabeçalhos seguros (content-type, accept) e injeta apikey automaticamente.
• Remove cabeçalhos potencialmente problemáticos da resposta (ex.: transfer-encoding).
• Garante que falhas retornem 502 com mensagem amigável sem expor detalhes sensíveis.

Essa abordagem permite que o frontend faça fetch para /api/whatsapp/... sem conhecer a topologia real da Evolution API.

Execução com Docker

Build manual

docker build -t evolution-qrcode-connector .
docker run --rm -p 3000:3000 \
  -e API_BASE_URL=http://evolution-api:3000 \
  -e API_KEY=troque-por-sua-chave \
  evolution-qrcode-connector

Docker Compose + Traefik

O arquivo docker-compose.yml serve como exemplo com labels Traefik e rede bridge interna. Ajuste o domínio (connector.example.com) e personalize o middleware opcional conforme a sua topologia.

1. Substitua o host nas labels Traefik e, se usar prefixo, edite ou remova o middleware StripPrefix.
2. Defina as variáveis em .env (ou via Portainer/secret manager).
3. Caso precise compartilhar a rede com outras stacks, altere o bloco networks para usar uma rede externa existente.
4. Suba a stack:

   docker compose up -d --build

Para testar sem Traefik, descomente a seção ports e acesse http://localhost:3000.

Documentação adicional

A pasta docs/ contém:

• Coleção Postman (Evolution API - v2.2.2.postman_collection.json) alinhada com as rotas utilizadas.
• Referências em Markdown para controladores da Evolution API (chats, grupos, instâncias, integrações etc.).

Esses materiais servem como apoio para depurar respostas ou implementar novos fluxos no conector.

Solução de problemas

• Missing environment variables no console → verifique .env(.local) e restart do servidor.
• Erro 502 "Erro ao comunicar com a Evolution API" → valide API_BASE_URL (deve ser acessível a partir do backend) e se a chave não expirou.
• QR Code não aparece ou expira muito rápido → confirme que o nome da instância está correto e que o relógio do servidor Evolution não está defasado.
• Foto ou métricas não carregam → as contagens são opcionais; confira se a instância possui permissões suficientes ou se a rota /chat/fetchProfilePictureUrl está habilitada.

Próximos passos sugeridos

1. Configurar pipelines (CI/CD) que executem npm run lint e npm run build em ambientes com acesso à internet.
2. Personalizar estilos em app/globals.css ou migrar para um design system da empresa, mantendo o fluxo intacto.
3. Estender o proxy (app/api/whatsapp) conforme novas rotas da Evolution API forem necessárias.
4. Publicar uma nova imagem Docker em um registry privado para simplificar deploys futuros.