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, no 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, no 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 que hay que reconocer: 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 a 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: admite cualquier tipo de transacción (Card, Wire, Pix, 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 y Docker Compose instalados
Go 1.26+ para desarrollo local (el go.mod del repositorio declara la versión exacta del toolchain)
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. 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
PostgreSQL	5701	Primario compartido de PostgreSQL de Midaz, tal como lo expone el ejemplo de infraestructura incluido (`DB_PORT`)

Paso 1: configura el entorno

Puedes ejecutar Tracer con Docker Compose o de forma local para desarrollo.

Opción A: Docker Compose (recomendado)

El propio archivo Compose de Tracer declara solo dos servicios: la aplicación y un ejecutor de migraciones de un solo uso. PostgreSQL no es uno de ellos. Proviene del Compose de infraestructura de la plataforma compartida y debe estar saludable primero. El contenedor de la aplicación arranca solo después de que el ejecutor de migraciones aplica el esquema y termina con éxito. El servicio siempre arranca contra una base de datos ya migrada.

En Midaz v4, Tracer es source-available bajo ELv2 dentro del repositorio y la versión de Midaz. Sigue ejecutándose como su propio servicio. Empieza desde components/tracer para desarrollo local.

Navega al directorio del proyecto Tracer e inicia los servicios:

cd components/tracer

# Setup environment
cp .env.example .env

# Start all services (brings up the shared infrastructure first,
# then the migration runner, then 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`	Habilita la autenticación con API Key	`true`, `false`
`SERVER_PORT`	Puerto de la API	`4020`
`LOG_LEVEL`	Nivel de log	`INFO`, `DEBUG`, `ERROR`

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
Single-tenant, con autenticación por plugin habilitada	Encabezado `Authorization` con un token Bearer	`MULTI_TENANT_ENABLED=false` y `PLUGIN_AUTH_ENABLED=true`, a menos que el endpoint esté configurado como exclusivo de API key.
Single-tenant, autenticación por API key	Encabezado `X-API-Key`	`MULTI_TENANT_ENABLED=false` y la autenticación por plugin está deshabilitada, o el endpoint está configurado como exclusivo de API key.
Multi-tenant (SaaS / BYOC Multi-Tenant)	Encabezado `Authorization` con un token Bearer	Cualquier despliegue con `MULTI_TENANT_ENABLED=true`. Se requiere autenticación por plugin; el JWT lo emite Access Manager y contiene el claim `tenantId`.

Los pasos siguientes usan la forma de API key single-tenant 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 (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 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

# 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

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). El .env.example incluido la mantiene desactivada, así que el desarrollo local funciona sin configuración adicional. 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: 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 calendario a las 00:00 UTC
`WEEKLY`	Monto máximo por semana	Un nuevo conteo empieza cada semana ISO, el lunes a las 00:00 UTC
`MONTHLY`	Monto máximo por mes	Un nuevo conteo empieza el día 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 lleva conteo

Para la 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:

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
Tipo de transacción: se aplica solo a CARD, WIRE, PIX o CRYPTO

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",
        "transactionType": "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 de forma permanente. 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, el monto intentado y el consumo proyectado del período actual de ese tope. Esa proyección incluye esta transacción. El endpoint GET /v1/limits/{id}/usage reporta un total acumulado de los contadores del límite, para una revisión del consumo general. 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 (tipo, 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",
    "transactionType": "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 dinámicamente. 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 funciona como una capa de decisión, no como 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 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, 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": [
      {
        "transactionType": "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

Servicios de Docker iniciados y saludables
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

Configuraste Tracer y validaste tu primera transacción. 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: configura el entorno

Opción A: Docker Compose (recomendado)

Opción B: ejecución local

Variables de entorno esenciales

Paso 2: autentícate en la API

API Key (single-tenant)

Bearer JWT (multi-tenant)

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: configura el entorno

​Opción A: Docker Compose (recomendado)

​Opción B: ejecución local

​Variables de entorno esenciales

​Paso 2: autentícate en la API

​API Key (single-tenant)

​Bearer JWT (multi-tenant)

​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: configura el entorno

Opción A: Docker Compose (recomendado)

Opción B: ejecución local

Variables de entorno esenciales

Paso 2: autentícate en la API

API Key (single-tenant)

Bearer JWT (multi-tenant)

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