Primeros pasos con Tracer

Tracer es la capa que tu sistema de autorización o de onboarding llama antes de que una transacción se procese. Ejecuta tus políticas de fraude, riesgo y límites en milisegundos y devuelve ALLOW, DENY o REVIEW. La decisión vive entonces en un solo lugar en lugar de dispersa en el código de producto. Lo que cambia en tu operación: la lógica de decisión deja de vivir en sentencias if dispersas entre servicios. Los cambios de reglas se publican a través de una API el mismo día en lugar de en la próxima versión. El historial de validación te da un solo lugar para investigar por qué una transacción recibió su decisión. Trade-off: agregas una llamada HTTP al camino crítico de cada transacción. La meta es p99 por debajo de 80 ms. A cambio, obtienes un punto único para las políticas y el historial de decisiones, y eliminas lógica duplicada del código de producto.

¿Para quién es esta guía? Para desarrolladores (junior o senior) que integran Tracer por primera vez. Si estás evaluando Tracer en el nivel de producto o de estrategia, empieza con Qué es Tracer. Si ya lo tienes en ejecución y necesitas la mecánica de la API, ve directo a Inicio rápido de la API de Tracer.

Esta guía te lleva paso a paso por la configuración de Tracer y la ejecución de tu primera validación. En pocos pasos, tendrás un entorno funcional listo para validar transacciones en tiempo real. Para instrucciones paso a paso de la API con ejemplos de solicitud y respuesta, consulta Inicio rápido de la API de Tracer.

Por qué usar Tracer

Validación en tiempo real: toma decisiones ALLOW/DENY/REVIEW en menos de 80 ms (p99)
Reglas flexibles: motor de reglas basado en expresiones para lógica de negocio personalizada
Control de gasto: configura límites por cuenta, portafolio, segmento y período
Historial de validación: decisiones almacenadas para investigación y generación de informes
Agnóstico de producto: valida transacciones de cualquier esquema de pago, como CARD, WIRE, PIX o CRYPTO

Al final de esta guía, habrás:

Entendido la arquitectura y los conceptos principales de Tracer
Preparado un entorno de desarrollo funcional
Ejecutado tu primera validación de transacción
Configurado un límite de gasto

Qué es Tracer

Tracer es una plataforma de validación de transacciones que evalúa reglas y límites y devuelve decisiones instantáneas. Tu sistema llama a Tracer antes de ejecutar una transacción. Luego actúa sobre la decisión (ALLOW, DENY o REVIEW) según tu lógica de negocio.

Cómo funciona

Cómo Tracer procesa una solicitud de validación a través de sus contextos de Validation, Rules y Limits, y devuelve una decisión ALLOW, DENY o REVIEW — Figura 1. Cómo funciona Tracer

En este flujo:

Rules evalúa expresiones contra el contexto de la transacción
Limits verifica los umbrales de gasto para los alcances aplicables
Decision devuelve ALLOW, DENY o REVIEW según los resultados de la evaluación

Contextos principales

Tracer tiene tres contextos delimitados:

Contexto de Validation - orquesta las solicitudes, coordina la evaluación y almacena el historial de validación
Contexto de Rules - administra las definiciones de reglas y la evaluación de expresiones
Contexto de Limits - administra los límites de gasto y el seguimiento de uso

Requisitos previos

Antes de empezar, confirma que tienes:

Docker instalado
PostgreSQL 17, con una base de datos para Tracer (tracer en los ejemplos de abajo)
API Key para autenticación

Dependencias de infraestructura

Tracer requiere los siguientes componentes:

Componente	Versión	Propósito
PostgreSQL	17	Persistencia de datos. Tracer usa su propia base de datos `tracer` en el primario compartido de PostgreSQL de Midaz; no incluye una instancia dedicada.

Puertos

Puertos predeterminados usados por los servicios de Tracer:

Servicio	Puerto	Descripción
Tracer API	4020	API REST principal
Seam de reservas	4021	Servicio gRPC al que llama el ledger de Midaz para reservar capacidad de límite

Paso 1: ejecuta Tracer

Tracer se distribuye como dos imágenes públicas en Docker Hub. Usa la misma etiqueta para ambas:

