INDENTIFICAR-TEXTO-EM-IMAGEM/docs/superpowers/specs/2026-08-20-orcamento-exames-imagem-design.md

# Orçamento automático de exames a partir de foto (GChat/Z-PRO + n8n + IA)

- **Data:** 2026-08-20
- **Status:** Aprovado para implementação
- **Instância n8n alvo:** `https://devn8n.gtigrupo.com.br`

## Objetivo

Quando um cliente manda, pelo WhatsApp (canal Z-PRO/GChat), uma foto de um pedido
médico de exames, o sistema deve:

1. Identificar os exames escritos/impressos na imagem.
2. Cruzar esses exames com uma tabela de preços mantida no prompt da IA.
3. Montar um orçamento formatado para WhatsApp (itens + valores + total).
4. Enviar esse orçamento automaticamente de volta ao cliente, via API do Z-PRO.

Este é um teste ponta-a-ponta: o objetivo imediato é validar o fluxo técnico
completo (recebimento da imagem → IA de visão → resposta automática), usando uma
lista de exames de exemplo. A lista real de exames/valores é trocada depois,
diretamente no prompt do agente.

## Contexto / descobertas

- A documentação disponível na pasta do projeto (`Z-PRO v4.x.x.x.postman_collection.json`)
  cobre apenas a **API externa de saída** do Z-PRO (criar ticket, enviar mensagem,
  listar contatos etc.) — não documenta o formato do webhook de **entrada** que o
  Z-PRO dispara quando um cliente manda uma mensagem.
- A conta n8n já tem vários workflows em produção que integram GChat/Z-PRO com
  agentes de IA para bots de agendamento (ex.: `Agendamento - GChat - Z-PRO
  (clínica exemplo)`, id `yG2mi6ECBpPv4Hmn`). Neles, o Z-PRO chama o webhook do
  n8n com um body como:
  ```json
  { "step": "process", "protocol": "...", "entrada": "texto do cliente", "contactName": "...", "number": "55..." }
  ```
  Nenhum desses fluxos existentes trata **imagem** — todos são só texto. Portanto
  o nome exato do campo que carrega a foto (`mediaUrl`, `file`, `midia`, etc.) é
  **desconhecido até o primeiro teste real** com uma imagem de verdade.
- Existe um sub-workflow reutilizável para envio de texto pelo Z-PRO:
  `MCP Server - Mensageria ZPRO - enviar_texto` (id `Y4ndG7GuIUrmVRxV`), que recebe
  `{ number, body, externalKey, isClosed }`, monta o corpo e faz `POST` para
  `https://apigchat.gtigrupo.com.br/v2/api/external/{apiId}/` usando a credencial
  HTTP Header Auth **"ZPRO API Token - Canal QR - MC AGENDAMENTO"**. Este fluxo
  novo vai **reaproveitar esse mesmo sub-workflow** para enviar a resposta, em vez
  de duplicar a chamada HTTP.
- O node `AI Agent` do n8n (`@n8n/n8n-nodes-langchain.agent`) tem a opção
  `passthroughBinaryImages` (padrão `true`), que repassa automaticamente imagens
  binárias do item de entrada para o modelo de chat como mensagem de imagem —
  não é necessário um node de OCR separado.

## Decisões (confirmadas com o usuário)

| Decisão | Escolha |
|---|---|
| Como responder ao cliente | Assíncrono: o workflow processa a imagem e chama a API do Z-PRO (`SendMessageAPIText`, via sub-workflow existente) para enviar a resposta. O webhook de entrada responde rápido (200 OK) e não fica esperando a IA. |
| Envio automático vs. revisão humana | Automático — a IA monta e já envia o orçamento, sem aprovação humana no meio. |
| Lista de exames/valores | Lista de exemplo (placeholder) embutida no prompt do agente para este teste. Lista real é trocada depois, editando o texto do system prompt do node `AI Agent` no n8n. |
| Exame identificado na imagem mas fora da lista de preços | O orçamento traz os itens reconhecidos normalmente (com valor) e avisa, para os não reconhecidos, que um atendente vai confirmar o valor à parte. Nunca bloqueia o envio do orçamento inteiro por causa de um item não reconhecido. |
| Canal/token do Z-PRO usado para enviar a resposta | Reaproveita o canal/credencial já cadastrados no n8n para "Canal QR - MC AGENDAMENTO" (mesmo usado pelo bot de agendamento), via o sub-workflow `enviar_texto` existente. |
| Workflow | Novo workflow dedicado (não mexe no workflow de agendamento existente). |
| Credenciais (IA, Z-PRO) | Configuradas como credenciais nativas do n8n (não hardcoded nos nodes), para poderem ser trocadas depois sem editar o workflow. |

