Files

T

VPS 4 Builder 36650397c9 docs(newwhats): contrato de integração Motor ↔ Satélite (auditoria + plano)

Documenta o contrato bidirecional (ext-api A: satélite→motor; webhook + /nw/* B:
motor→satélite), config, recursos do satélite (transcrição/sync-knowledge) e o
estado faseado da sincronização (contrato + alias numbers feitos; config,
sync-knowledge e2e e mover-recursos pendentes).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-28 08:28:22 +02:00

2.9 KiB

Raw Blame History

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)

✅ Contrato documentado (este arquivo).
✅ Compatibilidade de API: alias GET /secretaria/numbers no ext-api do motor (retrocompatível) — fecha o gap do webhook-receiver. (commit motor)
⏳ 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.)
⏳ Conhecimento: rodar sync-knowledge end-to-end (satélite → motor).
⏳ 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.

2.9 KiB Raw Blame History