Imagen	Función
`lerianstudio/midaz-tracer-migrations`	Aplica el esquema de Tracer en la base de datos y termina
`lerianstudio/midaz-tracer`	Ejecuta la API de Tracer

Los ejemplos usan la etiqueta 4.4.0. Tracer no aplica migraciones al iniciar, así que ejecuta primero la imagen de migración.

Aplica el esquema

docker run --rm \
  -e DB_HOST="your-postgres-host" \
  -e DB_PORT="5432" \
  -e DB_USER="your-postgres-user" \
  -e DB_PASSWORD="your-postgres-password" \
  -e DB_NAME="tracer" \
  -e DB_SSL_MODE="disable" \
  lerianstudio/midaz-tracer-migrations:4.4.0

El contenedor termina con estado 0 cuando el esquema está actualizado. Puedes ejecutarlo de nuevo sin riesgo.

Inicia Tracer

docker run -d --name midaz-tracer \
  -p 4020:4020 \
  -e SERVER_ADDRESS=":4020" \
  -e DB_HOST="your-postgres-host" \
  -e DB_PORT="5432" \
  -e DB_USER="your-postgres-user" \
  -e DB_PASSWORD="your-postgres-password" \
  -e DB_NAME="tracer" \
  -e DB_SSL_MODE="disable" \
  -e ALLOW_INSECURE_TLS="true" \
  -e API_KEY_ENABLED="true" \
  -e API_KEY="your-secure-api-key" \
  lerianstudio/midaz-tracer:4.4.0

DB_SSL_MODE="disable" y ALLOW_INSECURE_TLS="true" sirven para un PostgreSQL local sin TLS. En producción, define DB_SSL_MODE como require o más estricto y deja ALLOW_INSECURE_TLS sin definir.

Variables de entorno esenciales

Variable	Descripción	Ejemplo
`SERVER_ADDRESS`	Dirección de escucha de la API	`:4020`
`DB_HOST`	Host de PostgreSQL	`your-postgres-host`
`DB_NAME`	Nombre de la base de datos PostgreSQL	`tracer`
`API_KEY`	API Key para autenticación	`your-secure-api-key`
`API_KEY_ENABLED`	Habilita la autenticación con API Key	`true`, `false`
`LOG_LEVEL`	Nivel de log	`INFO`, `DEBUG`, `ERROR`

Para todas las variables, consulta Variables de entorno.

Paso 2: autentícate en la API

Tracer admite autenticación por API key y por plugin. La autenticación por plugin tiene prioridad cuando habilitas ambas, excepto en los endpoints configurados como exclusivos de API key.

Configuración de despliegue y autenticación	Encabezado de autenticación	Cuándo usarla
Self-hosted, con autenticación por plugin habilitada	Encabezado `Authorization` con un token Bearer	`PLUGIN_AUTH_ENABLED=true`, a menos que el endpoint esté configurado como exclusivo de API key.
Self-hosted, autenticación por API key	Encabezado `X-API-Key`	La autenticación por plugin está deshabilitada, o el endpoint está configurado como exclusivo de API key.
Lerian Cloud	Encabezado `Authorization` con un token Bearer	Siempre. El JWT lo emite Access Manager y contiene el claim `tenantId`.

Los pasos siguientes usan la forma de API key porque la mayoría de las configuraciones de desarrollo local funcionan así. Si la autenticación por plugin aplica a tu solicitud, reemplaza X-API-Key: your-secure-api-key por Authorization: Bearer $JWT en cada ejemplo.

API Key

Incluye la API Key en el encabezado X-API-Key:

GET /v1/rules
X-API-Key: your-secure-api-key

Bearer JWT

Incluye el JWT emitido por Access Manager en el encabezado Authorization:

GET /v1/rules
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Tracer extrae el claim tenantId del JWT y enruta la solicitud a la base de datos del tenant correcto. Nunca pasas el identificador del tenant en un encabezado, una ruta, un cuerpo o un alcance de regla. El token es la única fuente de verdad.

Ejemplo con cURL

# API key: List rules
curl -H "X-API-Key: your-secure-api-key" \
  http://localhost:4020/v1/rules

# Bearer JWT: List rules
curl -H "Authorization: Bearer $JWT" \
  https://tracer.sandbox.lerian.net/v1/rules