## Arquitetura

Novo workflow: **`Orçamento de Exames - GChat - Z-PRO (IA Visão)`**

```
Webhook (Z-PRO)
   → Responder 200 OK imediatamente (ack rápido, não espera a IA)
   → Extrair campos do webhook (número, protocolo/ticket, referência da imagem)
   → IF: é mensagem de imagem?
        ├─ não → encerra (não faz nada; este fluxo só trata imagem)
        └─ sim → Baixar imagem (HTTP Request, binário)
                → AI Agent (visão) — system prompt com tabela de exames/valores
                     + OpenAI Chat Model (gpt-4o, com credencial própria)
                → Montar corpo da resposta (body/number/externalKey/isClosed)
                → Execute Workflow: "MCP Server - Mensageria ZPRO - enviar_texto"
   (erro em qualquer etapa crítica → mensagem padrão de fallback, enviada pelo
   mesmo sub-workflow: "Recebemos sua solicitação, nossa equipe vai te
   responder em breve.")
```

### Componentes

1. **Webhook (trigger)** — novo path dedicado (ex.: `orcamento-exames-zpro`),
   `responseMode: lastNode`, responde rápido com um ack simples. Este endpoint
   precisa ser configurado, do lado do Z-PRO, como destino das mensagens do
   canal-alvo (mesmo mecanismo já usado para plugar os bots de agendamento —
   o usuário já sabe fazer isso).

2. **Extrair campos do webhook** — node Set/Code que lê `number`, `protocol`
   (ou equivalente) e a referência da imagem do `body` recebido. Os nomes de
   campo para a imagem são a melhor suposição inicial e **serão corrigidos após
   o primeiro teste real** (ver seção "Suposições em aberto").

3. **IF é imagem?** — segue adiante só se a mensagem recebida for do tipo
   imagem; qualquer outro tipo (texto, áudio, documento) encerra o fluxo sem
   ação, já que este workflow trata exclusivamente pedidos de exame por foto.

4. **Baixar imagem** — HTTP Request que baixa o arquivo da imagem como binário
   (assumindo que o Z-PRO entrega uma URL pública de mídia; se o payload real
   trouxer a imagem em base64 em vez de URL, este node é trocado por uma
   conversão base64 → binário).

5. **AI Agent + OpenAI Chat Model (gpt-4o)** — recebe a imagem baixada como
   binário (repassada automaticamente ao modelo via `passthroughBinaryImages`).
   System prompt contém:
   - Persona: assistente de orçamentos de exames da clínica, respondendo por
     WhatsApp.
   - Tabela de exames + valores (placeholder nesta fase).
   - Instruções: ler os exames pedidos na imagem (impressos ou manuscritos),
     casar com a tabela (tolerando abreviações/sinônimos comuns), montar
     resposta formatada para WhatsApp com itens + valores + total: para exames
     não encontrados na tabela, listar separadamente avisando que um atendente
     vai confirmar o valor. Saída deve ser só o texto final a enviar ao
     cliente (sem comentários extras, sem markdown incompatível com WhatsApp).
   - Credencial de API key da OpenAI própria deste node (independente da usada
     nos bots de agendamento), para poder ser trocada sem afetar outros fluxos.

6. **Montar corpo da resposta** — Set/Code node que monta
   `{ number, body: <texto da IA>, externalKey: <único por execução>,
   isClosed: false }`. `externalKey` gerado por execução (ex.:
   `orcamento-{{ $execution.id }}`) para respeitar a exigência do Z-PRO de
   chave única por ação.

