diff --git a/docs/n8n-agendamento-runbook.md b/docs/n8n-agendamento-runbook.md index f78ec9c..4682654 100644 --- a/docs/n8n-agendamento-runbook.md +++ b/docs/n8n-agendamento-runbook.md @@ -636,3 +636,89 @@ montar depois, atribuindo estas tools no workflow que ele decidir. **Resultado**: MCP Server de mensageria standalone, validado e testado com envio real, pronto para ser consumido por qualquer workflow futuro (confirmação de agenda ou outro), de qualquer provider. + +## 18. Confirmação de Agenda via WhatsApp (Klingo Telefonia) + +**Data:** 11/08/2026. Ver design completo em +`docs/superpowers/specs/2026-08-11-confirmacao-agenda-klingo-design.md` +e plano em +`docs/superpowers/plans/2026-08-11-confirmacao-agenda-klingo.md`. + +**Motivação**: permitir que o paciente confirme presença numa consulta +agendada via WhatsApp, usando uma API **separada** da de agendamento do +Klingo — a **Klingo Telefonia** +(`https://api-externa.klingo.app/api/telefonia`, auth `X-APP-TOKEN`). +Dois fluxos: um lembrete proativo (cron diário) e uma confirmação +reativa (o paciente responde "sim"/"não" no WhatsApp). `POST /entrada` +(registro de chamada telefônica) ficou fora do escopo por instrução +explícita do usuário — "não envolve telefonia, apenas a confirmação no +nosso sistema de WhatsApp". + +**MCP Server "Klingo Telefonia"** (`tSw2LGlOYVg9antR`) — 6 tools: + +| Tool | Endpoint | Workflow id | +| --- | --- | --- | +| `listar_agendamentos_do_dia` | `GET /lista/{data}` | `hynQtoURFqpDUGTI` | +| `consultar_agendamento_por_id` | `GET /{id}` | `JXEaNHZSmiBWxDej` | +| `buscar_agendamento_pendente_por_cpf` | `GET /lista_ultimo_por_cpf` | `OJYHMUQlYv48Gw7h` | +| `confirmar_presenca` | `POST /confirmar` | `jdFH4T2fyd7YKNOa` | +| `registrar_nps` | `POST /nps` | `khUIxWFx7zF0tygP` | +| `consultar_bloqueios` | `GET /bloqueios` | `TfYHBjRkaL8gDmYR` | + +Campos confirmados direto no spec OpenAPI real +(`api.swaggerhub.com/apis/agsx30/klingo-api-telefonia/1.0.0`) durante a +implementação — nada inventado. Pendências documentadas explicitamente: + +- **Schema de `/lista_ultimo_por_cpf` e `/bloqueios` não documentado** + no spec — as respostas são tratadas como objeto genérico, sem assumir + campos específicos. +- **Obrigatoriedade de `callid` em `/confirmar` é ambígua**: o texto + descritivo do endpoint sugere obrigatoriedade, mas nenhum campo do + schema JSON está marcado `required`. Tratado como opcional — vazio + para confirmações originadas no WhatsApp (sem chamada telefônica + real). +- **Inconsistência de tipo do `id_marcacao`**: aparece como `string` no + schema `marcacao` (retornado por `/lista/{data}` e `/{id}`), mas como + `number` obrigatório no body de `/confirmar` e `/nps`. Os + sub-workflows convertem com `Number(...)` antes de enviar. +- Os endpoints GET desta API aceitam filtros no **corpo da + requisição** (incomum para GET) — implementado no node `HTTP Request` + do n8n com `method: "GET"` + `sendBody: true`. + +**Workflow proativo "Lembrete de Confirmação - Klingo (exemplo)"** +(`IvLzmASwa9LGaMxf`): cron diário às 8h → calcula a data de amanhã → +chama `listar_agendamentos_do_dia` (mesmo sub-workflow usado pela tool +do MCP, via `Execute Workflow` direto — fluxo determinístico, sem IA) +→ loop pelos agendamentos → monta a mensagem de lembrete → chama +`enviar_texto` do **MCP Server - Mensageria ZPRO** (`Y4ndG7GuIUrmVRxV`, +seção 17), reaproveitando o envio já validado. Validado +estruturalmente (0 erros), mas deixado **inativo de propósito** — sem +clínica Klingo real, um cron ativo geraria só chamadas com erro contra +a API e tentativas de envio com dados vazios. + +**Workflow de exemplo "Confirmação de Agenda - GChat - Klingo+Z-PRO +(exemplo)"** (`F5jEliFFE3K9cW14`): réplica estrutural do padrão da +clínica exemplo (webhook → `AI Agent` → memória Postgres), mas **sem +cliente real associado** — mesmo espírito dos MCP Servers de +agendamento Klingo/SysLife/ClinicAll construídos sem clínica real. +Contrato do webhook idêntico ao já documentado na seção 6 (`body.protocol` +→ `sessionId`, `body.entrada` → `mensagem`, `body.contactName` → +`nomeContato`, `body.number` → `telefone`). Modelo de chat usa a +credencial OpenAI real e compartilhada já em uso na clínica exemplo +(`29vMIDah5DTIhUYJ`, "GPT") — não é uma credencial inventada. A memória +Postgres fica com credencial placeholder (sem cliente real, sem banco +provisionado ainda). Tools conectadas via `MCP Client Tool` (nativo), +restritas a `buscar_agendamento_pendente_por_cpf` e +`confirmar_presenca` (as outras 4 tools do MCP existem mas não foram +atribuídas a este agente de exemplo). `systemMessage` fixo instruindo o +agente a interpretar confirmação/recusa, buscar o `id_marcacao` +pendente pelo CPF do paciente, e então confirmar (`status: "C"`) ou +recusar (`status: "N"`). Validado estruturalmente (0 erros), deixado +**inativo de propósito** pela mesma razão do workflow de lembrete. + +**Resultado**: MCP Server de confirmação de agenda (Klingo Telefonia) +completo e validado estruturalmente, junto com os dois workflows de +exemplo (lembrete proativo + AI Agent reativo) prontos pra ativar assim +que houver uma clínica Klingo real com credencial `X-APP-TOKEN` e banco +Postgres provisionado. Sem teste de ponta a ponta contra a API real — +pendência explícita até então.