Documentos-Unicos/projetos/newwhats.clube67.com/integracao-satelites.md

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).

⚠️ Regra de registro bidirecional

• Cada plugin satélite é ÚNICO do projeto onde está instalado — o newwhats do mercado.clube67.com pode divergir do de outro projeto. Não copiar cego.
• Toda mudança no plugin que toque o contrato deve ser registrada no motor e nesta doc; toda mudança no motor que afete o contrato deve ser refletida no doc do plugin (INTEGRACAO-MOTOR.md, dentro de cada plugin).
• O plugin é um braço inteligente do motor: consome, alimenta e configura — não duplica lógica do motor.

Docs relacionadas

• tarefas.md — checklist mestre de pendências.
• wasabi-midias.md — storage, index e delete em lote.
• ativacao-whatsapp.md — trajeto inteligente de ativação.
• INTEGRACAO-MOTOR.md — dentro de cada plugin satélite (lado do satélite).

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 para o motor (genéricos a todos os satélites):
   • ✅ Transcrição (áudio→texto, imagem→descrição) já no motor via Gemini (messages.transcription). O media-transcribe.js do satélite vira redundante.
   • ⏳ memória (a secretária já tem memória por contato no motor; falta o satélite deixar de duplicar). Satélite passa a só enviar contexto.

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.