# Capacidades e limites — wpp-engine v1

> Documento honesto para **colocar o produto em ação** com clientes: o que vender, o que não prometer, e o que alinhar com o time (Lucas / backend).  
> **Data:** 2026-07-18  
> Fontes: OpenAPI de produção, health check, audit `docs/status-report-wpp-engine-2026-07-08.md`, ADR-006, quickstart do console.

---

## 1. O produto está funcional?

**Sim, para o núcleo v1**, com ressalvas claras:

| Verificação (2026-07-19) | Resultado |
|--------------------------|-----------|
| Engine `GET /v1/health` | `status: ok`, versão `0.1.0` |
| Rotas protegidas sem key | `401` (auth ativa) |
| OpenAPI publicado | 11 paths de negócio + docs/Swagger |
| Console + BFF | Sessões, mensagens, webhook config, API key one-shot |
| Onboarding de tenant | **Self-service com aprovação** (`/signup` → admin aprova → credenciais) |
| Rate limit / DLQ API | Rate limit **sim** (`429`); DLQ listagem pública **não** |
| Grupos / botões / templates | Grupos: **opt-in por sessão** (default desligado, inbound ignorado); botões/templates: **não** |

Conclusão prática: **pode ir a produção com clientes**, desde que o contrato comercial e o adapter do produto (ex. Clinik.One) respeitem a matriz abaixo — especialmente **canal não oficial** e o fato de grupos serem participação passiva/opt-in, não administração de grupos.

---

## 2. Matriz — o que PODE hoje

| Capacidade | Status | Como |
|------------|--------|------|
| Autenticar com API key | Sim | `Authorization: Bearer wae_live_*` |
| Criar sessão + QR | Sim | `POST /v1/sessions` |
| Renovar QR | Sim | `GET /v1/sessions/{id}/qr` |
| Listar / detalhar / revogar sessão | Sim | GET list, GET id, DELETE |
| Enviar texto | Sim | `content.type = text` (até 4096) |
| Enviar imagem / áudio / vídeo / documento | Sim | Upload → `media_id` → send; áudio = PTT (voice); MP3→OGG/Opus automático no outbound |
| Receber mídia no webhook | Sim | `content_type`, `media_id`, `mime_type`, `signed_url` |
| Idempotência de envio | Sim | `idempotency_key` 8–120 (permanente) |
| Listar / buscar mensagens | Sim | GET session messages / GET message (com `media_asset_id`) |
| Webhook único por tenant | Sim | `PATCH /v1/tenants/me` |
| Eventos de mensagem + sessão | Sim | received/sent/delivered/read/failed + session.* |
| Assinatura HMAC | Sim | SHA-256 hex do raw body |
| Confirmação sent / delivered / read / failed | Sim | Via webhooks (`failed.reason` enum estável) |
| Rate limit HTTP | Sim | `429` + `Retry-After`. Três camadas: 60 req/s por tenant, 6.000 req/min por IP, 20 falhas de auth por IP a cada 10 min |
| Filtro de grupos inbound | Sim | Default descarta `@g.us`; `@broadcast` sempre descartado |
| Participar de grupos (opt-in) | Sim | `groups` na sessão + allowlist por grupo (`PUT /v1/sessions/{id}/groups/{jid}`) |
| Enviar para grupo | Sim | `to_group` em `POST /v1/sessions/{id}/messages` (teto diário próprio) |
| Webhook só quando marcado no grupo | Sim | `groups.notify = mentions` → `group.message.received` |
| Resumo diário de grupo por LLM | Sim | `groups.digest` → `group.digest.ready` |
| Reconectar sessão | Sim | `POST /v1/sessions/{id}/reconnect` (sem QR se auth válida; senão QR) |
| Upload por URL pública | Sim | `POST /v1/media/upload-url` (HTTPS, anti-SSRF) |
| Conferir webhook (GET) | Sim | `GET /v1/tenants/me` — watchdog: PATCH só em drift |
| Rotação de API key | Sim | Via suporte OneClient (one-shot no console) |
| Multi-tenant (1 key por cliente) | Sim | Isolamento por tenant |
| Health / OpenAPI / Swagger | Sim | `/v1/health`, `/v1/openapi.json`, `/v1/docs` |
| Console + signup com aprovação | Sim | `/signup`, login, QR, key one-shot, config webhook |

