Motor de reglas

Aprende a usar el motor de reglas de Tracer para construir lógica de validación dinámica basada en expresiones y aplicarla a transacciones en tiempo real.

El motor de reglas es lo que los equipos de riesgo y fraude usan para cambiar cómo las transacciones se aprueban o bloquean, sin tocar el código de la aplicación. Cada regla es una pequeña expresión que se ejecuta en cada transacción que Tracer valida — “bloquear este MCC para este segmento”, “enviar todo lo superior a R$ 50 mil a revisión manual”, “denegar si la cuenta está suspendida”.

Qué cambia en tu operación: los cambios en reglas se publican por un endpoint de API, no por una release. Un analista puede publicar una nueva regla en la mañana y verla evaluando transacciones reales en segundos. Cada coincidencia queda registrada, así una llamada de cliente reclamando seis meses después puede rastrearse hasta la regla exacta que disparó.

El trade-off honesto: tienes que pensar en CEL (Common Expression Language) en vez de Go, Python o Java. La curva es corta — la mayoría de las reglas tiene una línea — pero el equipo que las escribe ya no es el de aplicación. La contrapartida es cero despliegue, auditoría completa, y quien está más cerca de la política es dueño de ella.

¿Para quién es esta guía? Analistas de riesgo y fraude que van a escribir reglas, devs integrando la llamada de validación, y oficiales de cumplimiento leyendo el rastro de auditoría. Los ejemplos en CEL se ponen técnicos más adelante, pero el ciclo de vida y la lógica de decisión son útiles para cualquiera evaluando el producto.

El motor de reglas de Tracer evalúa lógica de validación escrita en — un lenguaje de expresiones con seguridad de tipos de Google. Las expresiones se compilan al crear la regla y se ejecutan en cada validación de transacción; el comportamiento se cambia actualizando las reglas vía API, sin redespliegue de código.

​

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
• Sin cortocircuito: las reglas coincidentes se evalúan juntas, así el rastro de auditoría registra las reglas que se dispararon, no solo la categoría ganadora
• 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

Figura 1. Flujo de evaluación del motor de reglas

En este flujo:

• Load rules obtiene todas las reglas activas desde la cache (o base de datos si no hay cache)
• Evaluate expressions ejecuta la expresión CEL de cada regla cuyo alcance coincide con la transacción
• Collect matches recopila todas las reglas que coincidieron y determina la decisión

​

Patrón de evaluación

Las reglas cuyo alcance coincide con la transacción se evalúan juntas. 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 (de mayor a menor):

1. DENY — cualquier regla DENY que coincida gana de inmediato.
2. Límite excedido — si ninguna regla DENY coincide pero algún límite aplicable es excedido, la decisión es DENY (la precedencia de las reglas aplica primero; los límites entran solo cuando ninguna DENY coincidió).
3. REVIEW — si ninguna regla DENY coincide y ningún límite es excedido, cualquier regla REVIEW que coincida gana.
4. ALLOW — si solo coinciden reglas ALLOW, la decisión es ALLOW.
5. Predeterminado — si ninguna regla coincide, Tracer devuelve el DEFAULT_DECISION_WHEN_NO_MATCH configurado (ALLOW, a menos que esté establecido explícitamente como DENY para despliegues fail-closed). Solo se aceptan ALLOW y DENY; REVIEW no es un valor válido como decisión por defecto, y cualquier otro valor hace fallar el servicio al arrancar.

matchedRuleIds en la respuesta contiene todas las reglas que coincidieron, independientemente de la categoría ganadora, para que los consumidores de auditoría vean todos los disparadores.

Por qué DENY le gana a REVIEW, y REVIEW le gana a ALLOW. La precedencia es fija y no configurable, a propósito: elimina la ambigüedad de “¿cuál regla DENY gana?” en runtime y vuelve trivial la auditoría — la respuesta siempre identifica la acción más estricta que disparó. El costo es que no puedes escribir “reglas ALLOW que sobrescriben DENYs”; si necesitas ese patrón, la respuesta correcta es volver la regla DENY más específica.

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

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. Tanto merchant.category como merchant["category"] son aceptados; los ejemplos en producción usan la notación con corchetes por convención. Si necesitas hacer match con una etiqueta textual como "gambling", guárdala en metadata y haz match por ahí.)

