Inicio rápido de la API de Tracer

Esta guía está dirigida a desarrolladores. Si buscas una visión general a nivel de negocio de lo que hace Tracer, consulta ¿Qué es Tracer?.

Pon Tracer en funcionamiento en minutos. Esta guía te lleva por el recorrido completo, desde crear tu primera regla y límite de gasto hasta validar una transacción y revisar la auditoría.

Antes de comenzar

Necesitas:

Una instancia de Tracer en funcionamiento
Credenciales para uno de los dos modos de autenticación soportados

Todos los ejemplos usan cURL. Reemplaza $API_KEY con tu clave de API (single-tenant) o $JWT con tu token Bearer (multi-tenant), y https://tracer.lerian.io con tu URL de Tracer.

El modo de auth depende del despliegue. Los despliegues single-tenant usan X-API-Key. Los despliegues multi-tenant (SaaS / BYOC Multi-Tenant) usan Authorization: Bearer <jwt> — el JWT es emitido por Access Manager y lleva el claim tenantId. En modo multi-tenant, reemplaza cada -H "X-API-Key: $API_KEY" de esta guía por -H "Authorization: Bearer $JWT". Tracer resuelve el tenant a partir del token automáticamente — nunca pases el identificador del tenant en ningún otro campo. Consulta Multi-tenancy para el modelo.

Paso 1: Crear una regla

Crea una regla de validación con una expresión CEL. Las reglas siempre se crean en estado DRAFT — no afectan transacciones hasta que las actives.

Referencia de API: Crear regla

cURL

curl -X POST "https://tracer.lerian.io/v1/rules" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: $API_KEY" \
 -d '{
   "name": "Block high-value transactions",
   "description": "Deny transactions above BRL 10,000 for card payments",
   "expression": "amount > 1000000",
   "action": "DENY",
   "scopes": [
     {
       "transactionType": "CARD"
     }
   ]
 }'

{
  "ruleId": "019c96a0-4b20-7123-9a1b-2c3d4e5f6a7b",
  "name": "Block high-value transactions",
  "description": "Deny transactions above BRL 10,000 for card payments",
  "expression": "amount > 1000000",
  "action": "DENY",
  "scopes": [
    {
      "transactionType": "CARD"
    }
  ],
  "status": "DRAFT",
  "createdAt": "2026-03-05T10:00:00Z",
  "updatedAt": "2026-03-05T10:00:00Z"
}

Guarda el ruleId. Lo usarás para activar la regla.

Los valores monetarios (amount de la transacción, maxAmount del límite de gasto y contadores de uso) se expresan como cadenas decimales, por ejemplo "1500.00" o "10000.00".

Paso 2: Activar la regla

Activa la regla para que sea evaluada contra las transacciones entrantes.

Referencia de API: Activar regla

cURL

curl -X POST "https://tracer.lerian.io/v1/rules/019c96a0-4b20-7123-9a1b-2c3d4e5f6a7b/activate" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: $API_KEY"

{
  "ruleId": "019c96a0-4b20-7123-9a1b-2c3d4e5f6a7b",
  "name": "Block high-value transactions",
  "description": "Deny transactions above BRL 10,000 for card payments",
  "expression": "amount > 1000000",
  "action": "DENY",
  "scopes": [
    {
      "transactionType": "CARD"
    }
  ],
  "status": "ACTIVE",
  "createdAt": "2026-03-05T10:00:00Z",
  "updatedAt": "2026-03-05T10:01:00Z"
}

El estado de la regla cambia de DRAFT a ACTIVE.

Ciclo de vida de reglas

Estado	Comportamiento
`DRAFT`	Creada pero no evaluada durante las validaciones
`ACTIVE`	Evaluada contra cada transacción entrante
`INACTIVE`	Pausada y excluida de la evaluación

Las reglas INACTIVE pueden volver a DRAFT para reedición usando POST /v1/rules/{id}/draft.

Paso 3: Crear un límite de gasto

Crea un límite de gasto para controlar montos de transacciones por alcance y período de tiempo. Al igual que las reglas, los límites comienzan en estado DRAFT.

Referencia de API: Crear límite

