Primeros pasos con Tracer

Tracer es la capa que tu sistema de autorización u onboarding llama antes de que una transacción siga adelante. Ejecuta tus políticas de fraude, riesgo y límites en milisegundos y devuelve ALLOW, DENY o REVIEW — así la decisión queda en un solo lugar, no dispersa por el código del producto. Qué cambia en tu operación: la lógica de decisión deja de vivir en ifs dispersos por varios servicios. Los cambios en reglas se publican vía API el mismo día, no en la próxima release. La auditoría deja de ser “voy a juntar logs de N sistemas y cruzar timestamps” para volverse “este es el registro inmutable de por qué esta transacción recibió esta decisión”. El trade-off honesto: agregas una llamada HTTP al camino crítico de cada transacción (objetivo p99 bajo 80ms). A cambio, ganas un punto único de política, auditoría y analytics — y eliminas lógica duplicada del código del producto.

¿Para quién es esta guía? Desarrolladores (jr o sr) integrando Tracer por primera vez. Si estás evaluando Tracer a nivel de producto o estrategia, empieza por Qué es Tracer. Si ya lo tienes corriendo y necesitas la mecánica de la API, salta al Inicio rápido de la API de Tracer.

Esta guía te guía a través de la configuración de Tracer y la ejecución de tu primera validación. En unos pocos pasos, tendrás un entorno funcional listo para validar transacciones en tiempo real. Para instrucciones paso a paso con ejemplos de solicitudes y respuestas de la API, consulta el 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 80ms (p99)
Reglas flexibles: Motor de reglas basado en expresiones para lógica de negocio personalizada
Control de gastos: Configura límites por cuenta, portafolio, segmento y período
completo: Registros de validación inmutables para cumplimiento SOX/GLBA
Agnóstico de producto: Soporta cualquier tipo de transacción (Card, Wire, PIX, Crypto)

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

Comprender la arquitectura y conceptos principales de Tracer
Tener un entorno de desarrollo funcional
Ejecutar tu primera validación de transacción
Configurar 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 transacciones y actúa según la decisión (ALLOW, DENY o REVIEW) de acuerdo con tu lógica de negocio.

Cómo funciona

En este flujo:

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

Contextos principales

Tracer está construido alrededor de tres contextos delimitados:

Contexto de Validación - Orquesta solicitudes, coordina evaluaciones, registra el rastro de auditoría
Contexto de Reglas - Gestiona definiciones de reglas y evaluación de expresiones
Contexto de Límites - Gestiona límites de gasto y seguimiento de uso

Prerrequisitos

Antes de comenzar, asegúrate de tener:

Docker y Docker Compose instalados
Go 1.25.7+ (para desarrollo local)
PostgreSQL 16+ (incluido en Docker Compose)
API Key para autenticación

Dependencias de infraestructura

Tracer requiere los siguientes componentes:

Componente	Versión	Propósito
PostgreSQL	16+	Persistencia de datos y rastro de auditoría

Puertos

Puertos predeterminados utilizados por los servicios de Tracer:

Servicio	Puerto	Descripción
Tracer API	4020	API REST principal
PostgreSQL	5432	Base de datos

Paso 1: Configurar el entorno

Puedes ejecutar Tracer con Docker Compose o localmente para desarrollo.

Opción A: Docker Compose (recomendado)

Esta es la forma más rápida de comenzar. PostgreSQL se inicia automáticamente con el servicio.

Tracer está disponible para clientes con licencia; su repositorio se mantiene internamente. Los pasos a continuación asumen que ya tienes acceso a los archivos del proyecto Tracer requeridos.

Navega al directorio del proyecto Tracer e inicia los servicios:

cd tracer

# Setup environment
cp .env.example .env

# Start all services
make up

Opción B: Ejecución local

Para desarrollo, puedes ejecutar Tracer localmente:

# Set environment variables
export DB_HOST="localhost"
export DB_NAME="tracer"
export API_KEY="your-secure-api-key"
export API_KEY_ENABLED="true"
export SERVER_PORT="4020"
export LOG_LEVEL="INFO"

# Start the service
go run cmd/app/main.go

Variables de entorno esenciales

Variable	Descripción	Ejemplo
`DB_HOST`	Host de PostgreSQL	`localhost`
`DB_NAME`	Nombre de la base de datos PostgreSQL	`tracer`
`API_KEY`	API Key para autenticación	`your-secure-api-key`
`API_KEY_ENABLED`	Habilitar autenticación con API Key	`true`, `false`
`SERVER_PORT`	Puerto de la API	`4020`
`LOG_LEVEL`	Nivel de registro	`INFO`, `DEBUG`, `ERROR`

Paso 2: Autenticarse en la API

Tracer soporta dos modos de autenticación. Cuál usas depende de la topología de despliegue:

Despliegue	Encabezado de auth	Cuándo usar
Single-tenant	`X-API-Key: <api-key>`	Desarrollo local, BYOC single-customer, o cualquier despliegue con `MULTI_TENANT_ENABLED=false` (predeterminado).
Multi-tenant (SaaS / BYOC Multi-Tenant)	`Authorization: Bearer <jwt>`	Cualquier despliegue con `MULTI_TENANT_ENABLED=true`. El JWT es emitido por Access Manager y lleva el claim `tenantId`.

Los pasos restantes de esta guía usan la forma single-tenant (API Key) porque la mayoría de las configuraciones locales de desarrollo funcionan así. Si tu entorno es multi-tenant, reemplaza X-API-Key: your-secure-api-key por Authorization: Bearer $JWT en todos los ejemplos.

API Key (single-tenant)

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

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

Bearer JWT (multi-tenant)

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 pases el identificador del tenant en encabezado, path, body o alcance de regla — el token es la única fuente de verdad.

Ejemplo con cURL

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

# Multi-tenant: List rules
curl -H "Authorization: Bearer $JWT" \
  https://tracer.lerian.io/v1/rules

Las API Keys y JWTs deben mantenerse seguros. Nunca los expongas en código del lado del cliente o repositorios públicos.

La autenticación por API Key está deshabilitada por defecto (API_KEY_ENABLED=false). El archivo .env.example la mantiene desactivada para que el desarrollo local funcione sin configuración, pero un despliegue de producción debe establecer API_KEY_ENABLED=true (single-tenant) o MULTI_TENANT_ENABLED=true y PLUGIN_AUTH_ENABLED=true (multi-tenant) antes de exponer el servicio.

Paso 3: Configurar un límite de gasto

Los límites de gasto controlan los montos de transacción por alcance y período. Crea un límite usando POST /v1/limits.

Tipos de límite

Tipo	Descripción	Comportamiento de reinicio
`DAILY`	Monto máximo por día	Se reinicia a medianoche UTC
`WEEKLY`	Monto máximo por semana	Se reinicia cada lunes a medianoche UTC
`MONTHLY`	Monto máximo por mes	Se reinicia el 1° del mes
`CUSTOM`	Monto máximo para un rango de fechas personalizado	Se reinicia al final del período personalizado
`PER_TRANSACTION`	Monto máximo por transacción individual	No requiere seguimiento

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

Alcances

Aplica límites a contextos específicos:

Segmento: Aplica a todas las cuentas de un segmento (ej.: clientes corporativos)
Portafolio: Aplica a cuentas de un portafolio
Cuenta: Aplica a una cuenta específica
Tipo de transacción: Aplica solo a CARD, WIRE, PIX o CRYPTO

Crear 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",
    "currency": "BRL",
    "scopes": [
      {
        "segmentId": "550e8400-e29b-41d4-a716-446655440000",
        "transactionType": "CARD"
      }
    ]
  }'

Activar 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 se crean en estado DRAFT y siguen el ciclo de vida DRAFT → ACTIVE → INACTIVE. Los límites inactivos pueden volver a DRAFT para edición o ser eliminados permanentemente. Activa un límite para comenzar su aplicación. Para el ciclo de vida completo y las reglas de transición, consulta la Guía de límites de gasto.

Monitorear uso

Consulta GET /v1/limits/{id}/usage para verificar el consumo actual. El indicador nearLimit queda en true cuando la utilización es estrictamente mayor que 80% (utilizationPercent > 80), dándole a los operadores un aviso antes de que el límite sea excedido. Para opciones de configuración detalladas, consulta la Guía de límites de gasto.

Paso 4: Validar tu primera transacción

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

Enviar 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 (tipo, monto, moneda, timestamp)
Información de la cuenta
Opcional: segmento, portafolio, comercio y personalizada

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",
    "transactionType": "CARD",
    "subType": "credit",
    "amount": "1500.00",
    "currency": "BRL",
    "transactionTimestamp": "2026-02-20T12:00:00Z",
    "account": {
      "id": "550e8400-e29b-41d4-a716-446655440100"
    },
    "merchant": {
      "id": "550e8400-e29b-41d4-a716-446655440103",
      "category": "5411",
      "name": "Test Merchant"
    },
    "metadata": {
      "channel": "mobile"
    }
  }'

El transactionTimestamp debe ser reciente: timestamps en el futuro son rechazados con TRC-0226 (tolerancia de 1 minuto de desincronización de reloj), y timestamps con más de 24 horas son rechazados con TRC-0228.

Tracer evalúa todas las reglas y límites activos, luego devuelve una de tres decisiones:

Decisión	Significado	Tu sistema debería
`ALLOW`	Transacción aprobada	Proceder con la transacción
`DENY`	Transacción denegada (regla coincidió o límite excedido)	Bloquear la transacción
`REVIEW`	Requiere revisión manual	Enviar a cola de revisión humana

La respuesta incluye detalles sobre qué reglas fueron evaluadas, cuáles coincidieron y el uso actual del límite — útil para depuración y soporte al cliente.

