# Integração EvolutionGO — Passo a passo para atualizar no cPanel

Data: 05/10/2026

## O que mudou

O sistema passa a aceitar um 3º provedor de WhatsApp, **EvolutionGO**
(`https://zap.jf.eng.br`), junto com o Evolution API e o Uazapi.
**Evolution API e Uazapi continuam funcionando exatamente como antes.**

| Arquivo | Tipo |
|---|---|
| `backend/app/Services/WhatsApp/EvolutionGoWhatsAppService.php` | NOVO: comunicação com a API EvolutionGO |
| `backend/app/Http/Controllers/Webhooks/EvoGoWebhookController.php` | NOVO: recebe os avisos de conectado/desconectado |
| `backend/database/migrations/2026_10_05_000000_add_evolutiongo_provider_to_whatsapp_integrations.php` | NOVO: adiciona `evolutiongo` à coluna `provider` |
| `backend/app/Http/Controllers/Api/WhatsAppController.php` | alterado: escolhe o serviço EvolutionGO |
| `backend/app/Http/Controllers/Api/WhatsAppIntegrationController.php` | alterado: teste de conexão do EvolutionGO |
| `backend/app/Http/Requests/WhatsAppIntegrationRequest.php` | alterado: aceita o provedor `evolutiongo` |
| `backend/app/Jobs/ProcessWhatsAppQueue.php` | alterado: a fila envia pelo EvolutionGO quando for o caso |
| `backend/app/Jobs/CheckWhatsAppConnections.php` | alterado: confere o status do EvolutionGO a cada minuto |
| `backend/routes/api.php` | alterado: nova rota `/api/v1/webhooks/EvoGO` |
| `frontend/src/components/WhatsAppIntegrationModal.tsx` | alterado: opção "EvolutionGO" no cadastro |
| `frontend/src/pages/WhatsAppIntegrationsPage.tsx` | alterado: contador do EvolutionGO |

Conteúdo desta pasta (`deploy/evolutiongo/`):

- `arquivos/`: versão final de todos os arquivos acima, com o mesmo caminho do projeto.
- `backup_original/`: os arquivos como eram antes (para desfazer).
- `evolutiongo.patch`: só as diferenças, para aplicar com `git apply`.
- `frontend_build/`: frontend já compilado (com EvolutionGO), pronto para copiar para `backend/public/`.
- `backup_frontend_publicado/`: o `index.html` que estava no ar antes.

---

## A) Nesta pasta (derenbox.one), onde os arquivos já foram copiados

Os arquivos de código já estão no lugar. Pelo **Terminal do cPanel**:

### 1. Rodar a migration (somente esta)

> **Status em derenbox.one: JÁ FEITO em 05/10/2026.**

```bash
cd ~/derenbox.one/backend
php -v                             # precisa ser PHP 8.3 ou mais novo
php artisan migrate --path=database/migrations/2026_10_05_000000_add_evolutiongo_provider_to_whatsapp_integrations.php --force
```

> Com `--path`, só esta migration roda. Ela apenas acrescenta um valor ao
> ENUM e não altera nenhum registro existente.
> Se `php -v` mostrar uma versão menor que 8.3, use o PHP do domínio, por exemplo
> `/opt/cpanel/ea-php83/root/usr/bin/php artisan ...`.

### 2. Publicar o frontend (opção "EvolutionGO" no admin)

> **Status em derenbox.one: JÁ FEITO em 05/10/2026.** O `index.html` anterior
> está salvo em `deploy/evolutiongo/backup_frontend_publicado/`.

O build **não funciona no terminal do cPanel**: o `node_modules` de lá não tem os
binários Linux do vite/rollup. Por isso o build pronto está no pacote, em
`deploy/evolutiongo/frontend_build/`. Basta copiá-lo, **sem npm**:

```bash
cd ~/derenbox.one
# 1) guardar o index.html atual (para poder voltar)
cp backend/public/index.html backend/public/index.html.antes-evolutiongo
# 2) copiar primeiro os assets (arquivos novos, não quebram nada)
cp -r deploy/evolutiongo/frontend_build/assets/. backend/public/assets/
# 3) por último o index.html (é ele que "liga" a versão nova)
cp deploy/evolutiongo/frontend_build/index.html backend/public/index.html
```

Depois abra o site e faça Ctrl+F5. No admin → Integrações WhatsApp → Nova
integração, o provedor **EvolutionGO** deve aparecer.

