---
title: "Scripts de gatilho"
slug: "scripts-de-gatilho"
updated: 2026-09-11T20:02:56Z
published: 2026-09-11T20:02:56Z
canonical: "docs.omnisiga.ai/scripts-de-gatilho"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omnisiga.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Scripts de gatilho

Neste artigo você vai aprender a usar **scripts** nos componentes do dispositivo de emissão de tickets. Um script é um pequeno código JavaScript que o totem executa quando algo acontece com o componente, como quando o cidadão toca em um botão ou quando um campo precisa ser validado.

Com scripts, é possível mostrar avisos ao cidadão, consultar sistemas externos, guardar informações e decidir para qual tela o totem deve ir.

---

## Onde criar um script

1. Abra **Configuração → Canais → Presencial → Editor de dispositivo de emissão** e entre no dispositivo desejado.
2. Selecione um componente na tela, como botão, texto, imagem, campo de texto ou teclado numérico.
3. No painel de propriedades, abra a seção **Script**.
4. Clique em **Adicionar gatilho**, informe o **nome do gatilho** e escolha o **evento** em que o script deve executar.
5. Clique em **Editar script**, escreva o código e confirme.
6. Salve o dispositivo. Use o modo **Testar** para validar o comportamento antes de enviar a configuração ao totem real.

