Inicio rápido de la API de Tracer

Esta guía es para desarrolladores. Si buscas un resumen de negocio de lo que hace Tracer, consulta ¿Qué es Tracer?.

Esta guía te lleva desde la creación de tu primera regla y límite de gasto hasta la validación de una transacción y la revisión del registro de auditoría.

Antes de empezar

Necesitas:

Una instancia de Tracer en ejecución
Credenciales para uno de los dos modos de autenticación admitidos

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

El modo de autenticación depende del despliegue. Los despliegues single-tenant usan X-API-Key. Los despliegues multi-tenant (SaaS / BYOC Multi-Tenant) usan Authorization: Bearer $JWT, que Access Manager emite con el claim tenantId. En el 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, así que nunca pases el identificador del tenant en ningún otro campo. Consulta Multi-tenancy para conocer el modelo.

Paso 1: Crea una regla

Crea una regla de validación con una expresión CEL. Toda regla nueva empieza en estado DRAFT. No afectan las transacciones hasta que las activas.

Referencia de la API: Crear regla

cURL

curl -X POST "https://tracer.sandbox.lerian.net/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 los contadores de uso) aparecen como cadenas decimales, por ejemplo "1500.00" o "10000.00".

Paso 2: Activa la regla

Activa la regla. Tracer la evalúa entonces contra las transacciones entrantes.

Referencia de la API: Activar regla

cURL

curl -X POST "https://tracer.sandbox.lerian.net/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 la regla

Estado	Comportamiento
`DRAFT`	Creada pero no evaluada durante las validaciones
`ACTIVE`	Evaluada durante la validación, en las transacciones que coinciden con su scope
`INACTIVE`	Pausada y excluida de la evaluación

Las reglas INACTIVE pueden volver a DRAFT para editarse de nuevo mediante POST /v1/rules/{id}/draft.

Paso 3: Crea un límite de gasto

Crea un límite de gasto para controlar los montos de las transacciones por scope y período. Igual que las reglas, los límites empiezan en estado DRAFT.

Referencia de la API: Crear límite

cURL

curl -X POST "https://tracer.sandbox.lerian.net/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",
   "asset": "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",
  "asset": "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ímite

Tipo	Conteo del período	Caso de uso
`DAILY`	Un conteo nuevo empieza cada día calendario a las 00:00 UTC	Topes de gasto diarios
`WEEKLY`	Un conteo nuevo empieza cada semana ISO, el lunes a las 00:00 UTC	Topes de gasto semanales
`MONTHLY`	Un conteo nuevo empieza el día 1 del mes a las 00:00 UTC	Control de presupuesto mensual
`CUSTOM`	Un solo conteo para todo el rango	Ventanas fijas de campaña o evento
`PER_TRANSACTION`	No se mantiene ningún conteo; cada transacción se revisa por separado	Máximos por transacción

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

cURL

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

Paso 4: Valida una transacción

Envía una transacción a Tracer para su validación en tiempo real contra las reglas y los límites que le corresponden.

Referencia de la API: Validar transacción

cURL

curl -X POST "https://tracer.sandbox.lerian.net/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",
   "asset": "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	Qué debe hacer tu sistema
`ALLOW`	Todas las reglas se cumplieron, todos los límites dentro del umbral	Continuar con la transacción
`DENY`	Una regla de denegación coincidió o se superó un límite	Bloquear la transacción
`REVIEW`	Una regla de revisión coincidió, ninguna regla de denegación se activó	Enviar a revisión manual

Tracer devuelve las decisiones como recomendaciones. Tu sistema debe actuar sobre la decisión (bloquear, aprobar o poner en cola la transacción).

Tipos de transacción

Tipo	Subtipos de ejemplo	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 con criptomonedas

transactionType acepta solo los cuatro valores anteriores. subType es una cadena libre (hasta 50 caracteres, normalizada a minúsculas). Los subtipos indicados son ejemplos comunes, no una lista cerrada.

Paso 5: Consulta el uso del límite

