🏢 Integração de Empresa e Plugins Clientes

A arquitetura do NewWhats permite funcionar como um Motor SaaS Multi-tenant centralizado de mensagens e assistentes de Inteligência Artificial, servindo múltiplos satélites de forma isolada e segura.

1. Visão Geral do Ecossistema

O NewWhats (servidor motor) centraliza as conexões com o WhatsApp (Baileys), logs, controle de mensagens, armazenamento remoto e o motor de Inteligência Artificial (Secretária IA).

Os sistemas satélites integrados (como o Alemão Conveniências ou outros ERPs/CRMs) comunicam-se de forma leve com o motor central usando o plugin newwhats-client, sem necessidade de rodar bibliotecas WhatsApp locais.

[ Servidor NewWhats ]          [ Servidor da Empresa / Satélite ]
  Plugin: secretaria      ←→    Plugin: newwhats-client
  - Secretária IA               - CRUD de Dados Internos (Agenda)
  - WhatsApp / Baileys           - Agente de consulta local
  - Inbox / Sessions             - Frontend embarcado via iframe

2. Autenticação e Chaves de Integração

A autenticação é realizada utilizando a chave compartilhada integration_key (JWT).
O cabeçalho de requisição é preenchido no formato Authorization: Bearer <integration_key>.
O isolamento multi-tenant garante que cada integration_key resolva apenas para o user_id e instâncias do WhatsApp (allowed_sessions[]) pertencentes àquele tenant de forma restrita.

3. Endpoints de Integração (`/api/ext/v1/*`)

O motor expõe uma API robusta para os satélites consumirem e sincronizarem conversas:

GET /sessions: Lista todas as conexões WhatsApp do tenant.
POST /sessions: Cria e inicia nova sessão.
DELETE /sessions/:id: Desconecta e apaga sessão.
GET /inbox?session=ID: Retorna os chats da sessão com snapshot da última mensagem.
GET /inbox/:chatId/messages: Recupera o histórico paginado de mensagens.
POST /inbox/:chatId/send: Envia mensagens simples ou ricas (botões/listas).
POST /secretaria/ask: Envia uma mensagem à Secretária IA para processamento contextual de conversação e controle de modo Handoff (IA vs Atendimento Humano).

4. Integração de Dados do Cliente (CRM/ERP)

A Secretária IA precisa interagir com dados em tempo real da empresa (como agendar horários, buscar cadastro de clientes ou produtos). Para isso, o plugin local da empresa (newwhats-client) expõe uma API interna para o motor central consultar:

GET /nw/agenda?data=YYYY-MM-DD: Consulta horários livres.
POST /nw/agenda/agendar: Grava novo agendamento no banco local da empresa.
GET /nw/cliente?telefone=...: Recupera ficha cadastral do cliente pelo número de WhatsApp.
POST /nw/cliente: Registra novo lead/contato no banco local.

Esta comunicação garante que dados confidenciais e críticos permaneçam seguros dentro do servidor da empresa e apenas informações autorizadas sejam repassadas em tempo real à Inteligência Artificial!

🏢 Integração de Empresa e Plugins Clientes

1. Visão Geral do Ecossistema

2. Autenticação e Chaves de Integração

3. Endpoints de Integração (/api/ext/v1/*)

4. Integração de Dados do Cliente (CRM/ERP)

3. Endpoints de Integração (`/api/ext/v1/*`)