Motor de reglas

El motor de reglas de Tracer te permite construir logica de validacion poderosa sin escribir codigo. Usando CEL (Common Expression Language)—un lenguaje de expresiones con seguridad de tipos desarrollado por Google—puedes crear reglas sofisticadas que se evaluan en menos de 1ms, automatizar decisiones de negocio complejas y adaptarte rapidamente a nuevos requisitos.

Por qué usar el motor de reglas

Flexibilidad: Crea y modifica reglas sin despliegues de código
Rendimiento: Las expresiones compiladas se evalúan en menos de 1ms cada una
Seguridad de tipos: Sintaxis de expresiones validada al crear la regla
Evaluación completa: Todas las reglas activas se evalúan para un rastro de auditoría completo
Basado en alcances: Aplica reglas a segmentos, cuentas o tipos de transacción específicos

Al final de esta guia, podras:

Comprender los conceptos del motor de reglas y el flujo de evaluacion
Crear y probar reglas basadas en expresiones
Gestionar el ciclo de vida de las reglas (DRAFT, ACTIVE, INACTIVE, DELETED)
Aplicar mejores practicas para la gestion de reglas

Que es el motor de reglas

El motor de reglas es el componente de Tracer responsable de evaluar expresiones durante la validacion de transacciones. Permite a los analistas de fraude y gestores de riesgo configurar logica de negocio que se ejecuta en tiempo real—sin requerir despliegues de codigo o soporte de ingenieria.

Como funciona

En este flujo:

Load rules obtiene todas las reglas activas desde la cache (o base de datos si no hay cache)
Evaluate expressions ejecuta todas las expresiones CEL contra el contexto de la transaccion
Collect matches recopila todas las reglas que coincidieron y determina la decision

Patron de evaluacion

Todas las reglas activas se evaluan contra cada transaccion. No hay ordenamiento por prioridad ni evaluacion de cortocircuito. Esto asegura:

Rastro de auditoria completo (todas las reglas coincidentes se registran)
Sin perdida de informacion (los analistas pueden ver todos los disparadores)
Logica simple (sin conflictos de prioridad)

Precedencia de decision:

Si cualquier regla DENY coincide, Tracer devuelve una decision DENY
Si solo reglas ALLOW coinciden, Tracer devuelve una decision ALLOW
Si ninguna regla coincide, se aplica el valor predeterminado configurado (tipicamente ALLOW para comportamiento fail-open)

Tracer devuelve decisiones; no bloquea transacciones directamente. Tu sistema recibe la decision y es responsable de tomar la accion apropiada (ej., bloquear, permitir, o enviar a revision).

Conceptos principales

Antes de crear reglas, comprende los elementos fundamentales.

Reglas

Una regla es una unidad de logica de negocio compuesta de:

Expression - Una expresion con seguridad de tipos que evalua a true o false
Action - Que decision devolver cuando la expresion es verdadera
Scopes - A que transacciones se aplica la regla
Status - El estado del ciclo de vida de la regla

Expresiones

Las expresiones se escriben en CEL (Common Expression Language), un lenguaje con seguridad de tipos que evalua el contexto de la transaccion y devuelve un valor booleano (true o false). CEL proporciona validacion en tiempo de compilacion, por lo que los errores de sintaxis se detectan cuando creas la regla—no cuando se estan procesando las transacciones. Ejemplos de expresiones:

amount > 10000

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

merchant.category == "gambling"

Las expresiones tienen acceso al contexto completo de la solicitud de validación incluyendo:

amount - Monto de la transacción en centavos (unidad más pequeña de la moneda)
transactionType - CARD, WIRE, PIX, CRYPTO
subType - Subtipo de transacción (ej.: debit, credit, international)
currency - Código de moneda ISO 4217
transactionTimestamp - Cuándo ocurrió la transacción
account - AccountId, segmentId, portfolioId
segment - SegmentId y metadatos del segmento
portfolio - PortfolioId y metadatos del portafolio
merchant - MerchantId, category, country, riskLevel (opcional)
metadata - Campos personalizados pasados en la solicitud

Ejemplos de expresiones por caso de uso

Aqui hay ejemplos practicos organizados por escenario de negocio:

Reglas basadas en monto

// Block transactions above a threshold
amount > 10000

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

// Review large cryptocurrency transactions
transactionType == "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
account.segmentId == "high-risk-segment-uuid" && amount > 5000

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

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

Usando metadata

// 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

Los campos de metadata son proporcionados por tu integracion. Disena tu payload para incluir el contexto que tus reglas necesitan.

Acciones

Las acciones determinan la decision cuando una expresion evalua a true:

Accion	Descripcion
`ALLOW`	Permitir la transaccion
`DENY`	Denegar la transaccion
`REVIEW`	Enviar a revision manual

Alcances

Los alcances definen a que transacciones se aplica una regla. Una regla solo se evalua contra transacciones que coinciden con al menos uno de sus alcances. Campos de alcance (todos opcionales):

segmentId - Coincidir transacciones de un segmento especifico
portfolioId - Coincidir transacciones de un portafolio especifico
accountId - Coincidir transacciones de una cuenta especifica
merchantId - Coincidir transacciones hacia un comercio especifico
transactionType - Coincidir tipos de transaccion especificos (CARD, WIRE, PIX, CRYPTO)
subType - Coincidir subtipos especificos (debit, credit, instant, etc.)

Si un campo de alcance no se especifica, coincide con cualquier valor para ese campo.

Ciclo de vida de las reglas

Las reglas progresan a traves de un ciclo de vida definido para asegurar un despliegue seguro.

Estados

