Motor de reglas

El motor de reglas es lo que los equipos de riesgo y fraude usan para cambiar cómo Tracer aprueba o bloquea transacciones, sin tocar el código de la aplicación. Qué cambia en tu operación: los cambios de reglas se publican a través de un endpoint de la API, no de un release. Un analista puede publicar una regla nueva en la mañana y verla evaluando transacciones reales en cuestión de segundos. Tracer registra cada coincidencia, así que puedes rastrear la llamada de un cliente denegado seis meses después hasta la regla exacta que se activó. Contrapartida: tienes que pensar en CEL (Common Expression Language) en lugar de Go, Python o Java. La curva de aprendizaje es corta (la mayoría de las reglas son de una línea), pero el equipo que las escribe ya no son tus desarrolladores de aplicación. La ventaja es que no hay despliegues, hay auditoría completa, y las personas más cercanas a la política son dueñas de la política.

Esta guía es para analistas de riesgo y fraude que van a escribir reglas, desarrolladores que integran la llamada de validación, y oficiales de cumplimiento que leen el registro de auditoría. Los ejemplos de CEL se vuelven técnicos más adelante, pero el ciclo de vida y la lógica de decisión son útiles para cualquiera que esté evaluando el producto.

El motor de reglas de Tracer evalúa lógica de validación escrita en , un lenguaje de expresiones con tipado seguro de Google. Tracer compila las expresiones al crear la regla y las ejecuta durante cada validación de transacción. Cambias el comportamiento actualizando reglas a través de la API, sin volver a desplegar código.

Por qué usar el motor de reglas

Flexibilidad: crea y modifica reglas sin despliegues de código
Modelo de ejecución: Tracer evalúa expresiones compiladas durante la validación
Seguridad de tipos: la sintaxis de la expresión se valida al crear la regla
Sin cortocircuito: Tracer evalúa juntas las reglas que coinciden, así que el registro de auditoría guarda las reglas que se activaron, sin importar la categoría ganadora
Basado en alcance: aplica reglas a segmentos, cuentas o esquemas de pago específicos

Al final de esta guía, podrás:

Entender los conceptos del motor de reglas y el flujo de evaluación
Crear y probar reglas basadas en expresiones
Gestionar el ciclo de vida de la regla (DRAFT, ACTIVE, INACTIVE, DELETED)
Aplicar buenas prácticas para la gestión de reglas

Qué es el motor de reglas

El motor de reglas es el componente de Tracer responsable de evaluar expresiones durante la validación de transacciones. Permite a los analistas de fraude y a los gerentes de riesgo configurar lógica de negocio que se ejecuta en tiempo real, sin requerir despliegues de código ni soporte de ingeniería.

Cómo funciona

Cómo el motor de reglas evalúa las expresiones configuradas contra el contexto de la transacción durante la validación y devuelve una decisión — Figura 1. Flujo de evaluación del motor de reglas

En este flujo:

Cargar reglas obtiene reglas activas desde la caché
Evaluar expresiones ejecuta la expresión CEL de cada regla cuyo alcance coincide con la transacción, hasta MAX_RULES_PER_REQUEST reglas
Recolectar coincidencias reúne todas las reglas que coincidieron y determina la decisión

Patrón de evaluación

Precedencia de decisión (de mayor a menor):

DENY: cualquier regla DENY que coincida gana de forma definitiva.
Límite excedido: si ninguna regla DENY coincidió pero la transacción excede algún límite aplicable, la decisión es DENY. La precedencia de reglas se aplica primero, y los límites entran en juego solo cuando ninguna regla DENY coincidió.
REVIEW: si ninguna regla DENY coincidió y la transacción no excedió ningún límite, cualquier regla REVIEW que coincida gana. Una regla cuya expresión falla para la solicitud también da REVIEW, con el motivo rule_evaluation_error. En cambio, una clave ausente no da coincidencia.
ALLOW: si solo coincidieron reglas ALLOW, la decisión es ALLOW.
Predeterminado: si ninguna regla coincidió, la validación devuelve la DEFAULT_DECISION_WHEN_NO_MATCH configurada (ALLOW, a menos que se configure explícitamente como DENY). Tracer acepta solo ALLOW y DENY. REVIEW deliberadamente no es un valor predeterminado válido para “sin coincidencia”, y cualquier otro valor hace fallar el servicio al iniciar.

