Saltar al contenido principal
El motor de reglas de Tracer te permite construir lógica de validación poderosa sin escribir código. Usando CEL (Common Expression Language)—un lenguaje de expresiones con seguridad de tipos desarrollado por Google—puedes crear reglas sofisticadas que se evalúan en menos de 1ms, automatizar decisiones de negocio complejas y adaptarte rápidamente 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 guía, podrás:
  • Comprender 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 las reglas (DRAFT, ACTIVE, INACTIVE, DELETED)
  • Aplicar mejores 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 gestores de riesgo configurar lógica de negocio que se ejecuta en tiempo real—sin requerir despliegues de código o soporte de ingeniería.

​
Cómo 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 transacción
  • Collect matches recopila todas las reglas que coincidieron y determina la decisión

​
Patrón de evaluación

Todas las reglas activas se evalúan contra cada transacción. No hay ordenamiento por prioridad ni evaluación de cortocircuito. Esto asegura:
  • Rastro de auditoría completo (todas las reglas coincidentes se registran)
  • Sin pérdida de información (los analistas pueden ver todos los disparadores)
  • Lógica simple (sin conflictos de prioridad)
Precedencia de decisión:
  • Si cualquier regla DENY coincide, Tracer devuelve una decisión DENY
  • Si solo reglas ALLOW coinciden, Tracer devuelve una decisión ALLOW
  • Si ninguna regla coincide, se aplica el valor predeterminado configurado (típicamente ALLOW para comportamiento fail-open)
Tracer devuelve decisiones; no bloquea transacciones directamente. Tu sistema recibe la decisión y es responsable de tomar la acción apropiada (ej., bloquear, permitir, o enviar a revisión).

​
Conceptos principales

Antes de crear reglas, comprende los elementos fundamentales.

​
Reglas

Una regla es una unidad de lógica de negocio compuesta de:
  • Expression - Una expresión con seguridad de tipos que evalúa a true o false
  • Action - Qué decisión devolver cuando la expresión 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 evalúa el contexto de la transacción y devuelve un valor booleano (true o false). CEL proporciona validación en tiempo de compilación, por lo que los errores de sintaxis se detectan cuando creas la regla—no cuando se están 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

Aquí hay ejemplos prácticos 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 integración. Diseña tu payload para incluir el contexto que tus reglas necesitan.

​
Acciones

Las acciones determinan la decisión cuando una expresión evalúa a true:
AcciónDescripción
ALLOWPermitir la transacción
DENYDenegar la transacción
REVIEWEnviar a revisión manual

​
Alcances

Los alcances definen a qué transacciones se aplica una regla. Una regla solo se evalúa contra transacciones que coinciden con al menos uno de sus alcances. Campos de alcance (todos opcionales):
  • segmentId - Coincidir transacciones de un segmento específico
  • portfolioId - Coincidir transacciones de un portafolio específico
  • accountId - Coincidir transacciones de una cuenta específica
  • merchantId - Coincidir transacciones hacia un comercio específico
  • transactionType - Coincidir tipos de transacción específicos (CARD, WIRE, PIX, CRYPTO)
  • subType - Coincidir subtipos específicos (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 través de un ciclo de vida definido para asegurar un despliegue seguro.

​
Estados

EstadoDescripción
DRAFTNo se evalúa; la expresión puede modificarse libremente
ACTIVESe evalúa durante las validaciones; la expresión es inmutable
INACTIVENo se evalúa; preservada para el rastro de auditoría; puede reactivarse
DELETEDEliminada permanentemente; no aparece en listados; no puede recuperarse

​
Transiciones

TransiciónDesdeHaciaDescripción
activateDRAFT, INACTIVEACTIVEIniciar evaluación (valida la expresión)
deactivateACTIVEINACTIVEDetener evaluación
deleteDRAFT, INACTIVEDELETEDEliminación permanente (no se puede eliminar reglas ACTIVE)
Las reglas activas deben desactivarse antes de eliminarse. Esto previene la eliminación accidental de reglas que se están 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ónEndpointDescripción
ActivarPOST /v1/rules/{ruleId}/activateIniciar evaluación de esta regla
DesactivarPOST /v1/rules/{ruleId}/deactivateDetener 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ámetroTipoDescripción
statusstringFiltrar por estado (DRAFT, ACTIVE, INACTIVE)
pageSizeintegerElementos por página (predeterminado: 100, máx: 1000)
pageTokenstringToken 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 eliminación es permanente. Las reglas eliminadas no pueden recuperarse y no aparecen en ningún listado.

​
Mejores prácticas

Sigue estas prácticas para reglas efectivas y mantenibles.

​
Nomenclatura

  • Usa nombres descriptivos - El nombre debe indicar claramente qué hace la regla
  • Incluye contexto - Menciona el escenario o tipo de transacción
  • Evita abreviaturas - Prefiere claridad sobre brevedad
Menos claroMás claro
Rule 1Block night transactions above BRL 5,000
Block highDeny high-value weekend transactions
PIX ruleReview PIX transfers to new recipients

​
Diseño de expresiones

  • 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 en las expresiones
  • Prueba casos límite - Considera valores límites y campos nulos

​
Gestión 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 auditoría intacto
  • Elimina solo cuando estés seguro - La eliminación es permanente

​
Monitoreo

  • Revisa las reglas coincidentes - Verifica qué reglas se están disparando
  • Monitorea las tasas de DENY - Tasas altas de denegación 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

OperaciónMétodoEndpoint
Crear reglaPOST/v1/rules
Listar reglasGET/v1/rules
Obtener reglaGET/v1/rules/{id}
Actualizar reglaPATCH/v1/rules/{id}
Eliminar reglaDELETE/v1/rules/{id}
Activar reglaPOST/v1/rules/{id}/activate
Desactivar reglaPOST/v1/rules/{id}/deactivate

​
Acciones

AcciónDescripción
ALLOWPermitir la transacción
DENYDenegar la transacción
REVIEWEnviar a revisión manual

​
Estados

EstadoEvaluadaEditablePuede eliminarse
DRAFTNoSíSí
ACTIVESíParcial (expression inmutable)No (desactivar primero)
INACTIVENoSíSí
DELETEDNoNoN/A