Por qué Tracer devuelve una decisión en vez de bloquear directamente. Tracer es una capa de decisión, no un gateway de autorización. El sistema que llama es quien tiene la relación con el cliente, conoce el canal y decide qué hacer con un DENY — por ejemplo, tu sistema emisor de tarjeta puede honrar un DENY en una pre-auth de stand-in pero aún así querer capturar la solicitud para analytics. Al devolver una decisión, Tracer encaja en cualquier flujo de autorización sin ser dueño de la UX hacia el cliente.

Para la estructura completa del payload y detalles de campos, consulta la Referencia de API.

Paso 5: Crear una regla de validación

Las reglas te 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, 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": [
      {
        "transactionType": "CARD"
      }
    ]
  }'

Activar una regla

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

Las reglas activas se sirven desde una cache en memoria que se refresca cada RULE_SYNC_POLL_INTERVAL_SECONDS (predeterminado 10). Las reglas recién activadas pueden tardar hasta ~10 segundos en comenzar a ser evaluadas, y las desactivaciones entran en vigor en el próximo sync. Planifica las pruebas de integración en consecuencia.

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. Las reglas activas pueden desactivarse y reactivarse según sea necesario. Para información detallada sobre expresiones de reglas y gestión del ciclo de vida, consulta la Guía del motor de reglas.

Observabilidad

Tracer expone endpoints para monitoreo y observabilidad.

Métricas principales

Tracer expone métricas compatibles con OpenTelemetry vía el 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_audit_persist_failures_total - Fallos de persistencia de registros de auditoría (riesgo de cumplimiento)
tracer_validation_rollback_failures_total - Fallos de rollback de uso en decisiones REVIEW (brechas de consistencia eventual que se auto-corrigen en las fronteras de período)

Las métricas estándar de solicitudes HTTP son proporcionadas automáticamente por el middleware OpenTelemetry Fiber.

Verificación

Confirma que todo está funcionando correctamente.

Lista de verificación

Servicios Docker iniciados y saludables
Autenticación con API Key funcionando
Límite de gasto configurado
Transacción de prueba validada exitosamente
Regla creada y activada

Próximos pasos

Has configurado exitosamente Tracer y validado tu primera transacción. Desde aquí, puedes explorar funciones más avanzadas:

Guía de integración - Aprende cómo integrar tu sistema de autorización con Tracer
Motor de reglas - Escribe reglas de validación en CEL y gestiona su ciclo de vida
Límites de gasto - Configura y gestiona límites de gasto por alcance y período
Auditoría y cumplimiento - Consulta el historial de validaciones y comprende el rastro de auditoría

Referencia rápida

Los tres flujos que más vas a usar:

Validar una transacción: POST /v1/validations — consulta el Inicio rápido de la API de Tracer para el formato de la solicitud.
Gestionar reglas: /v1/rules (CRUD + endpoints de ciclo de vida /activate, /deactivate, /draft) — consulta la Guía del motor de reglas.
Gestionar 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, schemas de request/response y 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 debería
`ALLOW`	Aprobación	Proceder con la transacción
`DENY`	Denegación	Bloquear la transacción e informar al usuario
`REVIEW`	Revisión	Enviar a revisión manual en tu sistema

Tracer devuelve decisiones como recomendaciones. Tu sistema es responsable de implementar la acción apropiada basada en cada decisión.

​Por qué usar Tracer

​Qué es Tracer

​Cómo funciona

​Contextos principales

​Prerrequisitos

​Dependencias de infraestructura

​Puertos

​Paso 1: Configurar el entorno

​Opción A: Docker Compose (recomendado)

​Opción B: Ejecución local

​Variables de entorno esenciales

​Paso 2: Autenticarse en la API

​API Key (single-tenant)

​Bearer JWT (multi-tenant)

​Ejemplo con cURL

​Paso 3: Configurar un límite de gasto

​Tipos de límite

​Alcances

​Crear un límite

​Activar un límite

​Ciclo de vida del límite

​Monitorear uso

​Paso 4: Validar tu primera transacción

​Enviar una transacción para validación

​Paso 5: Crear una regla de validación

​Activar una regla

​Ciclo de vida de la regla

​Observabilidad

​Métricas principales

​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

Prerrequisitos

Dependencias de infraestructura

Puertos

Paso 1: Configurar el entorno

Opción A: Docker Compose (recomendado)

Opción B: Ejecución local

Variables de entorno esenciales

Paso 2: Autenticarse en la API

API Key (single-tenant)

Bearer JWT (multi-tenant)

Ejemplo con cURL

Paso 3: Configurar un límite de gasto

Tipos de límite

Alcances

Crear un límite

Activar un límite

Ciclo de vida del límite

Monitorear uso

Paso 4: Validar tu primera transacción

Enviar una transacción para validación

Paso 5: Crear una regla de validación

Activar una regla

Ciclo de vida de la regla

Observabilidad

Métricas principales

Verificación

Lista de verificación

Próximos pasos

Referencia rápida

Qué debe hacer tu sistema con cada decisión