Cuando el ledger de Midaz reserva una transacción, Tracer ejecuta las mismas reglas con una entrada más pequeña. Consulta Reglas en una reserva.

Por qué DENY le gana a REVIEW y REVIEW le gana a ALLOW. La precedencia nunca cambia y no puedes configurarla, a propósito. Elimina la ambigüedad de “¿qué regla DENY gana?” en tiempo de ejecución y hace que la auditoría sea trivial. La respuesta siempre identifica la acción más estricta que se activó. El costo es que no puedes escribir “reglas ALLOW que anulan DENYs”. Si necesitas ese patrón, la respuesta correcta es hacer la regla DENY más específica en su lugar.

Tracer devuelve decisiones. No bloquea transacciones directamente. Tu sistema recibe la decisión y debe tomar la acción correspondiente (por ejemplo, bloquear, permitir o poner en cola para revisión).

Conceptos centrales

Antes de crear reglas, entiende los elementos fundamentales.

Reglas

Una regla es una unidad de lógica de negocio compuesta por:

Expresión - una expresión con tipado seguro que se evalúa como verdadera o falsa
Acción - qué decisión devolver cuando la expresión es verdadera
Alcances - a qué transacciones aplica la regla
Estado - el estado del ciclo de vida de la regla

Expresiones

Escribes las expresiones en CEL (Common Expression Language), un lenguaje con tipado seguro que evalúa el contexto de la transacción y devuelve un valor booleano (verdadero o falso). CEL ofrece validación en tiempo de compilación, así que los errores de sintaxis aparecen cuando creas la regla, no cuando Tracer procesa transacciones. Ejemplos de expresiones:

amount > 10000

segment.segmentId == "high-risk-segment-uuid" && amount > 5000

merchant["category"] == "7995"

(merchant.category es el código MCC ISO 18245 de 4 dígitos. "7995" es el MCC de apuestas/casino. Tracer acepta tanto merchant.category como merchant["category"]. Los ejemplos de producción usan la notación de corchetes por convención. Si necesitas hacer coincidir una etiqueta de texto como "gambling", guárdala en metadata y haz coincidir sobre eso en su lugar.) Las expresiones leen la solicitud de validación a través de once variables. Para conocer los tipos y formatos de campo detrás de cada una, consulta el esquema ValidationRequest en la referencia de la API.

Variable	Tipo	Con qué se suele comparar
`amount`	número	El valor de la transacción, en las mismas unidades que envías en la solicitud: `"1500.00"` llega a la expresión como `1500`. El rango seguro es `±2^53`.
`scheme`	string	El esquema de pago, en mayúsculas (por ejemplo, `"PIX"`). Cadena vacía cuando la solicitud no trae ninguno.
`transactionType`	string	El nombre obsoleto de `scheme`, con el mismo valor.
`subType`	string	Texto libre, en minúsculas (por ejemplo, `"international"`, `"debit"`). Cadena vacía cuando no se proporciona.
`asset`	string	De 1 a 100 letras mayúsculas (por ejemplo, `"BRL"`).
`transactionTimestamp`	int	Hora de la transacción en nanosegundos Unix. Divide entre `1000000000` para obtener segundos.
`account`	map	`accountId`, `type`, `status`, `metadata`.
`segment`	map	`segmentId`, `name`, `metadata`.
`portfolio`	map	`portfolioId`, `name`, `metadata`.
`merchant`	map	`merchantId`, `name`, `category`, `country`, `metadata`.
`metadata`	map	Campos personalizados que tu integración envía en el payload de la solicitud.

Valores de campo que conviene conocer antes de escribir una condición:

account.status y account.type son texto libre, de hasta 50 y 256 caracteres. Tu expresión los recibe tal como los envías.
merchant.category toma un código MCC ISO 18245 de 4 dígitos. merchant.country toma un código ISO 3166-1 alpha-2.
Esos cuatro campos son opcionales en la solicitud. Una condición que compara un campo omitido contra un valor específico no se cumple.
segment.segmentId, portfolio.portfolioId, account.accountId y merchant.merchantId son cadenas UUID.

