KLINGO-CLINICAL-SYSLIFE-GCHAT/docs/superpowers/specs/2026-08-11-mcp-server-mensageria-zpro-design.md

# Design — MCP Server nativo no n8n para Mensageria (Z-PRO)

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

## Objetivo

Um MCP Server nativo do n8n, **standalone**, dedicado só a **enviar**
mensagens de WhatsApp — desacoplado de qualquer provider de agendamento
(Z-PRO, Klingo, SysLife, ClinicAll). O caso de uso original que motivou
isso foi a confirmação de agenda (lembrete proativo perguntando se o
paciente confirma a consulta), mas o MCP em si não sabe nada sobre
agendamento — é só "enviar mensagem". Qualquer workflow futuro (agente
conversacional, fluxo de confirmação, campanha, etc.) pode chamar essas
tools, atribuídas manualmente pelo usuário conforme a necessidade.

## Relação com o trabalho anterior

Reaproveita a mesma API do Z-PRO já integrada pro agendamento
(`apigchat.gtigrupo.com.br/v2/api/external/{ApiID}/...`), mas é um
**endpoint diferente** (envio de mensagem, não agenda) — provavelmente
uma integração/ApiID diferente da usada pro agendamento, dado o padrão já
visto nesta sessão de que cada integração cadastrada no Z-PRO tem seu
próprio `ApiID` + Bearer token, não intercambiáveis (ver
`docs/n8n-agendamento-runbook.md`, seção 13, gotcha 3).

O motivo de ser um MCP separado, não parte do `MCP Server - ZPRO`
(agendamento): a expectativa do usuário é que diferentes clientes usem
diferentes backends de envio (WABA oficial, não oficial, híbrido) — se
essas tools morassem dentro do MCP de agendamento de um provider
específico, um cliente que trocasse de sistema de agendamento perderia
a reutilização das tools de envio. Mantendo separado, qualquer workflow
(de qualquer provider) pode apontar pra esse MCP de mensageria.

## Escopo: 4 tools desta rodada (de 10 endpoints documentados)

| Tool | Endpoint | Uso |
| --- | --- | --- |
| `enviar_texto` | `POST /v2/api/external/{ApiID}/` (JSON) | Texto simples — canal não oficial ou dentro da janela de 24h do WABA oficial |
| `enviar_template` | `POST /v2/api/external/{ApiID}/template` | Template WABA aprovado, sem parâmetros dinâmicos |
| `enviar_template_com_parametros` | `POST /v2/api/external/{ApiID}/templateBody` | Template WABA aprovado, com parâmetros dinâmicos no corpo |
| `enviar_template_marketing` | `POST /v2/api/external/{ApiID}/templateMarketingBody` | Template WABA de marketing, com componentes de header (ex.: imagem) + body |

**Fora de escopo desta rodada** (documentados no manual/mensagem do
usuário, sem caso de uso imediato): envio de mídia via multipart
form-data, envio de mídia/áudio via URL pública, envio via Base64,
envio via query params GET, busca de mensagem por `wamid`
(`getMessageByMessageId`).

## Autenticação — pendência real a confirmar

As credenciais Z-PRO já criadas nesta sessão são específicas de
integrações de **agendamento** (`e372d4f0-...`/`ab2d51db-...` como
ApiID). O envio de mensagem pode usar uma integração diferente
(`ApiID` + Bearer token próprios) — possivelmente a credencial `ZPRO API
Token - Canal QR - MC AGENDAMENTO` (criada quando o usuário mencionou
"não é a versão que tem template da Meta, permite texto simples", que
bate conceitualmente com o canal não oficial de texto simples), mas
isso **não foi confirmado**, só é uma hipótese razoável dado o nome. Fica
como pré-requisito de confirmação/teste antes de considerar a
integração validada — mesmo espírito da lição já registrada no runbook
(nunca assumir que ApiID e token de integrações diferentes são
intercambiáveis).

## Arquitetura

```
[MCP Server Trigger] ──Tools──┬── enviar_texto                    ──▶ POST /v2/api/external/{ApiID}/
  ("MCP Server -              ├── enviar_template                 ──▶ POST /v2/api/external/{ApiID}/template
   Mensageria ZPRO")          ├── enviar_template_com_parametros  ──▶ POST /v2/api/external/{ApiID}/templateBody
                               └── enviar_template_marketing       ──▶ POST /v2/api/external/{ApiID}/templateMarketingBody
```