Mantén las API Keys y los JWT seguros. Nunca los expongas en código del lado del cliente ni en repositorios públicos.

La autenticación por API key está deshabilitada de forma predeterminada (API_KEY_ENABLED=false). Un despliegue de producción debe establecer API_KEY_ENABLED=true o PLUGIN_AUTH_ENABLED=true antes de exponer el servicio.

Paso 3: configura un límite de gasto

Los límites de gasto controlan los montos de las transacciones por alcance y período. Crea un límite con POST /v1/limits.

Tipos de límite

Tipo	Descripción	Conteo del período
`DAILY`	Monto máximo por día	Un nuevo conteo empieza cada día a su hora de reinicio (00:00 UTC de forma predeterminada)
`WEEKLY`	Monto máximo por semana	Un nuevo conteo empieza cada lunes a su hora de reinicio (00:00 UTC de forma predeterminada)
`MONTHLY`	Monto máximo por mes	Un nuevo conteo empieza el día 1 del mes a su hora de reinicio (00:00 UTC de forma predeterminada)
`CUSTOM`	Monto máximo para un rango de fechas personalizado	Un solo conteo para todo el rango
`PER_TRANSACTION`	Monto máximo por transacción individual	No se lleva conteo

Para la configuración detallada de todos los tipos de límite, incluyendo horas de reinicio, ventanas de tiempo y períodos personalizados, consulta la guía de límites de gasto.

Alcances

Aplica límites a contextos específicos:

Segment: se aplica a todas las cuentas de un segmento (por ejemplo, clientes corporativos)
Portfolio: se aplica a las cuentas de un portafolio
Account: se aplica a una cuenta específica
Esquema de pago: se aplica solo a un esquema, como CARD o PIX

Crea un límite

curl -X POST http://localhost:4020/v1/limits \
  -H "X-API-Key: your-secure-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Corporate Card Limit",
    "description": "Daily spending limit for corporate card transactions",
    "limitType": "DAILY",
    "maxAmount": "50000.00",
    "asset": "BRL",
    "scopes": [
      {
        "segmentId": "550e8400-e29b-41d4-a716-446655440000",
        "scheme": "CARD"
      }
    ]
  }'

Activa un límite

curl -X POST http://localhost:4020/v1/limits/{id}/activate \
  -H "X-API-Key: your-secure-api-key"

Ciclo de vida del límite

Los límites empiezan en estado DRAFT y siguen el ciclo de vida DRAFT → ACTIVE → INACTIVE. Los límites inactivos pueden volver a DRAFT para editarse, o puedes eliminarlos. Activa un límite para iniciar su aplicación. Para el ciclo de vida completo y las reglas de transición, consulta la guía de límites de gasto.

Monitorea el uso

Cada respuesta de POST /v1/validations incluye limitUsageDetails, con una entrada por cada límite que Tracer verificó. Cada entrada contiene el tope y el monto intentado. Para un límite que mantiene un conteo, también contiene el consumo proyectado del período actual: el monto ya contado, la capacidad que retienen las reservas no confirmadas del ledger de Midaz y esta transacción. El endpoint GET /v1/limits/{id}/usage reporta el período actual del límite, para el alcance más consumido. Para más opciones de configuración, consulta la guía de límites de gasto.

Paso 4: valida tu primera transacción

Con los límites configurados, estás listo para validar una transacción usando POST /v1/validations.

Envía una transacción para validación

Envía una solicitud de validación con el contexto de la transacción, incluyendo:

Detalles de la transacción (esquema de pago, monto, activo, marca de tiempo)
Información de la cuenta
Opcional: segmento, portafolio, comercio y personalizados

TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)

curl -X POST http://localhost:4020/v1/validations \
  -H "X-API-Key: your-secure-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "550e8400-e29b-41d4-a716-446655440104",
    "scheme": "CARD",
    "subType": "credit",
    "amount": "1500.00",
    "asset": "BRL",
    "transactionTimestamp": "'"$TS"'",
    "account": {
      "accountId": "550e8400-e29b-41d4-a716-446655440100"
    },
    "merchant": {
      "merchantId": "550e8400-e29b-41d4-a716-446655440103",
      "category": "5411",
      "name": "Test Merchant"
    },
    "metadata": {
      "channel": "mobile"
    }
  }'

