# Sintaxe para expressões

As expressões usadas em [regras](/pt/transactional/rules/) seguem uma sintaxe enxuta inspirada em fórmulas de planilhas. Cada expressão é composta por, no mínimo, uma **variável**, uma **operação** e um **valor**.

```
$merchant_id == "XYZ"
```

A expressão acima é verdadeira quando o ID do estabelecimento é igual a `"XYZ"`.

## Variáveis

Toda variável começa com `$`. As variáveis disponíveis dependem do tipo de evento avaliado.

| Variável                 | Conteúdo                                                                  | Tipo        | Exemplo        |
|--------------------------|---------------------------------------------------------------------------|-------------|----------------|
| `$amount`                | Valor total do pagamento                                                  | Decimal     | `100.12`       |
| `$card_bin`              | Primeiros 6 a 8 dígitos do PAN (BIN/IIN)                                  | Texto       | `"44332211"`   |
| `$card_issuer_country`   | País do emissor do cartão (ISO 3166-1 alfa-2)                             | Texto       | `"BR"`         |
| `$card_last_four`        | Últimos quatro dígitos do cartão                                          | Texto       | `"1234"`       |
| `$device_fingerprint_id` | Fingerprint do dispositivo                                                | Texto       | `"xyz"`        |
| `$device_ip_address`     | Endereço IP do dispositivo                                                | Endereço IP | `"200.123.10.2"` |
| `$device_user_agent`     | User-Agent do dispositivo                                                 | Texto       | `"Mozilla/5.0"` |
| `$merchant_id`           | ID do estabelecimento                                                     | Texto       | `"loja-1234"`  |
| `$metadata_[chave]`      | Metadado enviado via API                                                  | Texto       | `"valor"`      |
| `$score`                 | Score de risco calculado pela plataforma (0,00 a 1,00)                    | Decimal     | `0.75`         |
| `$user_email_domain`     | Domínio do email do usuário                                               | Texto       | `"gmail.com"`  |
| `$user_id`               | ID do usuário                                                             | Texto       | `"cliente-1234"` |
| `$user_profiles`         | Perfis de pagamento do usuário (apenas com a função `count`)              | Coleção     | N/A            |

## Operações

| Operação | Significado            |
|----------|------------------------|
| `==`     | Igualdade              |
| `!=`     | Desigualdade           |
| `>`      | Maior que              |
| `>=`     | Maior ou igual         |
| `<`      | Menor que              |
| `<=`     | Menor ou igual         |
| `in`     | Pertence a uma coleção |
| `not in` | Não pertence a uma coleção |

## Valores

O valor comparado com uma variável pode ser um texto ou um número:

- **Texto**: sempre entre aspas duplas, como `"XYZ"`. Aspas simples e textos sem aspas não são aceitos.
- **Número**: escrito sem aspas, usando ponto como separador decimal, como `1000` ou `99.01`.

Como todo texto fica entre aspas duplas, valores como um IP, uma data ou uma palavra usada na própria sintaxe (por exemplo, `in`) também precisam das aspas para serem tratados como texto.

Para verificar se uma variável está vazia, compare-a com `null` (sem aspas) usando `==` ou `!=`:

```
$device_fingerprint_id == null
```

A expressão acima é verdadeira quando o evento não tem fingerprint do dispositivo. Use `!=` para o caso contrário, quando a variável tem algum valor.

## Funções

### `concat`

A função `concat` junta vários valores em um único texto, que pode ser comparado com um valor. Cada argumento é uma variável (`$variável`) ou um texto fixo, separados por vírgula:

```
concat($user_id, "-", $merchant_id) == "cliente-1234-loja-1234"
```

A expressão acima é verdadeira quando a combinação do ID do usuário e do ID do estabelecimento, unidos por um hífen, resulta em `"cliente-1234-loja-1234"`.

Considerações sobre os valores juntados:

- Variáveis sem valor são tratadas como texto vazio.
- Valores numéricos são convertidos para texto na forma original (por exemplo, `99.01` e `0.9`).

## Combinando expressões

Use `and` e `or` para combinar expressões. O `and` tem precedência sobre o `or`: em uma combinação sem parênteses, as partes ligadas por `and` são avaliadas primeiro. Assim, `A and B or C` equivale a `(A and B) or C`.

Use parênteses para agrupar expressões e alterar essa precedência:

```
($amount > 1000 and $user_email_domain == "gmail.com") or $card_issuer_country != "BR"
```

## Listas

Listas configuradas em **Configurações > Listas** ficam disponíveis como coleções. Por exemplo, para verificar se um cliente está em uma lista de quarentena:

```
$user_id in @clientes_quarentena
```

Também é possível escrever a coleção diretamente na expressão, entre colchetes e com os valores separados por vírgula. Por exemplo, para verificar se o país do emissor do cartão não está entre os países atendidos:

```
$card_issuer_country not in ["BR", "AR", "CL"]
```