---

## 3. Matriz — o que NÃO PODE hoje

| Capacidade | Status | Nota comercial |
|------------|--------|----------------|
| **Administrar grupos (criar, admins, convite)** | Não | Participar de grupo existente é suportado; criar/administrar não |
| Botões interativos / listas | Não | Não prometa UI de botões |
| Templates HSM / Meta Cloud oficial | Não | Canal é **não oficial** (WAHA sob o engine) |
| Enquetes, reações, localização, contato | Não | — |
| “Digitando…” / presença | Não | — |
| Verificar se um número tem WhatsApp | Não | — |
| Disconnect dedicado (stop sem revogar) | Não | Use DELETE para revogar; reconnect para voltar |
| Múltiplas API keys / rotação self-service | Parcial | 1 key; rotação via suporte OneClient |
| Criar tenant via API pública | Não | Cadastro em `/signup` com aprovação (sem endpoint público de provisão) |
| Múltiplos webhooks | Não | 1 URL |
| Replay / DLQ via API pública | Parcial | Retry admin existe; UI DLQ do console é mock |
| SDK oficial | Não | REST puro (como muitos usam Evolution) |

---

## 4. Comparativo honesto (Evolution API · Z-API · wpp-engine)

Comparação **de posicionamento**, não de feature-parity pixel a pixel. Use para conversa com cliente e para decidir o adapter.

| Tema | Evolution API (típico) | Z-API (típico) | **wpp-engine v1** |
|------|------------------------|----------------|-------------------|
| Modelo | Self-host / cloud de terceiros | SaaS brasileiro | SaaS OneClient (engine gerenciado) |
| Auth | Instance + apikey / token | Instance + token | Bearer `wae_live_*` por tenant |
| Sessão / QR | Sim | Sim | Sim |
| Texto + mídia | Sim | Sim | Sim (upload multipart **ou** URL → media_id) |
| Grupos | Em geral sim (amplo) | Em geral sim | Participação opt-in (ler, enviar, resumir) — **sem administração** |
| Botões / listas | Frequentemente sim | Frequentemente sim | **Não** |
| Webhooks + status de mensagem | Sim | Sim | Sim (HMAC próprio) |
| Multi-tenant nativo | Depende do deploy | Conta/instâncias | Sim (tenant + RLS no backend) |
| Console | Varia | Painel web | Console Next.js + signup com aprovação |
| Canal | Não oficial | Não oficial | Não oficial (WAHA atrás do Fastify) |
| Rate limit / DLQ | Varia | Varia | Rate limit **sim** (60/s); DLQ listagem pública **não** |
| OpenAPI | Varia | Parcial | **Sim** (`/v1/openapi.json`) |

**Quando wpp-engine é a escolha certa**

- Você quer um **fornecedor OneClient** com tenant isolado, envelope de erro padrão e HMAC.
- O caso de uso é **1:1** (paciente ↔ clínica): texto + mídia + confirmação de entrega.
- Prefere **API gerenciada** a operar Evolution self-host.

**Quando NÃO é a escolha certa (ainda)**

- O cliente exige **administração de grupos** (criar grupo, mexer em admins), botões ou features ricas de “WhatsApp marketing”.
- O compliance exige **Cloud API oficial Meta** (templates aprovados, WABA).
- Precisa de **self-service total** (criar conta, girar key, DLQ) sem intervenção humana.

---

## 5. Riscos do canal não oficial (política de uso)

O motor sob o engine é baseado em stack tipo WAHA / web não oficial. Isso implica:

1. **Risco de ban / restrição** do número pela Meta — inerente ao modelo.
2. **1 sessão ≈ 1 número ≈ processo vivo** — sessão cai → precisa QR de novo (`session.disconnected`).
3. **Não use** para spam, cold blast massivo ou listas compradas.
4. **Boas práticas sugeridas:**
   - Chip / número dedicado ao produto.
   - Warm-up gradual de volume.
   - Conteúdo conversacional (respostas a opt-in).
   - Monitorar `session.disconnected` e `message.failed`.
   - Separar números de marketing vs. atendimento se o volume crescer.
5. Para fluxos que **exijam** oficial (HSM, WABA), planejar caminho paralelo Meta Cloud API — fora deste produto v1.

---

## 6. Como integrar nos produtos OneClient (ex.: Clinik.One)

Recomendação do audit interno (2026-07-08), ainda válida:

1. Adapter HTTP → `https://wpp-api.oneclient.tech/v1/*` com Bearer por clínica/tenant.
2. Persistir `tenant_id`, `session_id` e a API key cifrada.
3. Receptor de webhook com HMAC + dedupe por `event.id`.
4. Para Whisper: use `data.media_id` do `message.received` → `GET /v1/media/{id}`.
5. Rate limit já existe no engine (ainda assim, fila no produto é boa prática).
6. Onboarding de nova clínica: `/signup` → aprovação no admin → credenciais; rotação de key: suporte OneClient.
7. Watchdog: `GET /v1/tenants/me` periódico; `PATCH` **só** se `webhook_url` divergir (e **sem** enviar `webhook_secret`).
8. Sessão caiu: preferir `POST .../reconnect` antes de alertar humano; se voltar `qr`, aí sim peça novo scan.
9. Carrossel/imagem por URL: `POST /v1/media/upload-url` → use o `media_id` no envio.

Esforço estimado do adapter Hermes: **baixo–moderado** após o upgrade de 2026-07-18 (mídia no webhook + PTT já ok + grupos filtrados).

---

## 7. Pendências resolvidas (upgrade Hermes 2026-07-18)

As perguntas antigas `[confirmar com o dev]` foram respondidas no código do `wpp-engine` e documentadas em:

- [`docs/2026-07-18-respostas-integracao-hermes.md`](../2026-07-18-respostas-integracao-hermes.md)
- Este upgrade (webhook media, GET message, filtro grupo, rate limit, retenção, rotate key, failed reason)

**Ainda fora de escopo / mitigado no consumidor:** staging dedicado, ordem total de ACKs, API pública de listagem DLQ, botões como feature, administração de grupos.
(Conversão de áudio outbound PTT: **feita no engine** via WAHA `convert/voice` desde 2026-07-20.)

---

## 8. Checklist de go-live com o primeiro cliente

- [ ] Conta aprovada via `/signup` + key revelada com segurança no console
- [ ] Webhook HTTPS + HMAC testado com evento real (incl. áudio inbound → `media_id`)
- [ ] Sessão conectada e monitorada (`session.disconnected`)
- [ ] Envio texto + áudio PTT (MP3→OGG automático) + imagem validados **no celular**
- [ ] Confirmações `delivered`/`read`/`failed` refletidas no produto
- [ ] Contrato comercial alinhado: **grupos só por opt-in (sem administração) / sem botões / canal não oficial**
- [ ] Se usar grupos: política (`notify`) e allowlist revisadas, teto diário por grupo aceito, retenção de `group_messages` alinhada com LGPD
- [ ] Contato operacional OneClient para rotação de key e recuperação de sessão
- [ ] Volume inicial controlado (sem blast); rate limit 60/s no engine

---

## Links

- [Índice da documentação](./README.md)
- [Guia de integração](./2026-07-18-guia-de-integracao.md)
- [Referência API v1](./2026-07-18-referencia-api-v1.md)
- [Webhooks e eventos](./2026-07-18-webhooks-e-eventos.md)
- Audit: [`docs/status-report-wpp-engine-2026-07-08.md`](../status-report-wpp-engine-2026-07-08.md)
- ADR-006: [`docs/decisions/2026-06-10-adr-006-modo-concierge.md`](../decisions/2026-06-10-adr-006-modo-concierge.md)