# Plugin Empresa — Arquitetura de Integração ## Visão Geral O sistema NewWhats roda em servidor próprio e nunca acessa diretamente o banco da empresa cliente. A comunicação acontece por dois plugins que se reconhecem via chave compartilhada: ``` [ Servidor NewWhats ] [ Servidor da Empresa ] Plugin: secretaria ←→ Plugin: newwhats-client - Secretária IA - CRUD nos bancos - WhatsApp / Baileys - Agente de consulta - Inbox / Sessions - Frontend embarcado ``` --- ## Plugin da Empresa (`newwhats-client`) ### Responsabilidades - Conecta ao banco de dados interno da empresa (leitura e escrita) - Expõe endpoints controlados para o NewWhats consumir - Recebe webhooks do NewWhats (eventos, notificações) - Serve o frontend embarcado (inbox, sessions, secretária) - Gerencia a chave de integração e autenticação cruzada ### Instalação O plugin é distribuído como pacote independente. A empresa instala no próprio servidor — Node.js, PHP, Python ou via Docker. Após instalação, gera-se uma `integration_key` que é inserida nos dois lados. ``` 1. Empresa instala o plugin 2. Plugin gera integration_key + registra URL do servidor NewWhats 3. Admin copia a key e cola nas configurações do NewWhats 4. Os dois sistemas se reconhecem e começam a conversar ``` --- ## Comunicação entre os Plugins ### Direções | Direção | Quando | Exemplo | |---|---|---| | NewWhats → Empresa (pull) | Secretária precisa de dados em tempo real | Consultar agenda do Dr. | | Empresa → NewWhats (push) | Evento proativo no sistema da empresa | Dr. cancelou consulta, avisar paciente | ### Autenticação - Chave JWT gerada no NewWhats, compartilhada com o plugin da empresa - Rotacionável pelo admin a qualquer momento - Cada requisição carrega o JWT no header `Authorization: Bearer ` - Expiração configurável (padrão: 90 dias) --- ## Contrato de API (Endpoints Mínimos) O plugin da empresa **obrigatoriamente** expõe estes endpoints para a secretária funcionar: ### Agenda ``` GET /nw/agenda?data=YYYY-MM-DD&profissional_id= → horários disponíveis POST /nw/agenda/agendar → confirmar agendamento PUT /nw/agenda/:id/cancelar → cancelar agendamento GET /nw/agenda/:id → detalhes de um agendamento ``` ### Profissionais / Responsáveis ``` GET /nw/profissionais → lista com nome, área, número WhatsApp GET /nw/profissionais/:id → dados de um profissional ``` ### Clientes / Pacientes / Contatos ``` GET /nw/cliente?telefone=5511999999999 → dados pelo número de WhatsApp GET /nw/cliente/:id → dados por ID POST /nw/cliente → cadastrar novo cliente ``` ### Webhook ``` POST /nw/webhook/registrar → registrar URL de callback no NewWhats ``` ### Endpoints opcionais (dependem do ramo) ``` GET /nw/produtos → catálogo GET /nw/pedidos?cliente_id= → histórico de pedidos GET /nw/financeiro?cliente_id= → situação financeira GET /nw/historico?cliente_id= → histórico de atendimentos ``` --- ## Agente de Consulta (dentro do plugin da empresa) O plugin não expõe o banco diretamente — ele tem um **agente interno** que: 1. Recebe a query da secretária (ex: `agenda?data=2026-04-15&profissional=Dr. Carlos`) 2. Traduz para uma query SQL ou chamada interna do sistema da empresa 3. Filtra apenas os campos permitidos (sem dados sensíveis) 4. Devolve JSON padronizado ``` Secretária IA (NewWhats) ↓ GET /nw/agenda?data=15/04 Plugin da Empresa ↓ SELECT * FROM agenda WHERE data = '2026-04-15' AND ativo = true Banco da Empresa ↓ rows Plugin filtra e formata ↓ JSON limpo Secretária injeta no contexto e responde o cliente ``` ### Permissões por endpoint Cada endpoint tem uma flag de permissão configurável pelo admin da empresa: ``` agenda.read = true ✓ agenda.write = true ✓ cliente.read = true ✓ cliente.write = false ✗ (somente leitura por enquanto) financeiro.read = false ✗ (dado sensível, bloqueado) ``` --- ## Frontend Embarcado ### O que é As três telas principais do NewWhats servidas **dentro do sistema da empresa**, sem precisar abrir outro sistema ou fazer login separado. ``` Sistema da Empresa (ERP / CRM) └── Menu ├── [módulos da empresa] └── NewWhats ← plugin embarcado ├── Inbox (conversas WhatsApp em tempo real) ├── Sessions (instâncias Baileys, status de conexão) └── Secretária IA (configuração + chat de teste) ``` ### Opções de implementação **Opção 1 — iFrame com token SSO** (mais simples) - Plugin gera um token de sessão temporário (15min, renovável) - Abre `https://newwhats-server/embed?token=` em iFrame - NewWhats valida o token e serve a interface sem tela de login **Opção 2 — Micro-frontend (componentes standalone)** (mais integrado) - Plugin distribui componentes React/Vue que consomem a API do NewWhats - Renderizam dentro do layout da empresa sem iFrame - Requerem que a empresa use React/Vue no frontend **Recomendação:** começar com iFrame SSO — funciona em qualquer stack, entrega valor rápido. Migrar para micro-frontend quando houver demanda. ### Autenticação cruzada (SSO) ``` 1. Usuário logado no sistema da empresa clica em "NewWhats" 2. Sistema da empresa chama POST /nw/auth/sso no NewWhats com a integration_key 3. NewWhats retorna um token de sessão temporário 4. Plugin abre o iFrame com esse token 5. Usuário entra direto, sem segunda tela de login ``` --- ## Números e Papéis O plugin da empresa cadastra os números WhatsApp relevantes e seus papéis: | Papel | Descrição | Exemplo | |---|---|---| | `secretary_virtual` | Número principal da secretária IA | Atende clientes | | `clinic` | Número geral da empresa | Recebe notificações | | `doctor` / `specialist` | Profissional responsável por área | Recebe dúvidas específicas | | `manager` | Fallback universal | Recebe quando ninguém mais responde | | `reserve` | Backup da secretária | Entra quando principal cai ou é banido | | `human_secretary` | Secretária humana | Pode assumir conversa da IA | O NewWhats consulta esses papéis via `GET /nw/profissionais` e usa para roteamento interno. --- ## Fluxo Completo — Exemplo Real **Cenário:** Paciente pergunta se pode agendar com o Dr. Carlos na quinta-feira. ``` 1. Paciente envia mensagem no WhatsApp 2. Baileys recebe → NewWhats aciona Secretária IA 3. Nó de intenção classifica: "agendamento" 4. Nó de calendário chama GET /nw/agenda?data=2026-04-16&profissional=Dr.Carlos 5. Plugin da empresa consulta banco → retorna horários livres 6. Secretária oferece opções ao paciente 7. Paciente confirma horário das 14h 8. Secretária chama POST /nw/agenda/agendar com os dados 9. Plugin grava no banco da empresa 10. Secretária confirma para o paciente via WhatsApp 11. Sistema da empresa exibe o agendamento normalmente no próprio sistema ``` **Tudo isso sem o paciente saber que são dois sistemas.** --- ## Roadmap de Implementação ### Fase 1 — Conexão básica - [ ] Geração e troca de `integration_key` entre os dois plugins - [ ] Endpoints mínimos no plugin da empresa (agenda, profissionais, cliente) - [ ] Nó do tipo `api_query` no cérebro da secretária - [ ] Teste end-to-end: secretária consulta agenda real ### Fase 2 — Agente de consulta - [ ] Agente interno no plugin da empresa com mapeamento de permissões - [ ] Push de eventos (webhook): cancelamentos, atualizações - [ ] Roteamento por papel: secretária sabe para qual número perguntar ### Fase 3 — Frontend embarcado - [ ] SSO por token temporário - [ ] iFrame com Inbox + Sessions + Secretária IA - [ ] Personalização básica (logo, cores da empresa) ### Fase 4 — Expansão - [ ] SDK para empresas implementarem o plugin em qualquer stack - [ ] Marketplace de conectores prontos (ex: conector para sistemas populares do setor) - [ ] Painel de auditoria cruzada (o que a secretária consultou e quando)