cURL

curl -X POST "https://tracer.lerian.io/v1/limits" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: $API_KEY" \
 -d '{
   "name": "Daily Corporate Limit",
   "description": "Daily spending limit for corporate segment",
   "limitType": "DAILY",
   "maxAmount": "50000.00",
   "currency": "BRL",
   "scopes": [
     {
       "segmentId": "019c96a0-0b4e-7079-8be0-ab6bdccf975f",
       "transactionType": "CARD"
     }
   ]
 }'

{
  "limitId": "019c96a0-4a10-7dfe-b5c1-8a1b2c3d4e5f",
  "name": "Daily Corporate Limit",
  "description": "Daily spending limit for corporate segment",
  "limitType": "DAILY",
  "maxAmount": "50000.00",
  "currency": "BRL",
  "scopes": [
    {
      "segmentId": "019c96a0-0b4e-7079-8be0-ab6bdccf975f",
      "transactionType": "CARD"
    }
  ],
  "status": "DRAFT",
  "resetAt": "2026-03-06T00:00:00Z",
  "createdAt": "2026-03-05T10:02:00Z",
  "updatedAt": "2026-03-05T10:02:00Z"
}

Tipos de límites

Tipo	Comportamiento de reinicio	Caso de uso
`DAILY`	Se reinicia a medianoche UTC	Topes de gasto diarios
`MONTHLY`	Se reinicia el 1° de cada mes	Control de presupuesto mensual
`PER_TRANSACTION`	Sin rastreo — evaluado por transacción	Máximos por transacción individual

Activa el límite de la misma forma que activaste la regla:

cURL

curl -X POST "https://tracer.lerian.io/v1/limits/019c96a0-4a10-7dfe-b5c1-8a1b2c3d4e5f/activate" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: $API_KEY"

Paso 4: Validar una transacción

Envía una transacción a Tracer para validación en tiempo real contra todas las reglas y límites activos. Tracer no realiza llamadas externas durante la evaluación, por lo que los tiempos de respuesta se mantienen por debajo de 80ms (p99).

Referencia de API: Validar transacción

cURL

curl -X POST "https://tracer.lerian.io/v1/validations" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: $API_KEY" \
 -d '{
   "requestId": "019c96a0-10ce-75fc-a273-dc799079a99c",
   "transactionType": "CARD",
   "subType": "debit",
   "amount": "1500.00",
   "currency": "BRL",
   "transactionTimestamp": "2026-03-05T10:30:00Z",
   "account": {
     "accountId": "019c96a0-0c0c-7221-8cf3-13313fb60081",
     "type": "checking",
     "status": "active"
   },
   "segment": {
     "segmentId": "019c96a0-0b4e-7079-8be0-ab6bdccf975f",
     "name": "corporate"
   },
   "metadata": {
     "channel": "MOBILE_APP"
   }
 }'

{
  "requestId": "019c96a0-10ce-75fc-a273-dc799079a99c",
  "validationId": "019c96a0-4a10-7dfe-b5c1-8a1b2c3d4e5f",
  "decision": "ALLOW",
  "reason": "Transaction approved",
  "matchedRuleIds": [],
  "evaluatedRuleIds": [
    "019c96a0-4b20-7123-9a1b-2c3d4e5f6a7b"
  ],
  "limitUsageDetails": [
    {
      "limitId": "019c96a0-4a10-7dfe-b5c1-8a1b2c3d4e5f",
      "limitAmount": "50000.00",
      "currentUsage": "1500.00",
      "exceeded": false,
      "period": "DAILY"
    }
  ],
  "processingTimeMs": 23
}

Tipos de decisión

Decisión	Significado	Tu sistema debe
`ALLOW`	Todas las reglas pasaron, todos los límites dentro del umbral	Proceder con la transacción
`DENY`	Una regla deny coincidió o un límite fue excedido	Bloquear la transacción
`REVIEW`	Una regla review coincidió, ninguna regla deny activada	Enviar a revisión manual

Tracer devuelve decisiones como recomendaciones. Tu sistema es responsable de actuar sobre la decisión (bloquear, aprobar o encolar la transacción).

Tipos de transacción