transactionTimestamp debe ser reciente, por eso el ejemplo lo genera. Tracer rechaza una marca de tiempo futura con el código de error 0419 (tolerancia de desfase de reloj de 1 minuto). Tracer rechaza una marca de tiempo de más de 24 horas de antigüedad con el código de error 0421.

requestId es la clave de idempotencia. Envía un UUID nuevo en cada intento. Si repites uno, Tracer devuelve la decisión que ya registró para esa clave. Una regla que hayas activado en el medio no parecerá surtir efecto.

Tracer evalúa las reglas y límites que aplican a la transacción, y luego devuelve una de tres decisiones:

Decisión	Significado	Tu sistema debe
`ALLOW`	Transacción aprobada	Continuar con la transacción
`DENY`	Transacción denegada (una regla coincidió o se superó un límite)	Bloquear la transacción
`REVIEW`	Requiere revisión manual	Poner en cola para revisión humana

La respuesta indica las reglas que Tracer evaluó, las reglas que coincidieron y el uso actual de los límites. Ese detalle ayuda con la depuración y el soporte al cliente.

Por qué Tracer devuelve una decisión en lugar de bloquear directamente. Tracer es una capa de decisión, no una puerta de autorización. El sistema que llama mantiene la relación con el cliente y conoce el canal. Es quien decide qué hacer con un DENY. Por ejemplo, tu sistema emisor de tarjetas puede respetar un DENY para una preautorización stand-in. También puede capturar la solicitud para analítica. Al devolver una decisión, Tracer se integra en cualquier flujo de autorización sin apropiarse de la experiencia de cara al cliente.

Para la estructura completa del payload y el detalle de los campos, consulta la referencia de la API.

Paso 5: crea una regla de validación

Las reglas permiten definir lógica de negocio personalizada que se evalúa durante la validación. Crea una regla usando el endpoint POST /v1/rules con una expresión, una acción y alcances opcionales. Por ejemplo, para bloquear transacciones de alto valor:

curl -X POST http://localhost:4020/v1/rules \
  -H "X-API-Key: your-secure-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Block high-value card transactions",
    "description": "Deny card transactions above R$ 10,000",
    "expression": "amount > 10000",
    "action": "DENY",
    "scopes": [
      {
        "scheme": "CARD"
      }
    ]
  }'

Tracer conserva las mayúsculas y minúsculas y los espacios internos del nombre, y solo recorta los espacios al inicio y al final antes de almacenarlo. Toma el ruleId de la respuesta y úsalo en la llamada de activación siguiente.

Activa una regla

curl -X POST http://localhost:4020/v1/rules/{id}/activate \
  -H "X-API-Key: your-secure-api-key"

La activación surte efecto de inmediato en la instancia que atendió la llamada de activación. En una configuración de una sola instancia, la regla se evalúa en tu próxima validación. Cuando ejecutas varias instancias detrás de un balanceador de carga, las demás recogen el cambio en su próxima sincronización de reglas. El intervalo es RULE_SYNC_POLL_INTERVAL_SECONDS, con valor predeterminado 10. La desactivación se propaga de la misma forma.

Ciclo de vida de la regla

Las reglas siguen el mismo ciclo de vida que los límites: DRAFT → ACTIVE → INACTIVE. Para iniciar la evaluación, activa la regla usando POST /v1/rules/{id}/activate. Puedes desactivar y reactivar una regla activa según lo necesites. Para información detallada sobre las expresiones de reglas y la gestión del ciclo de vida, consulta la guía del motor de reglas.

Observabilidad

Tracer expone endpoints para monitoreo y observabilidad.

Métricas clave

Tracer expone métricas compatibles con OpenTelemetry a través del exportador OTLP, además de métricas de aplicación personalizadas:

tracer_auth_failures_total{reason} - fallos de autenticación por motivo (missing_api_key, invalid_api_key)
tracer_validation_rollback_failures_total - fallos de reversión de uso durante decisiones REVIEW (brechas de consistencia eventual que se autocorrigen en los límites del período)

El middleware HTTP de OpenTelemetry integrado en Tracer proporciona métricas estándar de solicitudes HTTP de forma automática.

Verificación

Confirma que todo funciona correctamente.

Lista de verificación