Las expresiones leen la solicitud de validación a través de diez variables. Para los tipos y formatos de campo detrás de cada una, consulta el schema ValidationRequest en la referencia de la API.

Variable	Tipo	Para qué típicamente sirve
amount	number	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.
transactionType	string	Uno de CARD, WIRE, PIX, CRYPTO.
subType	string	Texto libre, en minúsculas (ej., "international", "debit"). Cadena vacía cuando no se provee.
currency	string	Código ISO 4217 (ej., "BRL").
transactionTimestamp	int	Hora de la transacción en nanosegundos Unix. Divide por 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 pasa en el payload de la solicitud.

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

• account.status acepta active, suspended, closed, y account.type acepta checking, savings, credit.
• 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. Un campo que la solicitud omite llega a tu expresión como una cadena vacía, así que una condición que lo compara con un valor específico es falsa.
• segment.segmentId, portfolio.portfolioId, account.accountId y merchant.merchantId son cadenas UUID.

segmentId y portfolioId están en las variables de primer nivel segment y portfolio, no en account. Para filtrar por segmento, escribe segment.segmentId == "...", no account.segmentId == "...".

Una regla que lee un campo de contexto que la solicitud no carga no coincide, y las demás reglas siguen corriendo — así que no necesitas una guarda de presencia para ese caso. Cuando la presencia misma es la condición que buscas, escribe size(segment) > 0 o "risk_score" in metadata.

El costo de las expresiones está limitado por CEL_COST_LIMIT (predeterminado 10000). La comprobación corre en tiempo de compilación — al crear la regla, al actualizar la expresión y de nuevo al activarla —, no solo en la activación: una expresión cuyo costo estimado en el peor caso excede el límite se rechaza con el código de error 0342 (límite de costo excedido) la primera vez que la envías. Los errores de sintaxis aparecen como 0340, los errores de tipo (incluida una expresión que no devuelve un booleano) como 0341, y un fallo al estimar el costo como 0345.

​

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
segment.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

​

Reglas por horario

// Review late-night card transactions above BRL 5,000
transactionType == "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

​

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ón	Descripción
ALLOW	Permitir la transacción
DENY	Denegar la transacción
REVIEW	Enviar a revisión manual

​

Alcances

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

Dentro de un único objeto de alcance, los campos soportados son:

• 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.)

Semántica de coincidencia:

• Dentro de un objeto de alcance: los campos se combinan con AND. Un campo no especificado funciona como comodín (coincide con cualquier valor). Al menos un campo debe estar definido — objetos de alcance vacíos ({}) son rechazados con el código de error 0358.
• Entre múltiples objetos de alcance en 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 filtrando transactionType: CARD y otro filtrando transactionType: PIX — se ejecuta tanto para transacciones de tarjeta como para PIX. Un único alcance con segmentId Y accountId requiere que la transacción coincida con el segmento Y con la cuenta.

---

​

Ciclo de vida de las reglas

---

Las reglas progresan a través de un ciclo de vida definido para asegurar un despliegue seguro.

Figura 2. Ciclo de vida y transiciones del motor de reglas

​

Estados

Estado	Descripción
DRAFT	No se evalúa; la expresión puede modificarse libremente
ACTIVE	Se evalúa durante las validaciones; la expresión es inmutable
INACTIVE	No se evalúa; preservada para el rastro de auditoría; puede reactivarse. La expresión sigue siendo inmutable en este estado — para editarla, mueve la regla de vuelta a DRAFT vía POST /v1/rules/{id}/draft.
DELETED	Eliminada vía soft delete; no devuelta en listados y no puede recuperarse vía API, pero la fila se preserva en la base de datos para el rastro de auditoría.

​

Transiciones