segmentId y portfolioId viven en las variables de nivel superior segment y portfolio, no en account. Para comparar por segmento, escribe segment.segmentId == "...", no account.segmentId == "...".Cuando la presencia en sí es la condición que quieres, escribe size(segment) > 0 o "risk_score" in metadata.

Tracer limita el costo de las expresiones con CEL_COST_LIMIT (predeterminado 10000). La verificación se ejecuta en tiempo de compilación (al crear, al actualizar la expresión, y de nuevo al activar), no solo en la activación. Tracer rechaza una expresión cuyo costo estimado en el peor caso supere el límite, la primera vez que la envías, con el código de error 0342 (límite de costo excedido). Los errores de sintaxis aparecen como 0340, los errores de tipo (incluida una expresión que no devuelve un booleano) como 0341, y una falla al estimar el costo como 0345.

Ejemplos de expresiones por caso de uso

Estos son ejemplos prácticos por escenario de negocio:

Reglas basadas en monto

// Block transactions above a threshold
amount > 10000

// Block high-value international transfers
scheme == "WIRE" && subType == "international" && amount > 50000

// Review large cryptocurrency transactions
scheme == "CRYPTO" && amount > 5000

Reglas basadas en comercio

// Block gambling merchants
merchant.category == "7995"

// Block high-risk merchant categories
merchant.category in ["7995", "5967", "5966"]

// Review transactions from new merchant countries
merchant.country != "BR" && amount > 1000

Reglas basadas en cuenta

// Block suspended accounts
account.status == "suspended"

// Review transactions from newly created accounts
metadata.accountAgeDays < 30 && amount > 500

// Block closed accounts
account.status == "closed"

Condiciones combinadas

// High-value transaction from high-risk segment
segment.segmentId == "high-risk-segment-uuid" && amount > 5000

// International Pix above threshold
scheme == "PIX" && subType == "international" && amount > 10000

// Large card transaction to foreign merchant
scheme == "CARD" && merchant.country != "BR" && amount > 3000

Reglas basadas en tiempo

// Review late-night card transactions above BRL 5,000
scheme == "CARD" && amount > 5000 && timestamp(transactionTimestamp / 1000000000).getHours("UTC") >= 22

// Review weekend transactions above BRL 10,000
timestamp(transactionTimestamp / 1000000000).getDayOfWeek("UTC") in [0, 6] && amount > 10000

Uso de metadatos

// Block transactions from untrusted devices
metadata.deviceTrust == "untrusted"

// Review first-time purchases above threshold
metadata.isFirstPurchase == true && amount > 1000

// Block transactions outside business hours (using metadata)
metadata.isBusinessHours == false && amount > 5000

// VIP customers bypass certain restrictions
metadata.customerTier == "vip" && amount < 50000

Tu integración proporciona los campos de metadatos. Diseña tu payload para incluir el contexto que tus reglas necesitan.

Acciones

Las acciones determinan la decisión cuando una expresión se evalúa como verdadera:

Acción	Descripción
`ALLOW`	Permite la transacción
`DENY`	Deniega la transacción
`REVIEW`	Envía a revisión manual

Alcances

Los alcances definen a qué transacciones aplica una regla. Una regla sin scopes es global y se evalúa contra cada transacción. Una regla con uno o más objetos de alcance se evalúa solo cuando la transacción coincide con al menos uno de ellos (semántica OR entre objetos de alcance). Dentro de un solo objeto de alcance, los campos admitidos son:

segmentId - hace coincidir transacciones de un segmento específico
portfolioId - hace coincidir transacciones de un portafolio específico
accountId - hace coincidir transacciones de una cuenta específica
merchantId - hace coincidir transacciones hacia un comercio específico
scheme - hace coincidir un esquema de pago, como CARD o PIX. transactionType es el nombre obsoleto de este campo
subType - hace coincidir subtipos específicos (debit, credit, instant, etc.)

Semántica de coincidencia:

