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, auditdocs/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:
- Risco de ban / restrição do número pela Meta — inerente ao modelo.
- 1 sessão ≈ 1 número ≈ processo vivo — sessão cai → precisa QR de novo (
session.disconnected). - Não use para spam, cold blast massivo ou listas compradas.
- Boas práticas sugeridas:
- Chip / número dedicado ao produto.
- Warm-up gradual de volume.
- Conteúdo conversacional (respostas a opt-in).
- Monitorar
session.disconnectedemessage.failed. - Separar números de marketing vs. atendimento se o volume crescer.
- 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:
- Adapter HTTP →
https://wpp-api.oneclient.tech/v1/*com Bearer por clínica/tenant. - Persistir
tenant_id,session_ide a API key cifrada. - Receptor de webhook com HMAC + dedupe por
event.id. - Para Whisper: use
data.media_iddomessage.received→GET /v1/media/{id}. - Rate limit já existe no engine (ainda assim, fila no produto é boa prática).
- Onboarding de nova clínica:
/signup→ aprovação no admin → credenciais; rotação de key: suporte OneClient. - Watchdog:
GET /v1/tenants/meperiódico;PATCHsó sewebhook_urldivergir (e sem enviarwebhook_secret). - Sessão caiu: preferir
POST .../reconnectantes de alertar humano; se voltarqr, aí sim peça novo scan. - Carrossel/imagem por URL:
POST /v1/media/upload-url→ use omedia_idno 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- 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/failedrefletidas 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 degroup_messagesalinhada 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