5 workflows no total (servidor + 4 sub-workflows), mesmo padrão
arquitetural dos outros MCP Servers deste projeto. Sem workflow de
agente cliente — este MCP é consumido por outros workflows (a serem
atribuídos manualmente pelo usuário depois), não tem conversa própria.

## Componentes

### Sub-workflow `enviar_texto`

```
[Execute Workflow Trigger] → [Config Mensageria] → [Montar corpo] → [POST /] → [Classificar resultado]
```

- **Execute Workflow Trigger**: `number` (obrigatório, formato
  `5511999999999`), `body` (obrigatório, texto da mensagem),
  `externalKey` (obrigatório, chave única de controle — ex.:
  `agenda-<idAgenda>` pra rastrear de qual contexto veio o envio),
  `isClosed` (opcional, boolean, fecha o ticket após envio).
- **Config Mensageria** (`Set`): `baseUrl`/`apiId` desta integração
  (placeholder até confirmar a pendência de autenticação acima).
- **Montar corpo**: `{ body, number, externalKey, isClosed }`, só com
  os campos documentados.
- **POST `/v2/api/external/{apiId}/`**: Bearer token (credencial
  `httpHeaderAuth`), `neverError: true` + `fullResponse: true`.
- **Classificar resultado**: 2xx → sucesso (devolve o corpo cru — sem
  exemplo de resposta real capturado ainda pra validar um envelope
  específico); fora de 2xx → taxonomia genérica já usada nos outros
  providers (`AUTHENTICATION_ERROR` 401/403, `NOT_FOUND` 404,
  `VALIDATION_ERROR` 400/422, `ZPRO_MENSAGERIA_API_ERROR` demais).

### Sub-workflows `enviar_template` / `enviar_template_com_parametros` / `enviar_template_marketing`

Mesmo esqueleto do `enviar_texto`, mudando o endpoint e o corpo da
requisição:

- `enviar_template`: `number`, `isClosed`, `templateName`,
  `templateLanguageCode` (ex.: `pt_BR`) → monta
  `{ number, isClosed, templateData: { messaging_product: "whatsapp", to: number, type: "template", template: { name: templateName, language: { code: templateLanguageCode } } } }`.
- `enviar_template_com_parametros`: os mesmos campos acima + `parametrosBody`
  (lista de strings, cada uma vira `{ type: "text", text: valor }` dentro
  de `components[0].parameters`).
- `enviar_template_marketing`: os mesmos campos de
  `enviar_template_com_parametros` + `headerImageUrl` (opcional, monta o
  componente `header` com `{ type: "image", image: { link: headerImageUrl } }`
  quando presente).

Nenhum dos três inventa campo fora do que foi documentado pelo usuário
— parâmetros de template genéricos o suficiente pra cobrir os exemplos
reais mostrados (`hello_world`, template com 1 parâmetro de texto,
template de marketing com header de imagem), sem assumir uma estrutura
mais complexa (múltiplos parâmetros, múltiplos componentes) que não foi
documentada.

## Fora de escopo (adiado)

- Os 6 endpoints de envio de mídia/áudio/base64/busca listados acima
  (seção Escopo).
- Qualquer lógica de "qual canal usar por cliente" (WABA oficial vs.
  não oficial vs. híbrido) — decisão de negócio de quem for atribuir a
  tool no workflow consumidor, não deste MCP.
- A feature de confirmação de agenda em si (Klingo) — motivou a criação
  deste MCP, mas fica como trabalho separado, a ser desenhado depois,
  que vai **consumir** este MCP quando estiver pronto.

## Testes

Diferente dos outros MCP Servers (que não têm clínica real
disponível), este reaproveita a **clínica exemplo do Z-PRO, já em
produção real** — então existe a tentação de testar direto contra ela.
**Cuidado real**: enviar uma mensagem de teste manda uma mensagem de
WhatsApp de verdade pro número de destino — ao contrário de criar um
agendamento fictício (que pode ser apagado depois de conferido), uma
mensagem enviada não pode ser "desenviada". Testar só com um número de
celular de teste controlado pela equipe (nunca um número de paciente
real), e confirmar visualmente no celular de teste antes de considerar
validado. Validação estrutural (`n8n_validate_workflow`) segue a
disciplina normal; a validação de autenticação (pendência acima) precisa
ser resolvida antes de qualquer teste real de envio.