Sintaxis para expresiones

Escriba la expresión de una condición en una sintaxis sencilla, inspirada en fórmulas de planillas. La expresión resulta siempre en verdadero o falso y combina, como mínimo, una variable, una operación y un valor.

$merchant_id == "XYZ"

La expresión anterior es verdadera cuando el campo merchant_id del evento es igual a "XYZ".

Los tres prefijos

Toda variable comienza con un prefijo que indica de dónde viene el valor y cuánto tiempo dura:

Prefijo	Contiene	Duración
$campo	un campo del evento	persistido con el evento
@lista	una lista de valores de la cuenta	mantenida por la cuenta, entre eventos
%temporal	un valor calculado durante esta ejecución	solo existe durante la ejecución de la regla

Campos del evento ($)

Las variables son exactamente los campos del tipo de evento al que pertenece la regla. No existe una lista fija. Si el tipo de evento tiene un campo amount, la regla puede usar $amount; un tipo de evento diferente tendrá otro conjunto de variables.

Mientras usted escribe la condición, el panel ofrece los campos disponibles y resalta la expresión. Los campos que comienzan con _ están reservados por la plataforma y no quedan disponibles para su uso en expresiones.

Además de los campos del tipo de evento, $id contiene el identificador del evento informado en POST /events. La variable $id vale en las condiciones y como dimensión de un análisis.

El tipo del campo determina cómo se compara el valor:

Tipo del campo	Ejemplo de comparación
Texto	$status == "approved"
Entero	$installments > 6
Decimal	$amount >= 1500.00
Booleano	$is_first_purchase == true
Fecha y hora	$signup_at > "30 days ago"

Un campo que no vino en el evento se trata como vacío. Para probar esa ausencia, compárelo con null, sin comillas:

$device_fingerprint_id == null

La expresión anterior es verdadera cuando el evento no trajo fingerprint del dispositivo. Use != para el caso contrario.

Operaciones

Operación	Significado
==	Igualdad
!=	Desigualdad
>	Mayor que
>=	Mayor o igual
<	Menor que
<=	Menor o igual
in	Pertenece a una colección
not in	No pertenece a una colección
any in	Al menos uno de los valores pertenece a una colección
all in	Todos los valores pertenecen a una colección
=~	Corresponde a una expresión regular
!~	No corresponde a una expresión regular

Valores

El valor comparado con una variable puede ser un texto, un número o un booleano:

• Texto: siempre entre comillas dobles, como "XYZ". No se aceptan comillas simples ni textos sin comillas.
• Número: sin comillas, con punto como separador decimal, como 1000 o 99.01.
• Booleano: true o false, sin comillas.

Todo texto va entre comillas dobles. Una IP, una fecha o una palabra usada en la propia sintaxis (por ejemplo, in) también necesita las comillas para ser tratada como texto.

Fechas

Los campos de fecha y hora aceptan valores relativos y absolutos, siempre entre comillas:

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

El formato relativo es [número] [hour|day|week|month|year]s ago. El formato absoluto acepta año ("2026"), año y mes ("2026-03") o fecha completa ("2026-03-15"). Con año, o con año y mes, la comparación cubre todo el período.

Combinación de expresiones

Use and y or para combinar expresiones. and tiene precedencia sobre or: en una combinación sin paréntesis, la plataforma evalúa primero las partes unidas por and. Así, A and B or C equivale a (A and B) or C.

Use paréntesis para agrupar expresiones y alterar esa precedencia:

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

Un salto de línea funciona como un espacio entre los términos. Distribuya una combinación larga en varias líneas para facilitar la lectura, sin alterar el resultado:

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

true y false como condición entera

Una expresión puede consistir solo en true o false, sin variable ni comparación. true es siempre verdadera y mantiene la condición siempre activa. false es siempre falsa y desactiva la condición sin eliminarla. El uso difiere de la comparación de un campo booleano con true o false, descrita en Valores. En aquella comparación, el literal está a la derecha del operador; como condición entera, el literal constituye la expresión por completo.