Dentro de un objeto de alcance: los campos se combinan con AND. Un campo que dejas fuera funciona como comodín (coincide con cualquier valor). Debes establecer al menos un campo. Tracer rechaza objetos de alcance vacíos ({}) con el código de error 0358.
Entre varios objetos de alcance de la misma regla: se combinan con OR. La regla coincide si cualquier objeto de alcance coincide con la transacción.

Por ejemplo, una regla con dos alcances (uno que apunta a scheme: CARD y otro que apunta a scheme: PIX) se ejecuta tanto para transacciones de tarjeta como de Pix. Un solo alcance con segmentId Y accountId requiere que la transacción coincida con el segmento Y con la cuenta.

Ciclo de vida de la regla

Las reglas avanzan por un ciclo de vida definido para garantizar un despliegue seguro.

Ciclo de vida de reglas y límites en Tracer, que muestra las transiciones de estado por las que pasa una definición desde su creación hasta su aplicación activa — Figura 2. Ciclo de vida de reglas y transiciones de estado

Estados

Estado	Descripción
`DRAFT`	No se evalúa; la expresión se puede modificar libremente
`ACTIVE`	Se evalúa durante las validaciones; la expresión es inmutable
`INACTIVE`	No se evalúa; se conserva para el registro de auditoría; se puede reactivar. La expresión sigue siendo inmutable en este estado. Para editarla, mueve la regla de vuelta a DRAFT mediante `POST /v1/rules/{id}/draft`.
`DELETED`	Eliminación suave; no aparece en los listados y no se puede recuperar a través de la API, pero la fila se conserva en la base de datos para el registro de auditoría.

Transiciones

Transición	Desde	Hacia	Descripción
`activate`	DRAFT, INACTIVE	ACTIVE	Inicia la evaluación (valida la expresión)
`deactivate`	ACTIVE	INACTIVE	Detiene la evaluación
`draft`	INACTIVE	DRAFT	Vuelve a editar una regla previamente desactivada antes de reactivarla
`delete`	DRAFT, INACTIVE	DELETED	Eliminación permanente (no se pueden eliminar reglas ACTIVE)

Debes desactivar las reglas activas antes de eliminarlas. Esto evita la eliminación accidental de reglas que Tracer todavía evalúa.

Crear una regla

Crea reglas usando POST /v1/rules. Tracer crea las reglas en estado DRAFT por defecto. Una regla requiere:

name: un nombre descriptivo, único dentro de su contexto. Los alcances de la regla determinan el contexto (el segmentId más bajo entre ellos), y las reglas sin alcance comparten un único contexto global. Así, el mismo nombre de regla puede coexistir en dos segmentos distintos, pero no dos veces dentro de uno solo. La comparación distingue mayúsculas de minúsculas y conserva los espacios en blanco internos, y Tracer recorta los espacios en blanco al inicio y al final antes de almacenar. Una colisión responde 409 Conflict con el código de error 0441. Referencia la regla por el ruleId de la respuesta.
expression: una expresión CEL que se evalúa como verdadera o falsa
action: la decisión que se devuelve cuando la expresión coincide (ALLOW, DENY o REVIEW)
scopes (opcional): limita a qué transacciones aplica la regla

Para la estructura completa del payload y el detalle de los campos, consulta la referencia de la API.

Activar y desactivar reglas

Después de crear una regla, actívala para empezar a evaluarla. Desactiva reglas para detener la evaluación sin eliminarlas.

Operación	Endpoint	Descripción
Activar	`POST /v1/rules/{id}/activate`	Empieza a evaluar esta regla
Desactivar	`POST /v1/rules/{id}/deactivate`	Detiene la evaluación (se conserva para auditoría)

Desactivar una regla la conserva con fines de auditoría. Usa la eliminación solo cuando quieras remover una regla de forma permanente.

Listar y consultar reglas

Consulta reglas para gestión y auditoría usando GET /v1/rules.

Parámetros de consulta

