# 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.