7. **Execute Workflow: enviar_texto** — chama o sub-workflow existente
   `MCP Server - Mensageria ZPRO - enviar_texto` (id `Y4ndG7GuIUrmVRxV`),
   reaproveitando a credencial e a lógica de classificação de erro já
   existentes.

### Tratamento de erro

- Falha ao baixar a imagem ou erro na chamada da IA → segue para o mesmo passo
  de envio (`enviar_texto`), mas com uma mensagem padrão de fallback em vez do
  orçamento, avisando que a equipe vai responder manualmente.
- Falha no próprio envio (API do Z-PRO fora do ar, token inválido etc.) → fica
  registrada na execução do n8n (o sub-workflow já classifica o tipo de erro);
  não há novo retry automático nesta primeira versão.

## Suposições em aberto (validar no primeiro teste real)

- **Nome do campo da imagem no webhook** — assumimos algo como `mediaUrl` (por
  analogia com a API de saída do Z-PRO, que usa esse nome para anexar
  arquivos). Pode ser diferente; corrigido após ver o payload real de uma
  mensagem de imagem.
- **Formato da mídia** — assumimos URL pública, não base64 inline. Se for
  base64, o node "Baixar imagem" é substituído por uma conversão local.
- **Mecanismo de entrega do webhook para imagens** — os exemplos existentes
  nessa conta só cobrem texto (via um passo "Webhook" dentro de um ChatFlow do
  Z-PRO). Se imagens não passarem pelo mesmo tipo de passo, pode ser necessário
  configurar algo diferente no painel do Z-PRO — isso será resolvido junto com
  o usuário durante o teste.

## Plano de teste

1. Criar o workflow no n8n (inativo) e obter a URL de teste do webhook.
2. Usuário configura essa URL como destino de mensagens do canal-alvo no
   painel do Z-PRO.
3. Usuário envia uma foto real de pedido de exames para o número de teste.
4. Inspecionar a execução no n8n para confirmar o payload real recebido e
   ajustar o node "Extrair campos do webhook" (e "Baixar imagem", se
   necessário).
5. Validar que a resposta com o orçamento (lista de exemplo) chega
   corretamente no WhatsApp do cliente de teste.
6. Trocar a lista de exemplo pela lista real de exames/valores no prompt do
   `AI Agent`.

## Revisão 1 (2026-08-21) — fluxo conversacional (texto + imagem)

Depois do primeiro teste real, o usuário apontou que um atendimento real não
chega só como uma foto isolada: o cliente pode mandar texto antes/depois, ou
digitar os nomes dos exames em vez de (ou além de) mandar foto, tudo em
mensagens separadas. O desenho original tratava qualquer mensagem sem imagem
como "não se aplica" e encerrava sem responder — o que quebra esse caso real.

Mudanças no workflow, alinhadas ao mesmo padrão já usado pelo bot de
agendamento desta conta (`Agendamento - GChat - Z-PRO (clínica exemplo)`):

- O node **"É mensagem de imagem?"** deixou de ser um filtro que encerra o
  fluxo — agora só decide se baixa a imagem antes do agente ou não. As duas
  saídas (com ou sem imagem) chegam no `AI Agent`; nenhuma mensagem é mais
  ignorada.
- **"Extrair campos do webhook"** agora também extrai o texto da mensagem
  (`entrada`), no mesmo nome de campo usado pelos bots de agendamento que já
  funcionam nessa conta.
- Adicionada **memória de conversa por sessão** (node `Memória da Sessão
  (Postgres)`, reaproveitando a credencial `Postgres Agendamento - (clínica
  exemplo)`, com `sessionKey` prefixado (`orcamento-<protocolo>`) para não
  colidir com a memória do bot de agendamento). Isso é necessário porque cada
  mensagem do WhatsApp chega como uma execução nova e separada do workflow —
  sem memória persistente, o agente esqueceria o que o cliente já tinha
  mandado numa mensagem anterior.
- O **system prompt do `AI Agent`** foi reescrito para ser conversacional: se
  o cliente ainda não mandou nem foto nem lista de exames (nesta mensagem ou
  antes, na mesma conversa), o agente pede isso educadamente em vez de
  inventar um orçamento vazio; assim que houver pelo menos um exame
  identificável (por imagem, texto, ou o histórico da conversa), ele monta o
  orçamento normalmente.