Colecciones (@)

La plataforma ofrece las listas de la cuenta como colecciones, identificadas por el prefijo @. Por ejemplo, para verificar si un cliente está en una lista de cuarentena:

$user_id in @clientes_cuarentena

Escriba también la colección directamente en la expresión, entre corchetes y con los valores separados por coma:

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

Además del formato anterior, in y not in aceptan:

• un texto fijo a la izquierda, para probar un valor conocido contra una colección: "BR" in @paises_atendidos;
• un campo en ambos lados, para probar si el valor de un campo está contenido en el de otro: $user_id in $allowed_users.

Prueba de varios valores

Una colección escrita entre corchetes del lado izquierdo exige un cuantificador. La expresión declara cuántos de los valores necesitan pertenecer a la colección de la derecha:

Operación	Verdadera cuando
any in	al menos uno de los valores pertenece
all in	todos los valores pertenecen
not in	ninguno de los valores pertenece

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

No existe forma sin cuantificador. Escribir ["a", "b"] in @lista es un error de escritura. “A y B están en la lista” es ambiguo entre “al menos uno” y “los dos”, y una condición de riesgo no puede depender de cuál de las dos lecturas tenía en mente el autor. En la negación no hay ambigüedad, ya que “A y B no están en la lista” solo puede significar que ninguno de los dos está. Por eso not in no necesita cuantificador, y por el mismo motivo not any in y not all in no se aceptan.

La colección de la derecha puede ser una lista de la cuenta, una variable temporal de conjunto, un campo u otra colección literal.

Expresiones regulares

Los operadores =~ y !~ comparan un texto con una expresión regular. =~ es verdadera cuando el patrón aparece en el texto, y !~ cuando el patrón no aparece:

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

La primera expresión es verdadera cuando el ID del establecimiento comienza con m, mayúscula o minúscula.

El patrón sigue la sintaxis RE2:

• Coincidencia parcial: sin anclas, el patrón puede aparecer en cualquier posición del texto. ^ y $ anclan al inicio y al final del texto entero.
• Mayúsculas y minúsculas: la comparación las distingue. El prefijo (?i) elimina la distinción.
• Salto de línea: el . no corresponde a un salto de línea.
• Recursos ausentes: lookahead, lookbehind y referencias a grupos anteriores no se aceptan. Un patrón como a(?=b) se rechaza al guardar.

El patrón es un texto fijo entre comillas dobles, con hasta 256 caracteres. Un campo no ocupa el lugar del patrón. Una comilla doble dentro del patrón se escribe como \x22.

A la izquierda del operador, la expresión admite un campo de texto o de lista, una variable temporal de texto, un concat o un split. Los campos numéricos, booleanos y de fecha, así como los conjuntos, se rechazan al guardar.

Un valor ausente se trata como texto vacío. Así, $x !~ "foo" es verdadera cuando el evento no contiene el campo x.

Un texto de más de 4 KB no se compara, y la condición no se cumple, tanto con =~ como con !~. Las demás condiciones de la regla siguen normalmente. Un campo del evento tiene como máximo 1.024 bytes, por lo que solo un concat o una variable temporal alcanza ese tamaño.

Variables temporales (%)

Una variable temporal guarda un valor calculado durante la ejecución de la regla. Una acción produce la variable temporal y las condiciones siguientes leen el valor. La plataforma no graba la variable temporal en el evento, no la devuelve en la respuesta de la API y no la reaprovecha en el evento siguiente. Grabe en un campo el valor que necesite sobrevivir al evento.

Las variables temporales existen en dos formas.

Valores simples, definidos por una acción de definir variable temporal:

%revisao_manual == "1"

Resultados publicados por una acción productora, como ejecutar análisis o enriquecer, bajo el nombre del resultado, con claves accedidas por punto. La página de cada acción lista sus claves. El resultado de un análisis presenta las siguientes claves:

