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 o $JWT por tu token Bearer, y https://tracer.sandbox.lerian.net por la URL de tu Tracer.

El modo de autenticación depende del despliegue. Un despliegue self-hosted con clave de API usa X-API-Key. En Lerian Cloud, usa Authorization: Bearer $JWT, que Access Manager emite con el claim tenantId, y 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.

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",
   "expression": "amount > 1000000",
   "action": "DENY",
   "scopes": [
     {
       "scheme": "CARD"
     }
   ]
 }'

{
  "ruleId": "019c96a0-4b20-7123-9a1b-2c3d4e5f6a7b",
  "name": "Block high-value transactions",
  "expression": "amount > 1000000",
  "action": "DENY",
  "scopes": [
    {
      "transactionType": "CARD",
      "scheme": "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",
  "expression": "amount > 1000000",
  "action": "DENY",
  "scopes": [
    {
      "transactionType": "CARD",
      "scheme": "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. El campo opcional resetTime empieza cada período a una hora del día UTC. El ejemplo empieza cada día a las 03:00 UTC.

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",
   "resetTime": "03:00",
   "scopes": [
     {
       "segmentId": "019c96a0-0b4e-7079-8be0-ab6bdccf975f",
       "scheme": "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",
      "scheme": "CARD"
    }
  ],
  "status": "DRAFT",
  "resetTime": "03:00",
  "resetAt": "2026-03-06T03: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 a su hora de reinicio (00:00 UTC de forma predeterminada)	Topes de gasto diarios
`WEEKLY`	Un conteo nuevo empieza cada lunes a su hora de reinicio (00:00 UTC de forma predeterminada)	Topes de gasto semanales
`MONTHLY`	Un conteo nuevo empieza el día 1 del mes a su hora de reinicio (00:00 UTC de forma predeterminada)	Control de presupuesto mensual
`CUSTOM`	Un solo conteo para todo el rango	Ventanas fijas de campaña o evento
`PER_TRANSACTION`	Tracer no mantiene ningún conteo y revisa cada transacción 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. Para decidir solo por las reglas, sin verificar ni contar ningún límite, envía la misma solicitud a POST /v1/validations/rules-only. Consulta Validación solo por reglas.

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",
   "scheme": "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",
  "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ó, se superó un límite o se aplicó el valor predeterminado sin coincidencia	Bloquear la transacción
`REVIEW`	Una regla de revisión coincidió, o una expresión de regla falló para la solicitud	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).

Esquemas de pago

Esquema	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

scheme acepta de 1 a 50 caracteres de A-Z, 0-9, _ y -, después de que Tracer elimina los espacios de los extremos y convierte el valor a mayúsculas. Los cuatro valores anteriores son ejemplos, no una lista cerrada. transactionType es el nombre obsoleto de scheme. Una solicitud de validación debe llevar uno de los dos. Si envías ambos, deben tener el mismo valor, o Tracer devuelve 0540. 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

Consulta cuánto del límite consumió el período actual. 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
}

currentUsage cubre aquí el período actual del límite, para el scope que más consumió. Incluye la capacidad que retienen las reservas no confirmadas del ledger de Midaz.

Paso 6: Revisa los eventos de auditoría

Tracer registra las decisiones de validación y los cambios de configuración 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.

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

Guía detallada de las expresiones CEL y la configuración avanzada de reglas.

Límites de gasto

Configura y administra límites por scope, período y esquema de pago.

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 Eventos de Auditoría

API de Dashboards

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

Esquemas de pago

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

​Esquemas de pago

​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

Esquemas de pago

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