Runbook - Variável global do Sagazchat

Manual operacional para criar e gerenciar Configurações > Variável global no Sagazchat. Variáveis globais sao valores unicos por empresa (nao por lead) usados em fluxos para contadores, flags e estado compartilhado.

Status: validado em 2026-05-11 na conta exemplo. Criado e excluido lab_teste_var (id=2) para mapeamento.

1. Onde fica

• Sidebar: Configurações > Variável global
• URL: https://app.sagazchat.com/global-variables
• Endpoint backend: /global-variables (mesmo nome).

2. Estrutura da lista

A tela /global-variables tem:

• breadcrumb Painel de controle > Variável global;
• botao Variável (apenas a palavra, nao “Nova Variável” como em outros modulos);
• tabela com colunas Nome, Descrição, Valor, Ações;
• mensagem “Nenhum variável encontrada” quando vazia (typo: “Nenhum” deveria ser “Nenhuma”).

3. Criar variavel

3.1 Passo a passo via UI

1. Clicar Variável (canto superior direito).

2. Modal Crie uma variável global abre:

   

3. Campos:

   Campo	name	Obrigatorio	Notas
   Nome	name	sim	snake_case, sem espaco. Placeholder: Atendimentos_01.
   Tipo	type	sim	number (default) ou text — selecao por combobox/select.
   Descrição	desc	sim	Textarea. Salvar sem descricao NAO dispara request (validacao silente).
   Valor inicial (opcional)	value	nao	”Digite apenas números ou deixe vazio (use ponto para decimais)”

4. Botao Criar.

   

3.2 Endpoint

POST https://backend.sagazchat.com/global-variables
Authorization: Bearer <jwt>
Content-Type: application/json

{
  "name": "lab_teste_var",
  "desc": "Variavel LAB de teste - sera excluida",
  "type": "number",
  "value": "42"
}

Resposta: 200 + {"message":"success"}.

Quirks do payload:

• value e string ("42", nao 42 numerico) mesmo quando type=number.
• type e literal "number" ou "text".
• Sem campo de criacao reflexa — frontend nao retorna ID na resposta (so success).

3.3 Validacao silente

Se a Descricao estiver vazia, clicar Criar nao dispara request — modal fica aberto sem feedback visual claro (nao vimos toast). Caracteriza validacao puramente no frontend. Para automacao: sempre preencher os 4 campos antes de clicar Criar.

4. Editar variavel

NAO HA UI DE EDICAO.

Quirk MAJOR: o kebab ⋮ da linha tem apenas “Excluir” — nao tem “Editar”. Variavel global e create-only / delete-only pela UI.

Para “alterar” uma variavel: excluir + criar de novo com o mesmo nome (perde historico) OU usar bloco Variavel global dentro do fluxo, que pode somar/subtrair/setar o value em runtime.

Endpoint de update [a validar] — pode haver PUT /global-variables/{id} na API mesmo sem UI exposta.

5. Excluir variavel

1. Kebab ⋮ da linha > Excluir.

2. Modal de confirmacao:

   • Titulo: “Apagar Variável global?”
   • Texto: “Deseja realmente excluir essa Variável?”
   • Botoes: Cancelar / Deletar

   

3. Click Deletar confirma.

DELETE https://backend.sagazchat.com/global-variables/{id}
→ 200 { "message": "success" }

Se a variavel estiver sendo usada em algum fluxo, o fluxo passa a referenciar uma variavel inexistente. A doc confirma: “Atenção: se a variável ainda não foi criada em Configurações, ela não aparece no combobox do bloco. Não adianta preencher o bloco visualmente sem uma variável real cadastrada.” — vale o contrario tambem: se excluir, blocos antigos ficam orfaos.

6. Uso no Flowbuilder

No flowbuilder existe bloco Variável global. Ele aceita acoes em variaveis existentes:

• Somar (numero)
• Subtrair (numero)
• Setar (numero ou texto, depende do tipo)
• Provavelmente Multiplicar/Dividir [a validar — ver runbook fluxos]

A variavel precisa ja existir em /global-variables antes — o combobox do bloco carrega via GET /global-variables.

6.bis Uso estrategico (confirmado pelo administrador 2026-05-11)

“Variável é usado geralmente pra ver como estão as etapas dos funis, quantos leads no começo, final, no meio etc.”

Uso primario: medir etapas do funil. Cria uma variavel por etapa (funil_entrada, funil_qualificou, funil_proposta, funil_fechou), e cada bloco Variavel global em pontos-chave do fluxo incrementa +1 na etapa correspondente.

Funciona como um painel de funil rudimentar dentro do Sagazchat — admin abre /global-variables e ve os contadores em tempo real, sem precisar exportar relatorio.

Usos secundarios (validos mas menos comuns):

• Escassez/limite finito (cupons_disponiveis decrementa).
• Flag operacional da empresa (promo_ativa texto).
• Estado compartilhado entre fluxos distintos.

NAO usar para rotacao de atendentes — para isso ha o bloco Distribuidor.

7. Diferenca entre tipos de variavel no Sagazchat

Tipo	Escopo	Onde criar	Editavel?
Campo personalizado	Por lead	Bate Papo OU bloco Salvar/Manipulador	Sim (valor muda por interacao)
Variavel global	Por empresa	Configurações > Variável global	Nao — so apagar e recriar
Campo do sistema	Por lead	Ja existe — pre-definido	Nao — sao do produto

8. Acoes seguras e perigosas

Acao	Impacto	Regra
Abrir lista	Leitura	Seguro.
Criar lab_*	POST	OK para teste com cleanup.
Excluir variavel em uso	Quebra fluxos que dependem dela	NAO fazer sem ordem.
Criar variavel com nome ja existente	[a validar — provavelmente backend retorna erro]	Validar antes em produção.

9. Quirks consolidados

• Botao “Variável” (sem “Nova”).
• Descricao obrigatoria — sem ela, Criar nao dispara request, sem feedback visual claro.
• Tipo number/text literais.
• value sempre string mesmo em tipo number.
• Sem “Editar” no kebab — create/delete only.
• Resposta {"message":"success"} sem ID — tem que listar para descobrir o id criado.
• Confirmacao usa “Deletar” como botao (nao “Excluir”).
• Typo “Nenhum variável” quando lista vazia.

10. Pendencias

• Validar UI exata do combobox de Tipo (acoes ao trocar entre number e text).
• Verificar comportamento do bloco Variável global no flowbuilder (acoes disponiveis por tipo).
• Confirmar se backend tem PUT /global-variables/{id} (atualizar valor via API).
• Verificar comportamento ao tentar criar variavel com nome duplicado.

11. Imagens

• public/media/nova-ui/variavel-global-lista.png
• public/media/nova-ui/variavel-global-modal-add.png
• public/media/nova-ui/variavel-global-modal-preenchido.png
• public/media/nova-ui/variavel-global-modal-excluir.png

12. Scripts validados

node scripts/sagaz-globalvar-mapear.mjs       # lista
node scripts/sagaz-globalvar-criar-lab.mjs    # modal Crie variável + tenta criar
node scripts/sagaz-globalvar-completar.mjs    # completa descrição + Criar + Excluir cleanup