Clave	Contiene	Tipo
score	puntuación calculada por el análisis	Decimal
score_cell	nombre de la celda que originó la puntuación	Texto
triggered	si el análisis fue activado	Booleano
triggered_count	cuántas celdas fueron activadas	Entero
triggered_cells	nombres de las celdas activadas	Conjunto
version	versión del análisis ejecutada	Entero

%bot.triggered_count >= 2

La clave triggered_cells es un conjunto, no un valor único. Use triggered_cells solo a la derecha de una operación de pertenencia, para probar qué celdas fueron activadas.

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

Comparar el conjunto con ==, o usarlo en cualquier otra operación, es un error de escritura y la condición no se acepta. En una acción, la función join convierte el conjunto en texto.

Una acción en modo expresión también puede guardar un conjunto en una variable temporal simple. El valor sigue siendo un conjunto y se prueba de la misma forma.

Funciones

concat

La función concat une varios valores en un único texto, comparable con un valor. Cada argumento es un campo del evento ($campo), una variable temporal (%temporal) o un texto fijo, separados por coma:

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

La primera expresión es verdadera cuando la combinación del ID del usuario y el ID del establecimiento, unidos por un guion, resulta en "cliente-1234-loja-1234".

Consideraciones sobre los valores unidos:

• Una variable sin valor se trata como texto vacío.
• Un valor numérico se convierte a texto en su forma original (por ejemplo, 99.01 y 0.9).
• Un conjunto, como %bot.triggered_cells, no puede entrar en un concat. El conjunto se prueba con una operación de pertenencia o se convierte en texto con join.

El resultado de concat también acepta in y not in, para comparar la combinación con una lista:

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

split

La función split divide un texto por un separador y devuelve una de las partes. Los argumentos son el valor (un campo del evento o una variable temporal), el separador entre comillas dobles y la posición de la parte:

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

La expresión anterior es verdadera cuando la última parte del correo electrónico después de @, el dominio, es gmail.com.

Consideraciones sobre la división:

• La posición comienza en 0. Una posición negativa cuenta desde el final, y -1 es la última parte.
• El separador no puede estar vacío y puede tener más de un carácter.
• Un valor que no es texto se convierte a texto antes de la división. Un conjunto no se acepta.
• Las partes vacías cuentan. Dividido por "@", el texto "ana@" tiene "" en la posición -1.
• Una posición fuera del intervalo resulta en texto vacío en una condición. En una acción, no se graba nada.

El resultado de split es un texto y admite las mismas operaciones que un texto, incluidas in, not in y las expresiones regulares. Un split no entra en un concat, y un concat no entra en un split.

join

La función join convierte un conjunto en texto, con los elementos separados por el separador informado:

join(%bot.triggered_cells, ",")

El primer argumento es una variable temporal de conjunto, como %bot.triggered_cells. El segundo es el separador, entre comillas dobles.

La función join vale solo como el valor entero de una acción en modo expresión. Una condición no usa join, y un join no entra en un concat. Un conjunto vacío no graba nada.

Errores de escritura

La plataforma valida la expresión en el momento en que usted guarda la condición. El panel señala el problema y la regla no se publica mientras haya un error. Los casos más comunes:

• campo inexistente: la variable no corresponde a ningún campo del tipo de evento vinculado a la regla;
• tipo incompatible: el valor comparado no tiene sentido para el tipo del campo, como comparar un campo numérico con "aprobado";
• variable temporal desconocida: el nombre o el atributo no es producido por ninguna acción de la regla;
• variable temporal leída demasiado pronto: ninguna condición anterior la produce. Como las condiciones se evalúan en orden, el productor debe venir antes que el lector;
• texto sin comillas: los valores de texto necesitan comillas dobles.

Cada expresión tiene un límite de tamaño. Consulte límites y parámetros.