# newwhats.clube67.com — Contrato de integração Motor ↔ Satélite

> O **motor** (newwhats) expõe a plataforma WhatsApp + Secretária IA; cada
> **satélite** (ex.: mercado.clube67.com / "Alemão Conveniências", plugin
> `newwhats` v2.1.0) consome o motor e fornece dados do seu negócio.
> Fonte da verdade do contrato (auditado em 28/jun/2026).

## Config do satélite (plugin_configs, manifest `newwhats`)
`newwhats_url` (URL do motor) · `integration_key` (x-nw-key, rotas `/nw/*`) ·
`api_token` (Bearer, envio de mensagens) · `webhook_secret` (HMAC do webhook).

## Contrato A — Satélite → Motor (ext-api `/api/ext/v1/*`)
| Satélite chama | Motor (ext-api) | Status |
|---|---|---|
| `inbox`, `inbox/:chatId/messages`, `inbox/:chatId/send` | idem | ✅ |
| `media/:messageId` | `media/:messageId` | ✅ |
| `stream` (WS) | `stream` | ✅ |
| `secretaria/ask` | `secretaria/ask` (routes.ts) | ✅ |
| `secretaria/numbers` | **alias adicionado** → `sec_numbers` | ✅ (corrigido) |
| `secretaria/*` interno (`sync-knowledge`) | `/api/secretaria/*` (plugin) | ✅ |

> Demais dados da Secretária no ext-api ficam sob `/sec/*` (`sec/agent`,
> `sec/nodes`, `sec/slots`, `sec/conversations`, `sec/keys`, `sec/handoff`).

## Contrato B — Motor → Satélite
| Mecanismo | Satélite | Auth |
|---|---|---|
| Webhook `POST /api/webhook/newwhats` (`message.new`, `session.status`) | `webhook-receiver.js` | HMAC `webhook_secret` |
| Secretária consulta `/nw/*` (`/cliente`, `/clube`, `/parceiros`, `/promocoes`, `/sorteio`, `/vagas`, `/ping`) | `routes.js` | `integration_key` (timingSafeEqual) |

## O que o satélite já faz (e poderia migrar ao motor)
- `media-transcribe.js`: transcrição de áudio + descrição de imagem via Gemini
  (cache Redis, fallback Whisper). **Hoje só no satélite** → candidato a ir ao motor.
- `sync-knowledge.js`: monta o nó de conhecimento com dados reais e envia ao motor.
- `smart-router.js` (roteamento sem LLM), `personas.js`, `follow-up-detector.js`,
  `context-builder.js` (contexto local do negócio).

## Estado da sincronização (faseado)
1. ✅ **Contrato documentado** (este arquivo).
2. ✅ **Compatibilidade de API**: alias `GET /secretaria/numbers` no ext-api do
   motor (retrocompatível) — fecha o gap do `webhook-receiver`. (commit motor)
3. ⏳ **Config/conexão**: validar `newwhats_url`/keys do satélite apontando para o
   motor correto (dev/prod) e o HMAC do webhook. *(requer credenciais reais.)*
4. ⏳ **Conhecimento**: rodar `sync-knowledge` end-to-end (satélite → motor).
5. ⏳ **Mover recursos**: transcrição/memória para o motor (genéricos a todos os
   satélites); satélite passa a só enviar contexto. Ver `secretaria-ia-evolucao.md`.

## Inconsistência anotada
A transcrição no satélite usa `process.env.GEMINI_API_KEY`; o RAG/memória do motor
usa `cfg.gemini_key` (config do plugin). Unificar a fonte da chave ao migrar.