- O envio da resposta (via sub-workflow `enviar_texto`) passou a acontecer
  sempre, em toda mensagem — porque agora toda mensagem gera uma resposta do
  agente (seja um pedido de mais informação, seja o orçamento final), não só
  quando uma imagem é reconhecida.

### Descoberta durante o teste: payload do webhook chegou vazio

Os dois testes reais feitos pelo usuário mostraram o webhook recebendo
`body: {}` (content-length 0, user-agent `axios/1.19.0`) — ou seja, o Z-PRO
não mandou `protocol`/`entrada`/`contactName`/`number` como os bots de
agendamento recebem. Causa raiz confirmada pelo usuário: no ChatFlow do
Z-PRO, o passo "Webhook Avançado" do fluxo de orçamento (`Menu Orçamento` /
`Menu Orçamento 2`) estava com o campo **Body** vazio, enquanto o do fluxo de
agendamento (`Menu Agendamento` / `Menu Agendamento 2`, que já funciona) tem:

```json
{
  "step": "process",
  "entrada": "{{entrada}}",
  "number": "{{phoneNumber}}",
  "contactName": "{{name}}",
  "protocol": "{{protocol}}"
}
```

Ação do usuário: copiar o mesmo Body (com essas mesmas variáveis) para os
passos "Webhook Avançado" de `Menu Orçamento` e `Menu Orçamento 2`. Os nomes
de campo já batem com o que o node "Extrair campos do webhook" espera
(`body.protocol`, `body.number`, `body.contactName`, `body.entrada`) — não
precisou ajustar nada do lado do n8n para esses campos.

### Descoberta 2: o Z-PRO captura a resposta HTTP e reenvia ao cliente

Nas telas do ChatFlow, o passo "Webhook Avançado" tem uma seção "Resposta da
API (captura e roteamento)": ele salva o corpo da resposta HTTP do nosso
webhook numa variável (`n8n1`) e o passo seguinte ("Mensagem") manda
`{{n8n1}}` de volta ao cliente pelo WhatsApp. Ou seja, **o Z-PRO não usa a
API de envio de mensagens para essa resposta — ele repassa direto o que o
webhook devolver na hora**. Como o "Caminho no JSON" fica vazio, o corpo
precisa ser **texto puro**, não JSON.

Isso invalida a decisão original de "envio assíncrono via API do Z-PRO": o
workflow foi ajustado para responder de forma **síncrona**, com
`responseMode: responseNode` no Webhook e um node "Respond to Webhook"
(`respondWith: text`) devolvendo o texto final direto na resposta HTTP. O
node "Enviar orçamento (Z-PRO)" (chamada assíncrona ao sub-workflow
`enviar_texto`) foi removido — mantê-lo mandaria a mensagem duas vezes.

### Descoberta 3: memória de conversa

A credencial Postgres reaproveitada do bot de agendamento
(`Postgres Agendamento - (clínica exemplo)`) é de uso exclusivo daquele
fluxo — o usuário pediu para não usá-la aqui sem autorização explícita. A
memória de sessão agora usa o node nativo **Simple Memory**
(`memoryBufferWindow`, sem credencial), com `sessionKey` prefixado
(`orcamento-<protocolo ou telefone>`) para isolar as conversas de orçamento
das de agendamento.

### Descoberta 4: ChatFlow do Z-PRO não tem nenhum caminho pra imagem (confirmado)

Investigação exaustiva, todas as vias fechadas:

- **Seletor de variáveis** do passo "Webhook Avançado": só campos de
  contato/sessão (Nome, Saudação, Protocolo, Email, Telefone, Kanban,
  Atendente, Email do atendente, Primeiro/Sobrenome, Empresa) — nenhuma
  variável de mídia.
- **Consulta à API do Z-PRO** (`showticketchatbot`, buscando o ticket pelo
  número) — tentativa abandonada: no teste real, retornou um ticket
  **fechado, de mais de um mês atrás**, sobre um assunto não relacionado.
  Essa API não busca de forma confiável "a conversa/mensagem atual".