![Image](https://cdn.document360.io/d1786d22-23e4-4145-98ac-accd680324d8/Images/Documentation/image(828).png)

---

## Eventos disponíveis

| Evento | Quando o script executa |
| --- | --- |
| **Clique** | Quando o cidadão toca no componente. Disponível em botões e também em textos, imagens e campos que podem se comportar como botões. |
| **Tecla pressionada** | A cada tecla do teclado numérico. |
| **Foco** | Quando o campo de texto recebe o foco. |
| **Perda de foco** | Quando o campo de texto perde o foco. |
| **Mudança** | Quando o conteúdo do campo muda. |
| **Validar** | Quando o valor digitado precisa ser validado, a cada tecla do teclado numérico. |

O evento **Validar** permite bloquear o avanço do cidadão quando o valor digitado não é aceito.

---

## O que o script pode usar

Todo script recebe um contexto com os objetos abaixo. Eles estão disponíveis diretamente pelo nome e não é necessário importar nada.

| Objeto | O que é |
| --- | --- |
| `vars` | As variáveis do totem naquele momento. Qualquer valor gravado em `vars` fica disponível para os próximos scripts e para o fluxo de atendimento. |
| `http` | Cliente para chamadas a sistemas externos, com os métodos `get`, `post`, `put`, `patch` e `delete`. |
| `alert` | Avisos exibidos na tela do totem. |
| `navigation` | Navegação entre telas. |
| `input` | O valor associado ao evento. Na validação de um campo, contém o valor atual e a tecla pressionada. |
| `utils` | Reservado para funções auxiliares. Na versão atual, ainda não possui funções. |

O script é executado como uma função assíncrona. Por isso, é possível usar `await` para aguardar respostas de `http` e `alert`.

#### `vars` — variáveis do totem

Leia uma variável usando:

```
vars.nomeDaVariavel
```

Grave uma variável usando:

```
vars.nomeDaVariavel = valor
```

O que o script gravar em `vars` permanece disponível para os próximos scripts e é enviado ao fluxo de atendimento vinculado ao componente.

As variáveis também podem ser criadas sem script, na seção **Variáveis** do componente. No campo de texto, o valor digitado pelo cidadão é guardado na variável informada em **Nome da variável** e fica disponível para os scripts e para o fluxo.

#### `http` — chamadas externas

| Método | Uso |
| --- | --- |
| `http.get(url, opcoes?)` | Consulta. |
| `http.post(url, corpo, opcoes?)` | Envio de dados. O corpo é enviado como JSON. |
| `http.put(url, corpo, opcoes?)` | Atualização completa. |
| `http.patch(url, corpo, opcoes?)` | Atualização parcial. |
| `http.delete(url, opcoes?)` | Exclusão. |

Todas as chamadas devolvem `status` e `body`. Quando a resposta não é de sucesso, a chamada gera um erro com `status` e `body`. Use `try/catch` para tratar esse cenário.

#### `alert` — avisos na tela

| Chamada | Efeito |
| --- | --- |
| `alert.success(titulo, texto)` | Exibe um aviso de sucesso, que desaparece automaticamente após 2 segundos. |
| `alert.error(titulo, texto)` | Exibe um aviso de erro, que desaparece automaticamente após 3,5 segundos. |
| `alert.question(texto, opcoes)` | Exibe uma pergunta com os botões **Confirmar** e **Cancelar**. Retorna a resposta do cidadão. |
| `alert.nameInput(titulo, placeholder)` | Exibe uma janela com campo de digitação e retorna o valor informado pelo cidadão. |

#### `navigation` — ir para outra tela

Grave em `navigation.go` o **nome exato de uma tela** do dispositivo.

```
navigation.go = 'Tela Agradecimento';
```

Quando o script termina, o totem vai para essa tela. Se o nome não corresponder a nenhuma tela existente, o totem permanece onde está.

---

## Regra do valor de retorno

O valor devolvido pelo script com `return` controla o que acontece em seguida.

| Retorno | Efeito |
| --- | --- |
| `true` ou outro valor verdadeiro que não seja texto | Continua. O totem executa o fluxo vinculado e as demais ações do componente. |
| Um texto | O totem mostra o texto como aviso de erro e interrompe as ações do componente. |
| `false` ou sem retorno | Interrompe as ações do componente sem mostrar aviso. |

Por isso, a convenção recomendada é terminar scripts de clique com `return true;` e, na validação, devolver o texto do erro quando o valor informado não for aceito.

---

## Exemplos práticos

#### 1. Mostrar uma mensagem de boas-vindas e navegar

Gatilho **Clique** em um botão:

```
alert.success('Bem-vindo!', 'Seu atendimento foi solicitado.');
navigation.go = 'Tela Agradecimento';
return true;
```

#### 2. Validar o que o cidadão digitou

Gatilho **Validar** em um campo de texto ou teclado numérico. O valor digitado chega em `input.value`:

```
if (!input.value || input.value.trim().length < 5) {
  return 'Digite um código com pelo menos 5 caracteres.';
}

return true;
```

Enquanto o retorno for um texto, o totem mostra o aviso e não avança. Quando o valor é aceito, o script devolve `true`.

#### 3. Guardar o valor digitado para usar no fluxo

Gatilho **Validar** em um campo de código:

```
if (!input.value || input.value.trim() === '') {
  return 'Informe o código de atendimento.';
}

vars.codigoDigitado = input.value.trim();
return true;
```

A variável `codigoDigitado` passa a ficar disponível para outros scripts e para o fluxo de atendimento vinculado ao componente.

#### 4. Consultar um sistema externo antes de continuar

Gatilho **Clique** em um botão de consulta:

```
try {
  const resposta = await http.post('https://api.suaorganizacao.gov.br/consulta', {
    codigo: vars.codigoDigitado
  });

  vars.nomeCidadao = resposta.body.nome;
  vars.temAtendimento = resposta.body.encontrado;

  if (resposta.body.encontrado) {
    navigation.go = 'Tela Confirmacao';
  } else {
    alert.error('Atendimento não localizado', 'Confira o código e tente novamente.');
  }

  return true;
} catch (erro) {
  alert.error('Falha na consulta', 'Tente novamente em instantes.');
  return false;
}
```

#### 5. Pedir confirmação antes de agir

Gatilho **Clique** em um botão de cancelamento:

```
const resposta = await alert.question('Deseja realmente cancelar este atendimento?', {
  title: 'Confirmação',
  confirm: 'Sim, cancelar',
  cancel: 'Voltar'
});

if (!resposta.isConfirmed) {
  return false;
}

navigation.go = 'Tela Inicial';
return true;
```

#### 6. Navegação condicional por tipo de atendimento

Gatilho **Clique** em um botão que decide o caminho:

```
if (vars.preferencial === true) {
  navigation.go = 'Tela Preferencial';
} else {
  navigation.go = 'Tela Geral';
}

return true;
```

#### 7. Contador de toques em uma tela

Gatilho **Clique** em uma imagem ou texto usado como botão:

```
vars.tentativas = (vars.tentativas || 0) + 1;

if (vars.tentativas >= 3) {
  alert.error('Muitas tentativas', 'Procure um atendente no balcão.');
  navigation.go = 'Tela Inicial';
  return false;
}

return true;
```

---

## Como combinar scripts e ações do componente

Ao acionar um componente, o totem executa, nesta ordem:

1. **Gatilhos com script** — na ordem cadastrada. O primeiro que falhar interrompe a execução.
2. **Fluxo de atendimento** vinculado ao componente.
3. **Ações configuradas** do componente, como gravar variáveis, navegar, emitir evento e reiniciar.

Na prática, use o script para decidir e preparar dados, principalmente por meio de `vars` e `navigation.go`. Use as ações do componente para comportamentos fixos, como tela de destino, valores de variáveis e reinicialização.

Quando o script definir `navigation.go`, a navegação definida pelo script prevalece no destino.

---

## Testando os scripts

- Use o botão **Testar** do editor para abrir a pré-visualização e executar a configuração atual, incluindo os scripts.
- Durante o teste, o painel **Debug** mostra a resolução, as variáveis em uso e os eventos acionados. Isso ajuda a verificar se o script gravou os valores esperados em `vars`.
- Teste também em um dispositivo real antes de publicar a configuração.

---

## Boas práticas

- **Termine scripts de clique com `return true`** quando a execução puder continuar. Sem retorno, o totem interrompe as ações do componente silenciosamente.
- **Use mensagens de erro curtas e claras** na validação, pois são exibidas diretamente ao cidadão.
- **Use `try/catch` em chamadas `http`** e trate as falhas para evitar que o cidadão fique preso na tela.
- **Use nomes de tela exatos** ao definir `navigation.go`. O nome precisa corresponder à tela cadastrada.
- **Não coloque segredos no script**, como chaves de API e senhas. O script é executado no navegador do totem e pode ser lido por quem tiver acesso ao dispositivo.
- **Prefira as ações configuráveis** quando não houver condição envolvida. Use scripts principalmente para decisões e operações que dependem de dados.
- **Valide os valores antes de usá-los**. `input.value` pode estar vazio e uma variável pode ainda não existir.

---