Tipo	Subtipos	Descripción
`CARD`	debit, credit, prepaid	Transacciones con tarjeta
`WIRE`	domestic, international, ach	Transferencias bancarias
`PIX`	instant, scheduled	Pagos instantáneos brasileños
`CRYPTO`	bitcoin, ethereum, stablecoin	Transacciones de criptomonedas

Paso 5: Consultar uso de límites

Monitorea cuánto de un límite de gasto ha sido consumido en el período actual.

Referencia de API: Obtener uso del límite

cURL

curl -X GET "https://tracer.lerian.io/v1/limits/019c96a0-4a10-7dfe-b5c1-8a1b2c3d4e5f/usage" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: $API_KEY"

{
  "limitId": "019c96a0-4a10-7dfe-b5c1-8a1b2c3d4e5f",
  "limitAmount": "50000.00",
  "currentUsage": "15000.00",
  "utilizationPercent": 30.0,
  "nearLimit": false,
  "resetAt": "2026-03-06T00:00:00Z"
}

El flag nearLimit se activa al 80% de utilización, permitiendo la gestión proactiva de límites.

Paso 6: Revisar eventos de auditoría

Cada decisión de validación y cambio de configuración se registra en un log de auditoría inmutable. Consulta los eventos de auditoría para reportes de cumplimiento y depuración.

Referencia de API: Listar eventos de auditoría

cURL

curl -X GET "https://tracer.lerian.io/v1/audit-events?eventType=TRANSACTION_VALIDATED&startDate=2026-03-05T00:00:00Z&endDate=2026-03-06T00:00:00Z" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: $API_KEY"

Tipos de eventos de auditoría

Tipo de evento	Descripción
`TRANSACTION_VALIDATED`	Una transacción fue validada
`RULE_CREATED`	Una nueva regla fue creada
`RULE_ACTIVATED`	Una regla fue activada
`RULE_DEACTIVATED`	Una regla fue desactivada
`LIMIT_CREATED`	Un nuevo límite fue creado
`LIMIT_ACTIVATED`	Un límite fue activado
`LIMIT_DEACTIVATED`	Un límite fue desactivado

Paso 7: Verificar integridad de auditoría

Verifica la cadena de hash criptográfica de los eventos de auditoría para confirmar que ningún registro ha sido alterado. Esto es esencial para el cumplimiento de SOX y GLBA.

Referencia de API: Verificar evento de auditoría

cURL

curl -X GET "https://tracer.lerian.io/v1/audit-events/019c96a0-4a10-7dfe-b5c1-8a1b2c3d4e5f/verify" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: $API_KEY"

{
  "isValid": true,
  "totalChecked": 1234,
  "message": "Hash chain integrity verified successfully"
}

Próximos pasos

Primeros pasos con Tracer

Descripción general del ciclo de vida de validación y conceptos clave.

Motor de reglas

Profundización en expresiones CEL y configuración avanzada de reglas.

Límites de gasto

Configura y gestiona límites por alcance, período y tipo de transacción.

Manejo de errores

Lista completa de códigos de error y cómo resolverlos.

​Antes de comenzar

​Paso 1: Crear una regla

​Paso 2: Activar la regla

​Ciclo de vida de reglas

​Paso 3: Crear un límite de gasto

​Tipos de límites

​Paso 4: Validar una transacción

​Tipos de decisión

​Tipos de transacción

​Paso 5: Consultar uso de límites

​Paso 6: Revisar eventos de auditoría

​Tipos de eventos de auditoría

​Paso 7: Verificar integridad de auditoría

​Próximos pasos

Primeros pasos con Tracer

Motor de reglas

Límites de gasto

Manejo de errores

Antes de comenzar

Paso 1: Crear una regla

Paso 2: Activar la regla

Ciclo de vida de reglas

Paso 3: Crear un límite de gasto

Tipos de límites

Paso 4: Validar una transacción

Tipos de decisión

Tipos de transacción

Paso 5: Consultar uso de límites

Paso 6: Revisar eventos de auditoría

Tipos de eventos de auditoría

Paso 7: Verificar integridad de auditoría

Próximos pasos