Contenedor de Tracer iniciado y saludable
Autenticación con API Key funcionando
Límite de gasto configurado
Transacción de prueba validada con éxito
Regla creada y activada

Próximos pasos

A partir de aquí, puedes explorar funciones más avanzadas:

Guía de integración - aprende a integrar tu sistema de autorización con Tracer
Motor de reglas - escribe reglas de validación en CEL y administra su ciclo de vida
Límites de gasto - configura y administra límites de gasto por alcance y período
Historial de validación y cumplimiento - consulta el historial de validación y úsalo en tus procesos de cumplimiento

Referencia rápida

Los tres flujos que más usarás:

Validar una transacción: POST /v1/validations. Consulta el Inicio rápido de la API de Tracer para conocer la forma de la solicitud.
Administrar reglas: /v1/rules (CRUD + endpoints de ciclo de vida /activate, /deactivate, /draft). Consulta la guía del motor de reglas.
Administrar límites: /v1/limits (CRUD + ciclo de vida + /usage). Consulta la guía de límites de gasto.

Para el catálogo completo de endpoints, los esquemas de solicitud/respuesta y los códigos de error, consulta la referencia de la API.

Qué debe hacer tu sistema con cada decisión

Decisión	Tracer recomienda	Tu sistema debe
`ALLOW`	Aprobación	Continuar con la transacción
`DENY`	Denegación	Bloquear la transacción e informar al usuario
`REVIEW`	Revisión	Poner en cola para revisión manual en tu sistema

Tracer devuelve las decisiones como recomendaciones. Tu sistema debe implementar la acción adecuada para cada decisión.

Resumen

Guías

Console

Operaciones

Primeros pasos con Tracer

Por qué usar Tracer

Qué es Tracer

Cómo funciona

Contextos principales

Requisitos previos

Dependencias de infraestructura

Puertos

Paso 1: ejecuta Tracer

Aplica el esquema

Inicia Tracer

Variables de entorno esenciales

Paso 2: autentícate en la API

API Key

Bearer JWT

Ejemplo con cURL

Paso 3: configura un límite de gasto

Tipos de límite

Alcances

Crea un límite

Activa un límite

Ciclo de vida del límite

Monitorea el uso

Paso 4: valida tu primera transacción

Envía una transacción para validación

Paso 5: crea una regla de validación

Activa una regla

Ciclo de vida de la regla

Observabilidad

Métricas clave

Verificación

Lista de verificación

Próximos pasos

Referencia rápida

Qué debe hacer tu sistema con cada decisión

​Por qué usar Tracer

​Qué es Tracer

​Cómo funciona

​Contextos principales

​Requisitos previos

​Dependencias de infraestructura

​Puertos

​Paso 1: ejecuta Tracer

​Aplica el esquema

​Inicia Tracer

​Variables de entorno esenciales

​Paso 2: autentícate en la API

​API Key

​Bearer JWT

​Ejemplo con cURL

​Paso 3: configura un límite de gasto

​Tipos de límite

​Alcances

​Crea un límite

​Activa un límite

​Ciclo de vida del límite

​Monitorea el uso

​Paso 4: valida tu primera transacción

​Envía una transacción para validación

​Paso 5: crea una regla de validación

​Activa una regla

​Ciclo de vida de la regla

​Observabilidad

​Métricas clave

​Verificación

​Lista de verificación

​Próximos pasos

​Referencia rápida

​Qué debe hacer tu sistema con cada decisión

Por qué usar Tracer

Qué es Tracer

Cómo funciona

Contextos principales

Requisitos previos

Dependencias de infraestructura

Puertos

Paso 1: ejecuta Tracer

Aplica el esquema

Inicia Tracer

Variables de entorno esenciales

Paso 2: autentícate en la API

API Key

Bearer JWT

Ejemplo con cURL

Paso 3: configura un límite de gasto

Tipos de límite

Alcances

Crea un límite

Activa un límite

Ciclo de vida del límite

Monitorea el uso

Paso 4: valida tu primera transacción

Envía una transacción para validación

Paso 5: crea una regla de validación

Activa una regla

Ciclo de vida de la regla

Observabilidad

Métricas clave

Verificación

Lista de verificación

Próximos pasos

Referencia rápida

Qué debe hacer tu sistema con cada decisión