> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Motor de reglas
> Escribe expresiones CEL en el motor de reglas de Tracer para dar forma a las decisiones ALLOW, DENY y REVIEW en tiempo real, y gestiona el ciclo de vida de DRAFT a ACTIVE.
export const GMetadata = ({children}) =>
{children}
;
export const GCEL = ({children}) =>
{children}
;
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. Cada regla es una expresión pequeña que se ejecuta en cada transacción que Tracer valida: "bloquear este MCC para este segmento", "enviar a revisión manual todo lo que supere R\$ 50k", "denegar si la cuenta está suspendida".
**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ó.
**Compromiso que hay que reconocer:** 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.
**¿Para quién es esta guía?** 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 CEL (Common Expression Language), 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, no solo la categoría ganadora
* **Basado en alcance**: aplica reglas a segmentos, cuentas o tipos de transacción 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
En este flujo:
* **Cargar reglas** obtiene todas las reglas activas desde la caché (o desde la base de datos si falla la caché)
* **Evaluar expresiones** ejecuta la expresión CEL de cada regla cuyo alcance coincide con la transacción
* **Recolectar coincidencias** reúne todas las reglas que coincidieron y determina la decisión
### Patrón de evaluación
Tracer evalúa juntas todas las reglas cuyo alcance coincide con la transacción. No hay orden de prioridad ni evaluación por cortocircuito. Esto garantiza:
* Registro de auditoría completo (se registran todas las reglas que coinciden)
* 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 forma definitiva.
2. **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ó.
3. **REVIEW**: si ninguna regla DENY coincidió y la transacción no excedió ningún límite, cualquier regla `REVIEW` que coincida gana.
4. **ALLOW**: si solo coincidieron reglas `ALLOW`, la decisión es ALLOW.
5. **Predeterminado**: si ninguna regla coincidió, Tracer devuelve la `DEFAULT_DECISION_WHEN_NO_MATCH` configurada (`ALLOW`, a menos que se configure explícitamente como `DENY` para despliegues de fallo cerrado). 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.
`matchedRuleIds` en la respuesta contiene cada regla que coincidió, sin importar la categoría ganadora, así que los consumidores de auditoría pueden ver todos los disparadores.
**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 diez variables. Para conocer los tipos y formatos de campo detrás de cada una, consulta el esquema [ValidationRequest](/es/reference/products/tracer/validate-transaction) 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`. |
| `transactionType` | string | Uno de `CARD`, `WIRE`, `PIX`, `CRYPTO`. |
| `subType` | string | Texto libre, en minúsculas (por ejemplo, `"international"`, `"debit"`). Cadena vacía cuando no se proporciona. |
| `asset` | string | Código ISO 4217 (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` 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 contra un valor específico da falso.
* `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 == "..."`.
Una regla que lee un campo de contexto que la solicitud no trae no coincide, y las demás reglas se siguen ejecutando, así que no necesitas una guarda de presencia para ese caso. 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
```cel theme={null}
// 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
```cel theme={null}
// 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
```cel theme={null}
// 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
```cel theme={null}
// 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 basadas en tiempo
```cel theme={null}
// 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
```
#### Uso de metadatos
```cel theme={null}
// 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
* `transactionType` - hace coincidir tipos de transacción específicos (CARD, WIRE, PIX, CRYPTO)
* `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 `transactionType: CARD` y otro que apunta a `transactionType: 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.
### 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](/es/reference/products/tracer/create-rule).
***
## 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 |
| `transaction_type` | string | Filtra por alcance: tipo de transacción (CARD, WIRE, PIX, CRYPTO) |
| `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 reglas usando `PATCH /v1/rules/{id}`. Las reglas aceptan actualizaciones en cualquier estado, con una restricción importante:
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.
```http theme={null}
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** - asegúrate de 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 |