KLINGO-CLINICAL-SYSLIFE-GCHAT/docs/superpowers/specs/2026-08-11-confirmacao-agenda-syslife-design.md

Design — Confirmação de Agenda via WhatsApp (SysLife)

Data: 2026-08-11 Status: Aprovado pelo usuário, aguardando plano de implementação.

Objetivo

Mesmo padrão já implementado para Klingo e ClinicAll (docs/superpowers/specs/2026-08-11-confirmacao-agenda-klingo-design.md, docs/superpowers/specs/2026-08-11-confirmacao-agenda-clinicall-design.md), agora para o SysLife: permitir que o paciente confirme presença numa consulta agendada via WhatsApp. Os endpoints usados fazem parte do mesmo WebService já usado no MVP de agendamento (Manual WS SysLife V3.4.pdf, salvo em docs/Manual WS SysLife V3.4 (1).pdf, relido nesta sessão), recurso AgendaWSApp — explicitamente descrito no manual como "retorna os registros da agenda para uso do WhatsApp".

Relação com o trabalho anterior

• Reaproveita o MCP Server standalone de Mensageria (Z-PRO) (docs/n8n-agendamento-runbook.md, seção 17) para o disparo do lembrete, mesma decisão do Klingo e do ClinicAll.
• É um MCP novo e separado do MCP de agendamento do SysLife (seção 14.2 do runbook) — endpoints diferentes (AgendaWSApp de confirmação vs. Agenda/Horario/etc. de criação), mesmo espírito de separação já usado nos outros dois providers.
• Reaproveita a credencial Basic Auth já criada no MVP de agendamento do SysLife (SysLife Basic Auth - clínica pendente, u8XXJ6wyrKuGJp4Y) — usuário/senha fixos do WebService (WebSysLife/$Sys10Life), documentados literalmente no manual, não variam por clínica nem por endpoint. Diferente do Klingo (token por clínica) e do ClinicAll (sem auth documentada), aqui a credencial já existe e pode ser usada de verdade.

Escopo: 3 tools do MCP Server "SysLife - Confirmação de Agenda"

O recurso AgendaWSApp do manual é mais rico que o equivalente dos outros dois providers: um único GET já serve três propósitos diferentes, alternados por qual dos três parâmetros é enviado (o manual é explícito: "Deverá ser usado somente um dos 3 parâmetros"):

Tool	Endpoint	Parâmetro usado	Uso
listar_agendamentos_do_dia	GET /AgendaWSApp	QuantidadeDias (1 = amanhã, 2 = depois de amanhã, etc.)	Base do lembrete proativo
buscar_agendamento_por_telefone	GET /AgendaWSApp	NumeroCelular (DDD + número, sem separador)	O agente usa pra achar a consulta pendente do paciente pelo telefone
confirmar_presenca	POST /AgendaWSApp	CodigoAgenda + Resposta ("1" = SIM, "2" = NÃO)	Ação central — o mais simples dos três providers, só dois valores possíveis

Duas tools de leitura (listar_agendamentos_do_dia, buscar_agendamento_por_telefone) apontam pro mesmo endpoint, cada uma com um sub-workflow próprio que monta o parâmetro certo — mesma separação de responsabilidade já usada nos outros MCP Servers deste projeto (uma tool, um propósito claro), mesmo reaproveitando a chamada HTTP de baixo nível.

Fora de escopo, mesmo raciocínio do /entrada do Klingo e do AgendaCentral/relatórios do ClinicAll: AgendaCentral (central telefônica, não WhatsApp), AgendaRetorno (consultas de retorno, não confirmação), AgendaStatus (base para NPS, sem endpoint de submissão documentado no manual) e AgendaConfirmado (só consulta informativa de quem já confirmou, sem ação — não essencial ao fluxo).

Arquitetura

1) MCP Server "SysLife - Confirmação de Agenda" (servidor + 3 sub-workflows)
   [MCP Server Trigger] ──Tools──┬── listar_agendamentos_do_dia      ──▶ GET /AgendaWSApp (QuantidadeDias)
                                  ├── buscar_agendamento_por_telefone ──▶ GET /AgendaWSApp (NumeroCelular)
                                  └── confirmar_presenca              ──▶ POST /AgendaWSApp (CodigoAgenda, Resposta)

2) Workflow proativo "Lembrete de Confirmação - SysLife (exemplo)"
   [Cron 8h diário] → [SysLife: listar_agendamentos_do_dia (QuantidadeDias=1)]
     → [Loop por agendamento] → [Mensageria ZPRO: enviar_texto]

3) Workflow de exemplo "Confirmação de Agenda - GChat - SysLife+Z-PRO (exemplo)"
   [Webhook Z-PRO/GChat] → [AI Agent] → resposta ao paciente
     tools:   MCP SysLife - Confirmação de Agenda (buscar_agendamento_por_telefone, confirmar_presenca)
     memória: Postgres Chat Memory (mesmo padrão dos outros exemplos)

Sem clínica SysLife real disponível: mesma disciplina dos outros dois providers — estrutura completa, validada (n8n_validate_workflow, 0 erros esperados), sem teste de ponta a ponta.