- **Passo "n8n"** (interação alternativa ao "Webhook"): mesma lista de
  variáveis de contato/sessão, sem corpo customizável — não ajuda.
- **Passo "Mídia"**: é o oposto do que se imaginava — serve pra o *bot*
  enviar um arquivo *pro* cliente (seleciona arquivo + legenda), não pra
  capturar o que o cliente manda.
- **"Tipo da variável"** na captura de resposta (seção "Variável (opcional)"
  dos passos "Mensagem"/"n8n"): só permite capturar texto livre — sem opção
  de mídia/arquivo.

**Conclusão:** o construtor de ChatFlow do Z-PRO, na versão em uso, não tem
nenhum mecanismo para repassar uma imagem recebida do cliente para um
webhook externo. Não é uma configuração faltando — é uma limitação da
ferramenta nesse ponto. Corrigido o prompt do `AI Agent` pra não prometer
mais "mande uma foto" ao cliente (antes disso ele pedia foto mesmo sem
nunca conseguir processar nenhuma).

### Descoberta 5: "Webhook do Canal" resolve a imagem (solução final)

O Z-PRO tem, nas configurações do canal, uma opção **"Webhook do Canal"**
independente do ChatFlow: `Habilitar Webhook do Canal` + `URL de destino` +
toggle `Mensagens recebidas` (dispara a cada mensagem recebida pelo canal,
"em paralelo ao webhook geral do tenant"). Payload real capturado:

```json
{
  "method": "message",
  "msg": {
    "from": "5575...",
    "id": "wamid....",
    "timestamp": "...",
    "type": "image",
    "image": { "mime_type": "image/jpeg", "id": "...", "url": "https://lookaside.fbsbx.com/whatsapp_business/attachments/?..." }
  },
  "ticket": {
    "protocol": "...", "id": 469774, "status": "pending",
    "contact": { "name": "...", "number": "..." },
    "whatsapp": { "bmToken": "EAA..." }
  }
}
```

Pra mensagem de texto, `msg` vem como `{ "type": "text", "text": { "body": "..." } }`
em vez de `image`. O workflow foi reconstruído em cima desse webhook:

- Novo endpoint: `orcamento-exames-canal-zpro` (path completamente separado
  do antigo `orcamento-exames-zpro`, que foi removido).
- Campos extraídos: `sessionId` (`ticket.protocol`), `telefone` (`msg.from`),
  `nomeContato` (`ticket.contact.name`), `entrada` (`msg.text.body`),
  `imagemUrl` (`msg.image.url`), `tipoMidia` (`msg.type`), `mediaToken`
  (`ticket.whatsapp.bmToken`).
- A URL da imagem é do WhatsApp/Meta (`lookaside.fbsbx.com`) e exige
  autenticação — o node "Baixar imagem" manda `Authorization: Bearer
  {{ mediaToken }}` usando o `bmToken` do próprio payload.
- Como esse webhook é uma notificação assíncrona (não é capturado e
  reenviado pelo Z-PRO como no mecanismo do ChatFlow), o envio da resposta
  voltou a ser feito via API, reaproveitando o sub-workflow
  `enviar_texto` (mesma lógica da primeira versão do desenho).
- **Importante:** esse webhook dispara em paralelo a qualquer coisa que o
  ChatFlow também dispare para a mesma mensagem. Por isso as interações
  "Webhook Avançado" e "Mensagem" dos passos `Menu Orçamento` / `Menu
  Orçamento 2` no ChatFlow precisam ser removidas (ação do usuário, fora do
  n8n) — senão o cliente recebe duas respostas pra cada mensagem.
- O prompt do `AI Agent` voltou a aceitar/pedir foto normalmente, já que a
  imagem agora chega de verdade.

### Teste ponta-a-ponta validado

Com uma imagem real de teste, o fluxo completo funcionou: download
autenticado da mídia (44.9 kB, jpg) → IA de visão leu a imagem e
identificou 2 exames da tabela + 1 fora da tabela (avisando que precisa de
confirmação) → resposta enviada com sucesso pelo Z-PRO. Texto puro também
validado (cliente manda "oi" → IA pede pra digitar/mandar os exames).