Parámetro	Tipo	Descripción
`name`	string	Filtra por nombre (coincidencia parcial sin distinguir mayúsculas y minúsculas)
`status`	string	Filtra por estado (DRAFT, ACTIVE, INACTIVE). `DELETED` no es un valor de filtro válido.
`action`	string	Filtra por acción (ALLOW, DENY, REVIEW)
`account_id`	UUID	Filtra por alcance: id de cuenta
`segment_id`	UUID	Filtra por alcance: id de segmento
`portfolio_id`	UUID	Filtra por alcance: id de portafolio
`merchant_id`	UUID	Filtra por alcance: id de comercio
`scheme`	string	Filtra por alcance: esquema de pago, como `CARD` o `PIX`. `transaction_type` es el nombre obsoleto de este filtro
`sub_type`	string	Filtra por alcance: subtipo (por ejemplo, debit, credit)
`limit`	integer	Elementos por página (predeterminado: 10, máximo: 100)
`cursor`	string	Cursor de paginación de la respuesta anterior
`sort_by`	string	Campo de orden: `created_at`, `updated_at`, `name`, `status` (predeterminado: `created_at`)
`sort_order`	string	Dirección de orden: `ASC`, `DESC` (predeterminado: `DESC`)

Obtener una regla específica

Usa GET /v1/rules/{id} para recuperar la definición completa de la regla, incluida la expresión y los alcances.

Actualizar una regla

Actualiza una regla con PATCH /v1/rules/{id}. Una regla en estado DRAFT, ACTIVE o INACTIVE acepta cambios en su nombre, descripción, acción y alcances. La expresión tiene una restricción:

El campo expression es inmutable en los estados ACTIVE e INACTIVE. Desactivar una regla no es suficiente. Para editar una expresión, mueve la regla de ACTIVE → INACTIVE (POST /v1/rules/{id}/deactivate), y luego de INACTIVE → DRAFT (POST /v1/rules/{id}/draft). Solo las reglas DRAFT aceptan actualizaciones de expresión. Una vez editada, reactívala con POST /v1/rules/{id}/activate.

Eliminar una regla

Elimina las reglas que ya no necesites. Solo puedes eliminar reglas DRAFT e INACTIVE. Desactiva primero las reglas ACTIVE.

DELETE /v1/rules/{id}
X-API-Key: {api_key}

La eliminación es permanente. No puedes recuperar reglas eliminadas, y no aparecen en ningún listado.

Mejores prácticas

Sigue estas prácticas para reglas efectivas y fáciles de mantener.

Nomenclatura

Usa nombres descriptivos - el nombre debe indicar claramente qué hace la regla
Incluye contexto - menciona el escenario o el tipo de transacción
Evita abreviaturas - prefiere la claridad sobre la brevedad

Menos claro	Más claro
`Rule 1`	`Block night transactions above BRL 5,000`
`Block high`	`Deny high-value weekend transactions`
`Pix rule`	`Review Pix transfers to new recipients`

Diseño de la expresión

Mantén las expresiones simples - la lógica compleja es más difícil de mantener
Usa alcances para filtrar - no repitas condiciones de alcance dentro de las expresiones
Prueba casos límite - considera valores frontera y campos nulos

Gestión del ciclo de vida

Empieza en DRAFT - prueba antes de activar
Vuelve a DRAFT antes de editar la expresión - la expresión es inmutable en ACTIVE e INACTIVE. Mueve la regla a DRAFT mediante POST /v1/rules/{id}/draft para editarla, y luego reactívala
Archiva las reglas sin uso - mantén intacto el registro de auditoría
Elimina solo cuando estés seguro - la eliminación es permanente

Monitoreo

Revisa las reglas que coincidieron - verifica cuáles reglas se activan
Monitorea las tasas de DENY - tasas de denegación altas pueden indicar reglas demasiado agresivas
Audita con regularidad - verifica que las reglas sigan alineadas con los requisitos de negocio

Errores comunes al trabajar con reglas:

“Edité la expresión pero el cambio no se aplicó.” La expresión es inmutable en los estados ACTIVE e INACTIVE. Mueve la regla de vuelta a DRAFT mediante POST /v1/rules/{id}/draft, edítala y luego reactívala. INACTIVE por sí solo no es suficiente.
“Mi regla está ACTIVE pero otra instancia de Tracer todavía no la está evaluando.” La activación surte efecto de inmediato en la instancia que atendió la llamada de activación. Cuando ejecutas varias instancias detrás de un balanceador de carga, las demás toman el cambio en su siguiente sincronización de reglas (RULE_SYNC_POLL_INTERVAL_SECONDS, predeterminado 10). La desactivación se propaga de la misma manera. Planea las pruebas de integración en torno a esa brecha cuando las llamadas puedan caer en instancias distintas.
“Quiero eliminar una regla ACTIVE.” No puedes. Llama primero a POST /v1/rules/{id}/deactivate, y luego a DELETE /v1/rules/{id}. Esto obliga a un paso visible donde la regla deja de afectar el tráfico antes de desaparecer de los listados.
“Mi alcance vacío {} se rechaza con el código de error 0358.” Cada objeto de alcance debe tener al menos un campo establecido. Para ejecutar una regla de forma global (contra cada transacción), omite por completo el arreglo scopes. No envíes {}.

Referencia rápida

Endpoints, acciones e información de estado clave.

Endpoints

Operación	Método	Endpoint
Crear regla	POST	`/v1/rules`
Listar reglas	GET	`/v1/rules`
Obtener regla	GET	`/v1/rules/{id}`
Actualizar regla	PATCH	`/v1/rules/{id}`
Eliminar regla	DELETE	`/v1/rules/{id}`
Activar regla	POST	`/v1/rules/{id}/activate`
Desactivar regla	POST	`/v1/rules/{id}/deactivate`
Poner regla en borrador	POST	`/v1/rules/{id}/draft`

Estados

Estado	Se evalúa	Editable	Se puede eliminar
`DRAFT`	No	Sí	Sí
`ACTIVE`	Sí	Parcial (expresión inmutable)	No (desactivar primero)
`INACTIVE`	No	Parcial (expresión inmutable; volver a DRAFT primero)	Sí
`DELETED`	No	No	N/A

Resumen

Guías

Console

Operaciones

Motor de reglas

Por qué usar el motor de reglas

Qué es el motor de reglas

Cómo funciona

Patrón de evaluación

Conceptos centrales

Reglas

Expresiones

Ejemplos de expresiones por caso de uso

Reglas basadas en monto

Reglas basadas en comercio

Reglas basadas en cuenta

Condiciones combinadas

Reglas basadas en tiempo

Uso de metadatos

Acciones

Alcances

Ciclo de vida de la regla

Estados

Transiciones

Crear una regla

Activar y desactivar reglas

Listar y consultar reglas

Parámetros de consulta

Obtener una regla específica

Actualizar una regla

Eliminar una regla

Mejores prácticas

Nomenclatura

Diseño de la expresión

Gestión del ciclo de vida

Monitoreo

Referencia rápida

Endpoints

Estados

​Por qué usar el motor de reglas

​Qué es el motor de reglas

​Cómo funciona

​Patrón de evaluación

​Conceptos centrales

​Reglas

​Expresiones

​Ejemplos de expresiones por caso de uso

​Reglas basadas en monto

​Reglas basadas en comercio

​Reglas basadas en cuenta

​Condiciones combinadas

​Reglas basadas en tiempo

​Uso de metadatos

​Acciones

​Alcances

​Ciclo de vida de la regla

​Estados

​Transiciones

​Crear una regla

​Activar y desactivar reglas

​Listar y consultar reglas

​Parámetros de consulta

​Obtener una regla específica

​Actualizar una regla

​Eliminar una regla

​Mejores prácticas

​Nomenclatura

​Diseño de la expresión

​Gestión del ciclo de vida

​Monitoreo

​Referencia rápida

​Endpoints

​Estados

Por qué usar el motor de reglas

Qué es el motor de reglas

Cómo funciona

Patrón de evaluación

Conceptos centrales

Reglas

Expresiones

Ejemplos de expresiones por caso de uso

Reglas basadas en monto

Reglas basadas en comercio

Reglas basadas en cuenta

Condiciones combinadas

Reglas basadas en tiempo

Uso de metadatos

Acciones

Alcances

Ciclo de vida de la regla

Estados

Transiciones

Crear una regla

Activar y desactivar reglas

Listar y consultar reglas

Parámetros de consulta

Obtener una regla específica

Actualizar una regla

Eliminar una regla

Mejores prácticas

Nomenclatura

Diseño de la expresión

Gestión del ciclo de vida

Monitoreo

Referencia rápida

Endpoints

Estados