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

Cómo Tracer procesa una solicitud de validación a través de sus contextos de Validación, Reglas y Límites y devuelve una decisión ALLOW, DENY o REVIEW; el Contexto de Auditoría se omite intencionalmente en la figura — Figura 1. Cómo funciona Tracer

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 cuatro 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
Contexto de Auditoría - Mantiene el registro de eventos inmutable y verifica su cadena de hash

Prerrequisitos

Antes de comenzar, asegúrate de tener:

Docker y Docker Compose instalados
Go 1.26+ (para desarrollo local — la versión exacta del toolchain está declarada en el go.mod del repositorio)
PostgreSQL 17 (el primario compartido de Midaz, iniciado por el compose de infraestructura de la plataforma, no por el de Tracer)
API Key para autenticación

Dependencias de infraestructura

Tracer requiere los siguientes componentes:

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

Puertos

Puertos predeterminados utilizados por los servicios de Tracer:

Servicio	Puerto	Descripción
Tracer API	4020	API REST principal
PostgreSQL	5701	Primario de PostgreSQL compartido de Midaz, tal como lo expone el ejemplo de infraestructura distribuido (`DB_PORT`)

Paso 1: Configurar el entorno

Puedes ejecutar Tracer con Docker Compose o localmente para desarrollo.

Opción A: Docker Compose (recomendado)

El Compose propio de Tracer declara solo dos servicios: la aplicación y un ejecutor de migraciones de un solo uso. PostgreSQL no es uno de ellos — viene del Compose de infraestructura compartida de la plataforma y debe estar saludable primero. El contenedor de la aplicación arranca solo después de que el ejecutor de migraciones aplicó el esquema y terminó con éxito, así que el servicio siempre inicia contra una base ya migrada.

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 components/tracer

# Configura el entorno
cp .env.example .env

# Inicia todos los servicios (levanta primero la infraestructura
# compartida, luego el ejecutor de migraciones y después Tracer)
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.sandbox.lerian.net/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	Conteo por período
`DAILY`	Monto máximo por día	Un conteo nuevo empieza cada día calendario a las 00:00 UTC
`WEEKLY`	Monto máximo por semana	Un conteo nuevo empieza cada semana ISO, el lunes a las 00:00 UTC
`MONTHLY`	Monto máximo por mes	Un conteo nuevo empieza el 1° del mes a las 00:00 UTC
`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 guarda ningún conteo

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

Cada respuesta de POST /v1/validations lleva limitUsageDetails, con una entrada por límite que Tracer verificó: el tope, el monto intentado y el consumo proyectado del período actual de ese tope si la transacción se permite. GET /v1/limits/{id}/usage reporta un total acumulado entre los contadores del límite, para revisar el consumo general. 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

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",
    "transactionType": "CARD",
    "subType": "credit",
    "amount": "1500.00",
    "currency": "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"
    }
  }'

El transactionTimestamp debe ser reciente, por eso el ejemplo lo genera: timestamps en el futuro son rechazados con el código de error 0419 (tolerancia de 1 minuto de desincronización de reloj), y timestamps con más de 24 horas son rechazados 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, así que una regla que activaste en el medio no parecerá surtir efecto.

Tracer evalúa las reglas y límites que aplican a la transacción, 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"
      }
    ]
  }'

Tracer guarda el nombre de la regla en una forma normalizada, así que el name de la respuesta puede diferir de la cadena que enviaste. Toma el ruleId de la respuesta y úsalo en la llamada de activación de abajo.

Activar 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, así que en un setup de una sola instancia la regla empieza a evaluarse en tu siguiente validación. Cuando corres varias instancias detrás de un balanceador, las demás recogen el cambio en su siguiente sincronización de reglas (RULE_SYNC_POLL_INTERVAL_SECONDS, predeterminado 10); la desactivación se propaga igual.

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 HTTP de OpenTelemetry integrado en Tracer.

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.

Resumen

Guías

Console

Operaciones

Primeros pasos con Tracer

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

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