### Descoberta 6: canal/API errados no envio (corrigido)

O envio estava reaproveitando o sub-workflow `enviar_texto`
(`Y4ndG7GuIUrmVRxV`), que pertence a **outro projeto** (bot de agendamento)
e usa um ApiID/canal diferente — por isso as respostas saíam por um número
errado (recebendo num número, respondendo por outro). O usuário criou um
ApiID e token dedicados a este projeto. Correção aplicada:

- Nova credencial `httpHeaderAuth` **"ZPRO API Token - Orçamento de
  Exames"** (nome deliberadamente diferente de "ZPRO API Token - Canal QR -
  MC AGENDAMENTO", pra não confundir entre projetos), header `Authorization:
  Bearer <token>`.
- O envio deixou de chamar o sub-workflow compartilhado — agora é uma
  chamada HTTP direta (`POST`) dentro deste próprio workflow, isolada,
  usando a URL `https://apigchat.gtigrupo.com.br/v2/api/external/<ApiID
  deste projeto>/` e a credencial acima.
- Isso mantém este projeto completamente independente do de agendamento —
  nenhum node ou credencial é compartilhado entre os dois.

### Descoberta 7: filtro por fluxo/fila (o bot respondia a qualquer mensagem)

Como o "Webhook do Canal" dispara pra **toda mensagem do número** (não só
pra quem está no menu de Orçamento), o bot estava respondendo pra qualquer
coisa — cliente mandando foto do CPF, pedindo agendamento, etc. — sempre
pedindo exames. Isso não reflete o atendimento real: o cliente manda
mensagem, recebe o menu de filas, escolhe "Orçamento", e só a partir daí a
automação deve agir.

Correção: o payload do webhook traz `ticket.stepChatFlow`, identificando em
qual passo do ChatFlow o ticket está parado. Os passos `Menu Orçamento` e
`Menu Orçamento 2` (os únicos dois pontos do ChatFlow que levam a essa
automação) têm ids fixos: `node-1787312722889` e `node-1787312980617`.
Adicionado o node **"Está no fluxo de Orçamento?"**, logo após extrair os
campos: só segue adiante (pro resto do pipeline) se `stepChatFlow` for um
desses dois; qualquer outra coisa cai num `NoOp` e é ignorada — sem
resposta nenhuma, deixando pra fila/fluxo correspondente cuidar.

**Risco conhecido:** esse filtro depende dos ids de step atuais do
ChatFlow. Se o `Menu Orçamento`/`Menu Orçamento 2` forem recriados (não só
editados) no editor do Z-PRO, os ids mudam e o filtro precisa ser
atualizado no node `Está no fluxo de Orçamento?`.

### Descoberta 8: pipeline de áudio confirmado ponta-a-ponta

Adicionado suporte a mensagens de áudio: `Baixar áudio` (HTTP Request com o
`bmToken`) → `Transcrever áudio` (OpenAI node, resource=audio,
operation=transcribe, Whisper `whisper-1`) → `Preparar texto do áudio` (Set
node que popula `entrada` com a transcrição) → segue pro `AI Agent -
Orçamento` normalmente.

Confirmado via execução real **#476** (2026-08-21 17:31): cliente mandou um
áudio de 5s, o Whisper transcreveu corretamente *"Eu não tenho foto não,
quero saber o valor da Hemograma."*, e o AI Agent respondeu certo *"Olá! O
Hemograma custa R$ 35,00."*. Pipeline de texto, imagem, PDF e áudio todos
validados com execuções reais.

### Ainda em aberto

- Remover as interações antigas "Webhook Avançado"/"Mensagem" dos passos
  `Menu Orçamento`/`Menu Orçamento 2` no ChatFlow (apontavam pro endpoint
  antigo, que não existe mais no n8n — não causam mais duplicidade, mas
  ficam como chamada morta até serem removidas).

## Fora de escopo (por enquanto)

- Fila/aprovação humana antes do envio (usuário optou por envio automático).
- Fonte de preços fora do prompt (planilha/banco) — pode ser considerado no
  futuro se a lista crescer muito, mas não faz parte deste teste.
- Retry automático em caso de falha de envio.