Para voltar à versão anterior do frontend:
`cp backend/public/index.html.antes-evolutiongo backend/public/index.html`
(os assets antigos continuam na pasta).

> **Atenção:** nunca rode `npm run build` e `cp` em sequência sem `&&`.
> Se o build falhar, o `cp` publica um `dist/` antigo. Use sempre
> `npm run build && cp -r dist/* ../backend/public/`.
> Para voltar a compilar no próprio cPanel no futuro, seria preciso reinstalar
> as dependências (`rm -rf node_modules && npm ci`, com o Node de
> `~/nodevenv/game.jf.eng.br/backend/20/bin` no PATH).

### 3. Testar

1. Admin → Integrações WhatsApp → **Nova integração**
   - Provedor: **EvolutionGO**
   - URL da API: `https://zap.jf.eng.br`
   - API Key: a **GLOBAL_API_KEY** do servidor EvolutionGO
   - Ao salvar, o sistema testa a conexão. Se a chave estiver errada, aparece "API Key inválida".
2. Para testar com um usuário, conecte um WhatsApp. O QR Code e o código de
   pareamento devem aparecer.
3. Depois de escanear, o status muda para "conectado" em até 1 minuto
   (pelo webhook ou pela verificação automática).
4. Envie uma mensagem de teste e confira em `backend/storage/logs/laravel.log`
   as linhas `EvolutionGO: text message sent`.

> Se o servidor usar OPcache sem revalidação e as mudanças não surtirem efeito,
> reinicie o PHP em cPanel → MultiPHP Manager (ou aguarde alguns minutos).

---

## B) Para replicar em OUTRA pasta/servidor

Faça **backup da pasta de destino** antes de começar.

**Opção 1: copiar arquivos.** Use quando a outra pasta estiver na mesma versão do sistema.

```bash
cp -r deploy/evolutiongo/arquivos/* /caminho/da/outra/pasta/
```

**Opção 2: aplicar o patch.** É a mais segura se a outra pasta tiver diferenças.

```bash
cd /caminho/da/outra/pasta
git apply --check deploy/evolutiongo/evolutiongo.patch   # só testa, não altera nada
git apply deploy/evolutiongo/evolutiongo.patch
```

Se o `--check` acusar conflito, não force. Aplique as mudanças à mão, usando o
patch como guia (cada arquivo alterado tem poucas linhas novas).

Depois, nos dois casos, faça na pasta de destino os passos **A.1** (migration), **A.2**
(copiar `frontend_build/`, sem npm) e **A.3** (testar).

> O `frontend_build/` foi compilado a partir do `src/` e do `.env` do derenbox.one.
> Se a outra pasta tiver um frontend diferente (outro `.env` ou outras telas),
> compile lá mesmo ou me peça um build novo.

---

## C) Como desfazer (rollback)

1. Apague as integrações EvolutionGO pelo admin, se alguma foi criada.
2. Restaure os arquivos originais:
   ```bash
   cp -r deploy/evolutiongo/backup_original/* ./
   ```
3. Remova os 2 arquivos novos de código:
   ```bash
   rm backend/app/Services/WhatsApp/EvolutionGoWhatsAppService.php
   rm backend/app/Http/Controllers/Webhooks/EvoGoWebhookController.php
   ```
4. Se quiser reverter a migration:
   ```bash
   cd backend
   php artisan migrate:rollback --path=database/migrations/2026_10_05_000000_add_evolutiongo_provider_to_whatsapp_integrations.php --force
   rm database/migrations/2026_10_05_000000_add_evolutiongo_provider_to_whatsapp_integrations.php
   ```
5. Volte o frontend: `cp deploy/evolutiongo/backup_frontend_publicado/index.html backend/public/index.html`.

---

## Notas técnicas

- **Autenticação:** a API Key da integração é a GLOBAL_API_KEY. Cada conexão de
  usuário recebe um token próprio de instância, gerado pelo sistema e salvo em
  `whatsapp_connections.token`.
- **Webhook:** o próprio sistema configura a URL ao conectar cada instância
  (`/api/v1/webhooks/EvoGO?instance=...&sig=...`). Não é preciso configurar nada
  no EvolutionGO. A assinatura `sig` impede que terceiros forjem avisos de desconexão.
- **Rede de segurança:** mesmo que o webhook falhe, o job `CheckWhatsAppConnections`
  (já agendado a cada minuto) consulta `/instance/status` das conexões EvolutionGO.