Revisa el consumo acumulado de un límite. Para el consumo detrás de una decisión puntual, lee limitUsageDetails en la respuesta de POST /v1/validations.

Referencia de la API: Consultar uso de límite

cURL

curl -X GET "https://tracer.sandbox.lerian.net/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"
}

currentUsage suma aquí los contadores de uso registrados para el límite, entre períodos y scopes.

Paso 6: Revisa los eventos de auditoría

Cada decisión de validación y cada cambio de configuración quedan registrados en un log de auditoría inmutable. Consulta los eventos de auditoría para elaborar informes de cumplimiento y depurar.

Referencia de la API: Listar eventos de auditoría

cURL

curl -X GET "https://tracer.sandbox.lerian.net/v1/audit-events?event_type=TRANSACTION_VALIDATED&start_date=2026-03-05T00:00:00Z&end_date=2026-03-06T00:00:00Z" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: $API_KEY"

Tipos de evento de auditoría

Tipo de evento	Descripción
`TRANSACTION_VALIDATED`	Se validó una transacción
`RULE_CREATED`	Se creó una regla nueva
`RULE_ACTIVATED`	Se activó una regla
`RULE_DEACTIVATED`	Se desactivó una regla
`LIMIT_CREATED`	Se creó un límite nuevo
`LIMIT_ACTIVATED`	Se activó un límite
`LIMIT_DEACTIVATED`	Se desactivó un límite

Esta tabla muestra los tipos de evento más comunes. Para la lista completa (incluidos los eventos de actualización, eliminación, borrador y del ciclo de vida de reservas), consulta Auditoría y cumplimiento.

Paso 7: Verifica la integridad de la auditoría

Verifica la cadena de hash criptográfica de los eventos de auditoría para confirmar que ningún registro se alteró. Esto es indispensable para el cumplimiento de SOX y GLBA.

Referencia de la API: Verificar evento de auditoría

cURL

curl -X GET "https://tracer.sandbox.lerian.net/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

Resumen de negocio del ciclo de vida de la validación y los conceptos principales.

Motor de reglas

Profundiza en las expresiones CEL y la configuración avanzada de reglas.

Límites de gasto

Configura y administra límites por scope, período y tipo de transacción.

Gestión de errores

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

Primeros pasos

API de Validaciones

API de Reglas

API de Límites

API de Reservas

API de Eventos de Auditoría

Manejo de errores

Eventos

Inicio rápido de la API de Tracer

Antes de empezar

Paso 1: Crea una regla

Paso 2: Activa la regla

Ciclo de vida de la regla

Paso 3: Crea un límite de gasto

Tipos de límite

Paso 4: Valida una transacción

Tipos de decisión

Tipos de transacción

Paso 5: Consulta el uso del límite

Paso 6: Revisa los eventos de auditoría

Tipos de evento de auditoría

Paso 7: Verifica la integridad de la auditoría

Próximos pasos

Primeros pasos con Tracer

Motor de reglas

Límites de gasto

Gestión de errores

​Antes de empezar

​Paso 1: Crea una regla

​Paso 2: Activa la regla

​Ciclo de vida de la regla

​Paso 3: Crea un límite de gasto

​Tipos de límite

​Paso 4: Valida una transacción

​Tipos de decisión

​Tipos de transacción

​Paso 5: Consulta el uso del límite

​Paso 6: Revisa los eventos de auditoría

​Tipos de evento de auditoría

​Paso 7: Verifica la integridad de la auditoría

​Próximos pasos

Primeros pasos con Tracer

Motor de reglas

Límites de gasto

Gestión de errores

Antes de empezar

Paso 1: Crea una regla

Paso 2: Activa la regla

Ciclo de vida de la regla

Paso 3: Crea un límite de gasto

Tipos de límite

Paso 4: Valida una transacción

Tipos de decisión

Tipos de transacción

Paso 5: Consulta el uso del límite

Paso 6: Revisa los eventos de auditoría

Tipos de evento de auditoría

Paso 7: Verifica la integridad de la auditoría

Próximos pasos