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

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

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

Objetivo

Permitir que o paciente confirme presença numa consulta agendada via WhatsApp, usando a Klingo Telefonia API (https://api-externa.klingo.app/api/telefonia, auth X-APP-TOKEN) — uma API separada da API de agendamento do Klingo já integrada anteriormente. Dois fluxos compõem a feature: um lembrete proativo (cron diário avisando o paciente da consulta do dia seguinte) e uma confirmação reativa (o paciente responde "sim"/"não" no WhatsApp, e o sistema registra isso no Klingo).

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 — este design não cria nenhuma lógica nova de envio de mensagem, só consome a tool enviar_texto já validada.
• É um MCP novo e separado do MCP de agendamento do Klingo (docs/n8n-agendamento-runbook.md, seção 14.1) — API diferente (Telefonia vs. Agendamento), auth diferente (X-APP-TOKEN vs. o que for usado no de agendamento), propósito diferente. Mesma disciplina de não misturar integrações já estabelecida no projeto.
• Escopo excludente confirmado pelo usuário: o endpoint POST /entrada da API de Telefonia (registro de chamada telefônica) fica fora desta feature — "não envolve telefonia, apenas a confirmação no nosso sistema de WhatsApp".

Escopo: 6 tools do MCP Server "Klingo Telefonia"

Tool	Endpoint	Uso
listar_agendamentos_do_dia	GET /lista/{data}	Base do lembrete proativo — todas as consultas de uma data
consultar_agendamento_por_id	GET /{id}	Detalhe de uma consulta específica
buscar_agendamento_pendente_por_cpf	GET /lista_ultimo_por_cpf	O agente usa isso pra achar qual consulta o paciente está confirmando, a partir do CPF/telefone dele
confirmar_presenca	POST /confirmar	Ação central — registra a confirmação/recusa de presença no Klingo
registrar_nps	POST /nps	Pesquisa de satisfação pós-consulta — fora do fluxo de confirmação em si, mas dentro do escopo "tudo" aprovado pelo usuário
consultar_bloqueios	GET /bloqueios	Consulta de bloqueios de agenda — informativo

POST /entrada excluído (ver seção anterior).

Arquitetura

Três peças distintas, cada uma um conjunto de workflows n8n:

1) MCP Server "Klingo Telefonia" (servidor + 6 sub-workflows)
   [MCP Server Trigger] ──Tools──┬── listar_agendamentos_do_dia          ──▶ GET /lista/{data}
                                  ├── consultar_agendamento_por_id        ──▶ GET /{id}
                                  ├── buscar_agendamento_pendente_por_cpf ──▶ GET /lista_ultimo_por_cpf
                                  ├── confirmar_presenca                  ──▶ POST /confirmar
                                  ├── registrar_nps                       ──▶ POST /nps
                                  └── consultar_bloqueios                 ──▶ GET /bloqueios

2) Workflow proativo "Lembrete de Confirmação — Klingo (exemplo)"
   [Cron 8h diário] → [Klingo Telefonia: listar_agendamentos_do_dia (amanhã)]
     → [Loop por agendamento] → [Mensageria ZPRO: enviar_texto]

3) Workflow de exemplo "Confirmação de Agenda — GChat - Klingo+Z-PRO (exemplo)"
   [Webhook Z-PRO/GChat] → [AI Agent] → resposta ao paciente
     tools:   MCP Klingo Telefonia (buscar_agendamento_pendente_por_cpf, confirmar_presenca)
     memória: Postgres Chat Memory (mesmo padrão da clínica exemplo)

Nenhuma das três peças depende de cliente real Klingo em produção para existir estruturalmente — mesma disciplina já usada pra Klingo/SysLife/ ClinicAll no agendamento: construir e validar a estrutura (n8n_validate_workflow, 0 erros), sem teste de ponta a ponta contra a API real (sem credencial de teste disponível no momento).

Componentes

MCP Server "Klingo Telefonia"

Mesmo esqueleto de sub-workflow usado em todos os outros MCP Servers deste projeto: Execute Workflow Trigger → Config Klingo Telefonia (Set com baseUrl e placeholder de auth) → montagem de query/params/body → HTTP Request (header X-APP-TOKEN, neverError: true + fullResponse: true) → classificação de resultado (taxonomia genérica já usada nos outros providers: AUTHENTICATION_ERROR 401/403, NOT_FOUND 404, VALIDATION_ERROR 400/422, KLINGO_TELEFONIA_API_ERROR demais).