Componentes

MCP Server "SysLife - Confirmação de Agenda"

Mesmo esqueleto de sub-workflow do MVP de agendamento do SysLife: Execute Workflow Trigger → Config SysLife (Set com baseUrl placeholder) → Montar corpo (monta o JSON do body — mesmo em GET, conforme documentado: Seção Body, Type raw, JSON) → HTTP Request (Basic Auth via credencial reaproveitada, neverError: true + fullResponse: true) → Classificar resultado (mesma taxonomia genérica dos outros providers: AUTHENTICATION_ERROR 401/403, NOT_FOUND 404, VALIDATION_ERROR 400/422, SYSLIFE_API_ERROR demais — o manual não documenta código de erro específico).

• listar_agendamentos_do_dia: parâmetro quantidadeDias (obrigatório — 1 para amanhã, conforme o exemplo do manual "1 = Dia atual + 1"). Body: { "QuantidadeDias": <int> }.
• buscar_agendamento_por_telefone: parâmetro numeroCelular (obrigatório, string — DDD + número, ex.: "71999999999", conforme documentado "Código DDD + Número do Celular"). Body: { "NumeroCelular": "<string>" }.
• confirmar_presenca: parâmetros codigoAgenda (obrigatório) e resposta (obrigatório, string "1" ou "2" — documentado na description da tool como "1" = paciente confirmou, "2" = paciente não confirmou/recusou, sem terceiro estado como no Klingo). Body: { "CodigoAgenda": <int>, "Resposta": "<string>" }.

Resposta de AgendaWSApp GET é um array rico (campos coAgenda, dtAtendimento, hrAtendimentoAlterado, nmPaciente, coMedico, nmMedico, nmEspecialidade, nmOrigemDestino, coProcedimento, nmProcedimento, nuTelefone, nuTelefoneDdd, nuCelular, nuCelularDdd, txObservacao, txWhatsappProcedimento, txWhatsappHorario, txWhatsappMedico, txEndereco, txBairro, txComplemento, txCidade, txEstado, nmMsgSms, nmMsgSmsExtra) — já vem pronto com textos formatados pro WhatsApp (txWhatsappProcedimento/txWhatsappHorario/txWhatsappMedico), útil pra montar a mensagem do lembrete sem concatenar campos manualmente.

Workflow proativo "Lembrete de Confirmação - SysLife (exemplo)"

[Cron Trigger, 8h diário] → [SysLife: listar_agendamentos_do_dia]
  (quantidadeDias = 1, ou seja, amanhã)
  → [Loop] → [Mensageria ZPRO: enviar_texto]
     (number = nuCelularDdd + nuCelular do item, body = mensagem usando
      txWhatsappProcedimento/txWhatsappHorario/txWhatsappMedico quando
      presentes, senão monta com nmProcedimento/dtAtendimento/nmMedico)

Diferente do ClinicAll, o telefone aqui é campo direto do item (nuCelular/nuCelularDdd), sem objeto Paciente aninhado — mais parecido com o Klingo nesse aspecto. Fica inativo de propósito.

Workflow de exemplo "Confirmação de Agenda - GChat - SysLife+Z-PRO (exemplo)"

Réplica estrutural do padrão já usado no Klingo e no ClinicAll (webhook → AI Agent → memória Postgres), sem cliente real associado.

• Webhook: mesmo contrato Z-PRO/GChat já documentado (seção 6 do runbook).
• AI Agent: systemMessage fixo instruindo o agente a: entender se a mensagem é confirmação/recusa; se for, pedir o telefone do paciente (ou usar o telefone já vindo do próprio contato do WhatsApp, quando disponível) e usar buscar_agendamento_por_telefone para achar o coAgenda pendente; chamar confirmar_presenca com resposta: "1" (confirmou) ou "2" (recusou); responder confirmando o registro. Mais simples que o ClinicAll — não precisa de tool de tabela de domínio, os dois valores já são documentados diretamente.
• Tools: MCP SysLife - Confirmação de Agenda — buscar_agendamento_por_telefone e confirmar_presenca conectadas (listar_agendamentos_do_dia só serve ao workflow proativo).
• Memória: Postgres Chat Memory, mesmo padrão da seção 16/18/19 do runbook, credencial placeholder.

Fica inativo de propósito.

Fora de escopo (adiado)

• AgendaCentral, AgendaRetorno, AgendaStatus, AgendaConfirmado — ver seção "Escopo" acima.
• Configuração via Google Docs no workflow de exemplo — sem gestor real associado.
• Teste de ponta a ponta contra a API real do SysLife — sem clínica real disponível (mesma pendência do MVP de agendamento).

Testes

Sem clínica SysLife real disponível: validação estrutural apenas (n8n_validate_workflow, 0 erros esperados em todos os workflows). Teste real de ponta a ponta fica pendente para quando houver uma clínica SysLife real — a credencial Basic Auth já existe (reaproveitada do MVP de agendamento), então só falta o baseUrl real da clínica.