Estado	Descripcion
`DRAFT`	No se evalua; la expresion puede modificarse libremente
`ACTIVE`	Se evalua durante las validaciones; la expresion es inmutable
`INACTIVE`	No se evalua; preservada para el rastro de auditoria; puede reactivarse
`DELETED`	Eliminada permanentemente; no aparece en listados; no puede recuperarse

Transiciones

Transicion	Desde	Hacia	Descripcion
`activate`	DRAFT, INACTIVE	ACTIVE	Iniciar evaluacion (valida la expresion)
`deactivate`	ACTIVE	INACTIVE	Detener evaluacion
`delete`	DRAFT, INACTIVE	DELETED	Eliminacion permanente (no se puede eliminar reglas ACTIVE)

Las reglas activas deben desactivarse antes de eliminarse. Esto previene la eliminacion accidental de reglas que se estan evaluando actualmente.

Crear una regla

Crea reglas usando POST /v1/rules. Las reglas se crean en estado DRAFT por defecto. Una regla requiere:

name: Un nombre único y descriptivo
expression: Una expresión CEL que evalúa a true o false
action: La decisión a devolver cuando la expresión coincide (ALLOW, DENY o REVIEW)
scopes (opcional): Limita a qué transacciones se aplica la regla

Para la estructura completa del payload y detalles de campos, consulta la Referencia de API.

Activar y desactivar reglas

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

Operación	Endpoint	Descripción
Activar	`POST /v1/rules/{ruleId}/activate`	Iniciar evaluación de esta regla
Desactivar	`POST /v1/rules/{ruleId}/deactivate`	Detener evaluación (preserva para auditoría)

Desactivar una regla la preserva para propósitos de auditoría. Usa eliminar solo cuando quieras remover permanentemente una regla.

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
`status`	string	Filtrar por estado (DRAFT, ACTIVE, INACTIVE)
`pageSize`	integer	Elementos por página (predeterminado: 100, máx: 1000)
`pageToken`	string	Token de paginación

Obtener una regla específica

Usa GET /v1/rules/{ruleId} para recuperar la definición completa de la regla incluyendo expresión y alcances.

Actualizar una regla

Actualiza reglas usando PATCH /v1/rules/{ruleId}. Las reglas pueden actualizarse en cualquier estado, con una restricción importante:

El campo expression no puede actualizarse mientras una regla está ACTIVE. Desactiva la regla primero para modificar su expresión.

Eliminar una regla

Elimina las reglas que ya no se necesitan. Solo las reglas DRAFT e INACTIVE pueden eliminarse. Las reglas ACTIVE deben desactivarse primero.

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

Respuesta: 204 No Content

La eliminacion es permanente. Las reglas eliminadas no pueden recuperarse y no aparecen en ningun listado.

Mejores practicas

Sigue estas practicas para reglas efectivas y mantenibles.

Nomenclatura

Usa nombres descriptivos - El nombre debe indicar claramente que hace la regla
Incluye contexto - Menciona el escenario o tipo de transaccion
Evita abreviaturas - Prefiere claridad sobre brevedad

Menos claro	Mas 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`

Diseno de expresiones

Manten las expresiones simples - La logica compleja es mas dificil de mantener
Usa alcances para filtrar - No repitas condiciones de alcance en las expresiones
Prueba casos limite - Considera valores limites y campos nulos

Gestion del ciclo de vida

Comienza en DRAFT - Prueba antes de activar
Desactiva antes de editar - Nunca edites reglas activas
Archiva reglas no usadas - Mantiene el rastro de auditoria intacto
Elimina solo cuando estes seguro - La eliminacion es permanente

Monitoreo

Revisa las reglas coincidentes - Verifica que reglas se estan disparando
Monitorea las tasas de DENY - Tasas altas de denegacion pueden indicar reglas demasiado agresivas
Audita regularmente - Asegura que las reglas sigan alineadas con los requisitos de negocio

Referencia rápida

Endpoints, acciones e información de estados clave.

Endpoints

Operacion	Metodo	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`

Acciones

Accion	Descripcion
`ALLOW`	Permitir la transaccion
`DENY`	Denegar la transaccion
`REVIEW`	Enviar a revision manual

Estados

Estado	Evaluada	Editable	Puede eliminarse
`DRAFT`	No	Si	Si
`ACTIVE`	Si	Parcial (expression inmutable)	No (desactivar primero)
`INACTIVE`	No	Si	Si
`DELETED`	No	No	N/A

​Por qué usar el motor de reglas

​Que es el motor de reglas

​Como funciona

​Patron de evaluacion

​Conceptos principales

​Reglas

​Expresiones

​Ejemplos de expresiones por caso de uso

​Reglas basadas en monto

​Reglas basadas en comercio

​Reglas basadas en cuenta

​Condiciones combinadas

​Usando metadata

​Acciones

​Alcances

​Ciclo de vida de las reglas

​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 practicas

​Nomenclatura

​Diseno de expresiones

​Gestion del ciclo de vida

​Monitoreo

​Referencia rápida

​Endpoints

​Acciones

​Estados

Por qué usar el motor de reglas

Que es el motor de reglas

Como funciona

Patron de evaluacion

Conceptos principales

Reglas

Expresiones

Ejemplos de expresiones por caso de uso

Reglas basadas en monto

Reglas basadas en comercio

Reglas basadas en cuenta

Condiciones combinadas

Usando metadata

Acciones

Alcances

Ciclo de vida de las reglas

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 practicas

Nomenclatura

Diseno de expresiones

Gestion del ciclo de vida

Monitoreo

Referencia rápida

Endpoints

Acciones

Estados