mercado.clube67.com/backend/plugins/newwhats/INTEGRACAO-MOTOR.md

Plugin newwhats (mercado.clube67.com) ↔ Motor NewWhats

Este plugin é ÚNICO deste projeto (mercado.clube67.com / "Alemão Conveniências"). Outro projeto tem o seu próprio newwhats, possivelmente divergente. Não copie cego entre projetos. v2.1.0 — rev. 28/jun/2026.

⚠️ Regra de registro bidirecional (obrigatória)

• Toda mudança neste plugin que toque o contrato (rotas, payloads, auth, webhook, dados enviados) deve ser registrada no motor e na doc central documentos-unicos/projetos/newwhats.clube67.com/integracao-satelites.md.
• Toda mudança no motor que afete o contrato deve ser refletida aqui (este arquivo) e validada contra este plugin.
• O plugin é um braço inteligente do motor: consome, alimenta e configura o motor — não duplica lógica que pertence ao motor.

Configuração (plugin_configs, manifest newwhats)

Chave	Uso
newwhats_url	URL do motor (ex.: http://newwhats.local:8008)
integration_key	x-nw-key — rotas /nw/* e proxy REST/WS (timingSafeEqual)
api_token	Bearer — envio de mensagens ao motor
webhook_secret	HMAC x-nw-signature — valida webhooks recebidos do motor

Arquivos deste plugin e o que falam com o motor

Arquivo	Papel	Lado do motor
index.js	registro/boot do plugin	—
auth.js	valida integration_key / token	pair/api-keys
proxy.js	proxy REST + WS autenticado p/ inbox	ext-api /api/ext/v1/*, stream
routes.js	expõe /nw/* (cliente, clube, parceiros, promoções, sorteio, vagas, ping)	Secretária consulta via integration_key
webhook-receiver.js	recebe message.new / session.status (HMAC)	motor → satélite
sync-knowledge.js	monta e envia nó de conhecimento (RAG)	/api/secretaria/* (sync-knowledge)
context-builder.js	contexto local do negócio p/ Secretária	alimenta secretaria/ask
smart-router.js	roteamento sem LLM	local
personas.js	personas do atendimento	local
follow-up-detector.js	detecção de follow-up	local
media-transcribe.js	REDUNDANTE — transcrição já existe no motor (messages.transcription)	⏳ remover (Fase 5)

Contrato resumido (detalhes na doc central)

• Satélite → Motor (ext-api): inbox, inbox/:chatId/messages, inbox/:chatId/send, media/:messageId, stream (WS), secretaria/ask, secretaria/numbers (alias), secretaria/* interno (sync-knowledge).
• Motor → Satélite: webhook POST /api/webhook/newwhats (HMAC) e a Secretária consultando /nw/* (integration_key).

Pendências que tocam este plugin

• Fase 3 — validar newwhats_url/keys (dev/prod) + HMAC do webhook.
• Fase 4 — sync-knowledge end-to-end.
• Fase 5 — consumir messages.transcription do motor e remover media-transcribe.js; unificar fonte da chave Gemini.
• Ativação inteligente — este plugin deve orquestrar o trajeto de provisionamento (ver ativacao-whatsapp.md na doc central).

Fonte da verdade do contrato e checklist: documentos-unicos/projetos/newwhats.clube67.com/ → integracao-satelites.md, tarefas.md, wasabi-midias.md, ativacao-whatsapp.md.