Evolution API — WhatsApp por Loja

A Evolution API é uma solução não-oficial que permite conectar números WhatsApp pessoais/comerciais via QR code, sem precisar de aprovação Meta WABA.

Quando é usada

• Lojas que usam número WhatsApp comum (não WABA)
• Conectado por QR code na interface Evolution
• Permite receber e enviar mensagens sem limite de template
• Sem os requisitos de aprovação da Meta

Diferenças vs Meta Cloud API

Aspecto	Evolution	Meta Cloud API
Aprovação	Nenhuma	Requer WABA + aprovação Meta
Templates	Não obrigatório	Obrigatório fora da janela 24h
Volume	Depende do número	Limitado por tier
Custo	Evolution (self-hosted)	Meta (por conversa)
Risco	ToS do WhatsApp	Oficial
Confiabilidade	Menor (pode ser bloqueado)	Alta

Configuração por loja

Cada loja com Evolution tem uma entrada em StoreWhatsappNumber:

Campo	Descrição
provider	"evolution" (ou outro valor não "meta_cloud")
evolutionInstanceName	Nome da instância no servidor Evolution
evolutionApiKey	API key da instância (criptografada AES-256-GCM)
storeId	FK para a loja proprietária
chatwootInboxId	Inbox do Chatwoot vinculado

Fluxo de mensagem inbound (Evolution)

Cliente → WhatsApp
  → Evolution API (servidor)
  → POST /webhooks/whatsapp/evolution (webhook CRM)
  → CRM processa (identifica org/loja pelo número)
  → CRM repassa para Chatwoot via API
  → Chatwoot exibe para o atendente

Fluxo de mensagem outbound (Evolution)

Campanha ou atendente
  → CRM coloca job na fila whatsapp-send
  → Processor identifica provider=evolution
  → POST {evolutionInstanceUrl}/message/sendText/{instance}
    Authorization: Bearer {evolutionApiKey}
  → Evolution envia via número conectado

Endpoints da Evolution usados

# Enviar texto
POST {baseUrl}/message/sendText/{instanceName}

# Enviar template (WABA-like no Evolution Pro)
POST {baseUrl}/message/sendTemplate/{instanceName}

# Status da instância
GET {baseUrl}/instance/fetchInstances/{instanceName}

# QR code para conexão
GET {baseUrl}/instance/qrcode/{instanceName}

Gestão de instâncias

O painel do Evolution API fica em URL separada (não gerenciada pelo CRM diretamente). Para conectar um novo número:

1. Criar instância no painel Evolution
2. Escanear QR code com o WhatsApp da loja
3. Copiar o nome da instância e API key
4. Cadastrar no CRM via PATCH /whatsapp/numbers/:id
5. CRM criptografa a API key antes de salvar

Webhook do Evolution

O servidor Evolution envia eventos para POST /webhooks/whatsapp/evolution.

A validação é feita verificando que o instanceName no payload corresponde a uma instância cadastrada na organização.

Atenção: A Evolution não usa HMAC por padrão. O endpoint é protegido pela combinação organização + nome da instância.

Limitações

• Não suporta messagingLimitTier (sem tier de volume)
• Qualidade do serviço depende do servidor Evolution e da saúde do número
• Números podem ser banidos pelo WhatsApp se enviarem spam em alto volume
• Não tem relatórios de entrega tão detalhados quanto a WABA