Transición	Desde	Hacia	Descripción
activate	DRAFT, INACTIVE	ACTIVE	Iniciar evaluación (valida la expresión)
deactivate	ACTIVE	INACTIVE	Detener evaluación
draft	INACTIVE	DRAFT	Reeditar una regla previamente desactivada antes de reactivarla
delete	DRAFT, INACTIVE	DELETED	Eliminació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 descriptivo, único dentro de su contexto. El contexto se deriva de los alcances de la regla (el segmentId más bajo entre ellos); 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. La comparación ignora mayúsculas/minúsculas y los espacios repetidos; una colisión devuelve 409 Conflict con el código de error 0441. Tracer guarda el nombre en una forma normalizada, así que el name que devuelve puede diferir de la cadena que enviaste — referencia la regla por el ruleId de la respuesta.
• 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/{id}/activate	Iniciar evaluación de esta regla
Desactivar	POST /v1/rules/{id}/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
name	string	Filtrar por nombre (coincidencia parcial, case-insensitive)
status	string	Filtrar por estado (DRAFT, ACTIVE, INACTIVE). DELETED no es un valor válido para este filtro.
action	string	Filtrar por acción (ALLOW, DENY, REVIEW)
account_id	UUID	Filtrar por alcance: ID de la cuenta
segment_id	UUID	Filtrar por alcance: ID del segmento
portfolio_id	UUID	Filtrar por alcance: ID del portafolio
merchant_id	UUID	Filtrar por alcance: ID del comerciante
transaction_type	string	Filtrar por alcance: tipo de transacción (CARD, WIRE, PIX, CRYPTO)
sub_type	string	Filtrar por alcance: subtipo (ej.: debit, credit)
limit	integer	Elementos por página (predeterminado: 10, máx: 100)
cursor	string	Cursor de paginación de la respuesta anterior
sort_by	string	Campo de ordenamiento: created_at, updated_at, name, status (predeterminado: created_at)
sort_order	string	Dirección: ASC, DESC (predeterminado: DESC)

​

Obtener una regla específica

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

---

​

Actualizar una regla

---

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

El campo expression es inmutable en los estados ACTIVE e INACTIVE — desactivar la regla no basta. 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 cambios en la expresión. Después de editar, reactívala con POST /v1/rules/{id}/activate.

---

​

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/{id}
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 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 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
• Vuelve a DRAFT antes de editar la expresión - La expresión es inmutable en ACTIVE e INACTIVE; mueve la regla a DRAFT vía POST /v1/rules/{id}/draft para editar, después reactívala
• 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

Tropezones comunes al trabajar con reglas:

• “Edité la expresión pero el cambio no surtió efecto.” La expresión es inmutable en los estados ACTIVE e INACTIVE. Mueve la regla de vuelta a DRAFT vía POST /v1/rules/{id}/draft, edita y reactiva. INACTIVE solo no basta.
• “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 corres varias instancias detrás de un balanceador, las demás recogen el cambio en su siguiente sincronización de reglas (RULE_SYNC_POLL_INTERVAL_SECONDS, predeterminado 10). La desactivación se propaga igual. Planifica las pruebas de integración con esa brecha cuando las llamadas pueden caer en instancias distintas.
• “Quiero eliminar una regla ACTIVE.” No puedes — POST /v1/rules/{id}/deactivate primero, después DELETE /v1/rules/{id}. Esto fuerza un paso visible donde la regla deja de afectar el tráfico antes de desaparecer de los listados.
• “Mi alcance vacío {} está siendo rechazado con el código de error 0358.” Todo objeto de alcance necesita tener al menos un campo definido. Para correr una regla globalmente (contra cualquier transacción), omite el array scopes completo — no pases {}.

---

​

Referencia rápida

---

Endpoints, acciones e información de estados 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
Volver a borrador	POST	/v1/rules/{id}/draft

​

Estados

Estado	Evaluada	Editable	Puede eliminarse
DRAFT	No	Sí	Sí
ACTIVE	Sí	Parcial (expression inmutable)	No (desactivar primero)
INACTIVE	No	Parcial (expression inmutable; volver a DRAFT primero)	Sí
DELETED	No	No	N/A