# Listas

Listas são conjuntos de valores usados para parametrizar [regras](/pt/rules/) sem precisar editá-las a cada mudança. Nas [expressões](/pt/rules/expression-syntax/#coleções-), a lista é referenciada pelo seu nome com o prefixo `@`:

```
$user_id in @clientes_quarentena
```

Manter dados em listas separa a responsabilidade da operação (que mantém os itens) da responsabilidade técnica (que mantém as regras), reduzindo o risco de alterações acidentais nas regras. Cada lista guarda valores de texto de até 128 caracteres, sem quebras de linha.

## Criar uma lista

Em **Configurações > Listas > Nova lista**:

1. Escolha um nome usando apenas letras, números, hífen e sublinhado (ex.: `clientes-quarentena`).
2. Inclua uma descrição opcional.
3. Clique em **Criar lista**.

O nome é o identificador usado nas expressões e **não pode ser alterado depois da criação**: uma regra que referenciasse o nome antigo deixaria de encontrar os itens.

## Adicionar itens

Abra a lista desejada e clique em **Adicionar itens**:

1. Insira um item por linha.
2. Inclua uma descrição opcional, repetida em todos os itens da inserção (útil para referenciar um ticket de atendimento, por exemplo).
3. Opcionalmente, defina um prazo de validade, em minutos, horas ou dias, no mínimo 5 minutos e no máximo 2 anos. Sem prazo, o item permanece até remoção manual.

Cada lista comporta até **10.000 itens**. Você pode adicionar até **1.000 itens por inserção**; para cadastrar volumes maiores, divida o conteúdo em mais de uma inserção.

Também é possível adicionar itens pela API, com `POST /lists/{list_id}/items`. O prazo de validade é informado em `expires_in`, como um período ISO 8601 (`PT30M`, `PT12H`, `P1D`).

## Itens adicionados por regras

Uma regra pode escrever em uma lista durante o processamento de um evento, com a ação [adicionar à lista](/pt/rules/actions/add_to_list/). Dessa forma, uma regra incorpora o que já observou: uma condição detecta o comportamento e registra o valor na lista, e os eventos seguintes consultam essa lista com uma condição comum.

Ao acompanhar uma lista escrita por regras, considere que:

- os itens aparecem **sem descrição e sem autor**, já que não foram cadastrados por uma pessoa;
- um valor detectado de novo **renova o prazo** do item existente, em vez de criar outro;
- com a lista **cheia**, valores novos deixam de ser adicionados; convém acompanhar a quantidade de itens em listas alimentadas automaticamente.

## Consultar e remover itens

Itens podem ser paginados ou buscados pelo campo de busca no topo da tabela. Para remover, use **⋮ > Remover** no item desejado, ou **Remover todos os itens** para limpar a lista.

Itens com prazo de validade são removidos automaticamente por varreduras periódicas, executadas a cada poucos minutos. Por isso um item pode continuar valendo em uma condição por alguns minutos além do prazo, e é também por isso que o prazo mínimo é de 5 minutos.

## Remover uma lista

Uma lista só pode ser removida quando está vazia e não é usada por nenhuma regra ativa nem por nenhum monitoramento. Remova os itens e as referências antes de excluí-la.