• listar_agendamentos_do_dia: parâmetro data (formato a confirmar contra a spec do SwaggerHub — assumido YYYY-MM-DD até verificação). Devolve lista de agendamentos do dia.
• consultar_agendamento_por_id: parâmetro id.
• buscar_agendamento_pendente_por_cpf: parâmetro cpf.
• confirmar_presenca: parâmetros id (ou idAgenda, a confirmar contra a spec) e resposta/confirmado (a confirmar o formato exato esperado pela API — booleano vs. enum — contra o SwaggerHub na hora da implementação).
• registrar_nps: parâmetros id e nota/comentário (formato a confirmar contra a spec).
• consultar_bloqueios: sem parâmetros obrigatórios óbvios — a confirmar contra a spec (pode aceitar filtro de data/profissional).

Pendência explícita: os nomes exatos de campo de cada endpoint (além do que já foi inspecionado) serão confirmados durante a implementação, consultando o spec OpenAPI do SwaggerHub (api.swaggerhub.com/apis/agsx30/klingo-api-telefonia/1.0.0 — técnica de acesso direto ao spec raw já validada nesta sessão). Nenhum campo será inventado; se o spec não documentar algo necessário, fica registrado como pendência, não como suposição.

Autenticação: assim como o MCP de Mensageria, nenhuma credencial é inventada — a criação da credencial httpHeaderAuth com o X-APP-TOKEN real fica pré-requisito manual do usuário, feito quando houver uma clínica Klingo real pra testar.

Workflow proativo "Lembrete de Confirmação — Klingo (exemplo)"

[Cron Trigger, 8h diário] → [Klingo Telefonia: listar_agendamentos_do_dia]
  (data = amanhã, calculada via expressão)
  → [Split in Batches / loop] → [Mensageria ZPRO: enviar_texto]
     (number = telefone do paciente, body = mensagem de lembrete com
      nome do paciente + data/hora da consulta)

Chama diretamente as tools dos dois MCP Servers via Execute Workflow (não via AI Agent — fluxo determinístico, sem necessidade de interpretação de linguagem natural). Sem lógica de "já lembrado antes" nesta rodada — se rodar mais de uma vez no mesmo dia por engano, manda lembrete duplicado; ajuste futuro se isso for um problema real. Texto do lembrete fixo nesta rodada (sem config via Google Docs — é workflow de exemplo, sem cliente/gestor real associado ainda).

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

Réplica estrutural do padrão já usado na clínica exemplo (webhook → AI Agent → memória Postgres), mas sem cliente real associado — workflow de referência/esqueleto, mesmo espírito dos MCP Servers de agendamento Klingo/SysLife/ClinicAll já construídos sem clínica real.

• Webhook: mesmo contrato do Z-PRO/GChat já documentado (seção 6 do runbook).
• AI Agent: systemMessage fixo (sem Google Docs nesta rodada) instruindo o agente a: entender se a mensagem do paciente é uma resposta de confirmação/recusa de presença; se for, usar buscar_agendamento_pendente_por_cpf pra achar a consulta pendente (a partir do telefone/CPF do contato do webhook) e então chamar confirmar_presenca; responder ao paciente confirmando o registro.
• Tools: MCP Klingo Telefonia — só buscar_agendamento_pendente_por_cpf e confirmar_presenca conectados nesta rodada (as outras 4 tools do MCP existem mas não são atribuídas a este agente específico — podem ser usadas por outros workflows futuros).
• Memória: Postgres Chat Memory, mesmo padrão da seção 16 do runbook — credencial própria a ser criada quando houver cliente real.

Fora de escopo (adiado)

• POST /entrada (telefonia em si) — explicitamente fora, por instrução do usuário.
• Lógica de "não lembrar de novo se já confirmado" no workflow proativo — YAGNI até aparecer o caso real.
• Configuração via Google Docs no workflow de exemplo — sem gestor/ cliente real associado ainda; replicar quando houver.
• Teste de ponta a ponta contra a API real do Klingo Telefonia — sem credencial de teste disponível.
• Qualquer UI/relatório de acompanhamento de confirmações — não solicitado.

Testes

Sem cliente/credencial real Klingo Telefonia disponível: validação estrutural apenas (n8n_validate_workflow, 0 erros esperados em todos os workflows) — mesma disciplina já usada para Klingo/SysLife/ClinicAll no agendamento. Teste real de ponta a ponta (lembrete disparando, paciente respondendo, /confirmar sendo chamado corretamente) fica pendente para quando houver uma clínica Klingo real em produção, com credencial de teste da API de Telefonia.