Sintaxe para expressões

Escreva a expressão de uma condição em uma sintaxe enxuta, inspirada em fórmulas de planilhas. A expressão resulta sempre em verdadeiro ou falso e combina, no mínimo, uma variável, uma operação e um valor.

$merchant_id == "XYZ"

A expressão acima é verdadeira quando o campo merchant_id do evento é igual a "XYZ".

Os três prefixos

Toda variável começa com um prefixo que indica de onde o valor vem e quanto tempo ele dura:

Prefixo	Contém	Duração
$campo	um campo do evento	persistido com o evento
@lista	uma lista de valores da conta	mantida pela conta, entre eventos
%temporaria	um valor calculado durante esta execução	só existe durante a execução da regra

Campos do evento ($)

As variáveis são exatamente os campos do tipo de evento ao qual a regra pertence. Não existe uma lista fixa. Se o tipo de evento tem um campo amount, a regra pode usar $amount; um tipo de evento diferente terá outro conjunto de variáveis.

Enquanto você escreve a condição, o painel oferece os campos disponíveis e destaca a expressão. Os campos iniciados por _ são reservados da plataforma e não ficam disponíveis para uso em expressões.

Além dos campos do tipo de evento, $id contém o identificador do evento informado em POST /events. A variável $id vale nas condições e como dimensão de uma análise.

O tipo do campo determina como o valor é comparado:

Tipo do campo	Exemplo de comparação
Texto	$status == "approved"
Inteiro	$installments > 6
Decimal	$amount >= 1500.00
Booleano	$is_first_purchase == true
Data e hora	$signup_at > "30 days ago"

Um campo que não veio no evento é tratado como vazio. Para testar essa ausência, compare com null, sem aspas:

$device_fingerprint_id == null

A expressão acima é verdadeira quando o evento não trouxe fingerprint do dispositivo. Use != para o caso contrário.

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
any in	Pelo menos um dos valores pertence a uma coleção
all in	Todos os valores pertencem a uma coleção
=~	Corresponde a uma expressão regular
!~	Não corresponde a uma expressão regular

Valores

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

• Texto: sempre entre aspas duplas, como "XYZ". Aspas simples e textos sem aspas não são aceitos.
• Número: sem aspas, com ponto como separador decimal, como 1000 ou 99.01.
• Booleano: true ou false, sem aspas.

Todo texto fica entre aspas duplas. Um IP, uma data ou uma palavra usada na própria sintaxe (por exemplo, in) também precisa das aspas para ser tratado como texto.

Datas

Campos de data e hora aceitam valores relativos e absolutos, sempre entre aspas:

$signup_at > "30 days ago"
$signup_at == "2026-03-15"

O formato relativo é [número] [hour|day|week|month|year]s ago. O formato absoluto aceita ano ("2026"), ano e mês ("2026-03") ou data completa ("2026-03-15"). Com ano, ou com ano e mês, a comparação cobre todo o período.

Combinação de 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, a plataforma avalia primeiro as partes ligadas por and. 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 $issuer_country != "BR"

Uma quebra de linha funciona como um espaço entre os termos. Distribua uma combinação longa em várias linhas para facilitar a leitura, sem alterar o resultado:

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

true e false como condição inteira

Uma expressão pode consistir apenas em true ou false, sem variável nem comparação. true é sempre verdadeira e mantém a condição sempre ativa. false é sempre falsa e desativa a condição sem removê-la. O uso difere da comparação de um campo booleano com true ou false, descrita em Valores. Naquela comparação, o literal está à direita do operador; como condição inteira, o literal constitui a expressão por completo.

Coleções (@)

A plataforma oferece as listas da conta como coleções, identificadas pelo prefixo @. Por exemplo, para verificar se um cliente está em uma lista de quarentena:

$user_id in @clientes_quarentena

Escreva também a coleção diretamente na expressão, entre colchetes e com os valores separados por vírgula:

$issuer_country not in ["BR", "AR", "CL"]

Além do formato acima, in e not in aceitam:

• um texto fixo à esquerda, para testar um valor conhecido contra uma coleção: "BR" in @paises_atendidos;
• um campo dos dois lados, para testar se o valor de um campo está contido no de outro: $user_id in $allowed_users.

Teste de vários valores

Uma coleção escrita entre colchetes do lado esquerdo exige um quantificador. A expressão declara quantos dos valores precisam pertencer à coleção da direita:

Operação	Verdadeira quando
any in	pelo menos um dos valores pertence
all in	todos os valores pertencem
not in	nenhum dos valores pertence

["susp_59", "susp_83"] any in %regua.triggered_cells
["BR", "AR"] all in @paises_atendidos
["tor", "vpn"] not in @tipos_permitidos

Não existe forma sem quantificador. Escrever ["a", "b"] in @lista é um erro de escrita. “A e B estão na lista” é ambíguo entre “pelo menos um” e “os dois”, e uma condição de risco não pode depender de qual das duas leituras o autor tinha em mente. Na negação a ambiguidade não existe, já que “A e B não estão na lista” só pode significar que nenhum dos dois está. Por isso not in dispensa quantificador, e pelo mesmo motivo not any in e not all in não são aceitos.

A coleção da direita pode ser uma lista da conta, uma variável temporária de conjunto, um campo ou outra coleção literal.

Expressões regulares

Os operadores =~ e !~ comparam um texto com uma expressão regular. =~ é verdadeira quando o padrão ocorre no texto, e !~ quando o padrão não ocorre:

$merchant_id =~ "(?i)^m"
split($user_email, "@", -1) !~ "\.com\.br$"

A primeira expressão é verdadeira quando o ID do estabelecimento começa com m, maiúsculo ou minúsculo.

O padrão segue a sintaxe RE2:

• Correspondência parcial: sem âncoras, o padrão pode ocorrer em qualquer posição do texto. ^ e $ ancoram no início e no fim do texto inteiro.
• Maiúsculas e minúsculas: a comparação as diferencia. O prefixo (?i) desfaz a distinção.
• Quebra de linha: o . não corresponde a uma quebra de linha.
• Recursos ausentes: lookahead, lookbehind e referências a grupos anteriores não são aceitos. Um padrão como a(?=b) é recusado ao salvar.

O padrão é um texto fixo entre aspas duplas, com até 256 caracteres. Um campo não ocupa o lugar do padrão. Uma aspa dupla dentro do padrão é escrita como \x22.

À esquerda do operador, a expressão admite um campo de texto ou de lista, uma variável temporária de texto, um concat ou um split. Campos numéricos, booleanos e de data, assim como conjuntos, são recusados ao salvar.

Um valor ausente é tratado como texto vazio. Assim, $x !~ "foo" é verdadeira quando o evento não contém o campo x.

Um texto com mais de 4 KB não é comparado, e a condição não é atendida, tanto com =~ quanto com !~. As demais condições da regra seguem normalmente. Um campo do evento tem no máximo 1.024 bytes, e por isso só um concat ou uma variável temporária alcança esse tamanho.

Variáveis temporárias (%)

Uma variável temporária guarda um valor calculado durante a execução da regra. Uma ação produz a variável temporária e as condições seguintes leem o valor. A plataforma não grava a variável temporária no evento, não a devolve na resposta da API e não a reaproveita no próximo evento. Grave em um campo o valor que precise sobreviver ao evento.

As variáveis temporárias existem em duas formas.

Valores simples, definidos por uma ação de definir variável temporária:

%revisao_manual == "1"

Resultados publicados por uma ação produtora, como executar análise ou enriquecer, sob o nome do resultado, com chaves acessadas por ponto. A página de cada ação lista as suas chaves. O resultado de uma análise apresenta as seguintes chaves:

Chave	Contém	Tipo
score	score calculado pela análise	Decimal
score_cell	nome da célula que originou o score	Texto
triggered	se a análise foi acionada	Booleano
triggered_count	quantas células foram acionadas	Inteiro
triggered_cells	nomes das células acionadas	Conjunto
version	versão da análise executada	Inteiro

%bot.triggered_count >= 2

A chave triggered_cells é um conjunto, não um valor único. Use triggered_cells apenas à direita de uma operação de pertencimento, para testar quais células foram acionadas.

"email_velocity" in %bot.triggered_cells
["susp_59", "susp_83"] any in %bot.triggered_cells

Comparar o conjunto com ==, ou usá-lo em qualquer outra operação, é um erro de escrita e a condição não é aceita. Em uma ação, a função join converte o conjunto em texto.

Uma ação em modo expressão também pode guardar um conjunto em uma variável temporária simples. O valor continua sendo um conjunto e é testado da mesma forma.

Funções

concat

A função concat junta vários valores em um único texto, comparável com um valor. Cada argumento é um campo do evento ($campo), uma variável temporária (%temporaria) ou um texto fixo, separados por vírgula:

concat($user_id, "-", $merchant_id) == "cliente-1234-loja-1234"
concat($merchant_id, "-", %bot.score_cell) == "loja-1234-email_velocity"

A primeira expressão é 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:

• Uma variável sem valor é tratada como texto vazio.
• Um valor numérico é convertido para texto na forma original (por exemplo, 99.01 e 0.9).
• Um conjunto, como %bot.triggered_cells, não pode entrar em um concat. O conjunto é testado com uma operação de pertencimento ou convertido em texto com join.

O resultado de concat também aceita in e not in, para comparar a combinação com uma lista:

concat($user_id, "-", $merchant_id) in @pares_bloqueados

split

A função split divide um texto por um separador e devolve uma das partes. Os argumentos são o valor (um campo do evento ou uma variável temporária), o separador entre aspas duplas e a posição da parte:

split($user_email, "@", -1) == "gmail.com"

A expressão acima é verdadeira quando a última parte do e-mail depois de @, o domínio, é gmail.com.

Considerações sobre a divisão:

• A posição começa em 0. Uma posição negativa conta a partir do fim, e -1 é a última parte.
• O separador não pode ser vazio e pode ter mais de um caractere.
• Um valor que não é texto é convertido para texto antes da divisão. Um conjunto não é aceito.
• As partes vazias contam. Dividido por "@", o texto "ana@" tem "" na posição -1.
• Uma posição fora do intervalo resulta em texto vazio em uma condição. Em uma ação, nada é gravado.

O resultado de split é um texto e admite as mesmas operações de um texto, inclusive in, not in e as expressões regulares. Um split não entra em um concat, e um concat não entra em um split.

join

A função join converte um conjunto em texto, com os elementos separados pelo separador informado:

join(%bot.triggered_cells, ",")

O primeiro argumento é uma variável temporária de conjunto, como %bot.triggered_cells. O segundo é o separador, entre aspas duplas.

A função join vale apenas como o valor inteiro de uma ação em modo expressão. Uma condição não usa join, e um join não entra em um concat. Um conjunto vazio não grava nada.

Erros de escrita

A plataforma valida a expressão no momento em que você salva a condição. O painel aponta o problema e a regra não é publicada enquanto houver erro. Os casos mais comuns:

• campo inexistente: a variável não corresponde a nenhum campo do tipo de evento vinculado à regra;
• tipo incompatível: o valor comparado não faz sentido para o tipo do campo, como comparar um campo numérico com "aprovado";
• variável temporária desconhecida: o nome ou o atributo não é produzido por nenhuma ação da regra;
• variável temporária lida cedo demais: nenhuma condição anterior a produz. Como as condições são avaliadas em ordem, o produtor precisa vir antes do leitor;
• texto sem aspas: valores de texto precisam de aspas duplas.

Cada expressão tem um limite de tamanho. Consulte limites e parâmetros.