Primeros pasos con Tracer

Esta guia te guiara a traves de la configuracion de Tracer y la ejecucion de tu primera validacion. En solo unos pocos pasos, tendras un entorno de trabajo listo para validar transacciones en tiempo real.

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
Registro de auditoría 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

Que 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.

Como funciona

En este flujo:

Rules evaluan expresiones contra el contexto de la transaccion
Limits verifican los umbrales de gasto para los alcances aplicables
Decision devuelve ALLOW, DENY o REVIEW basado en los resultados de la evaluacion

Contextos principales

Tracer esta construido alrededor de tres contextos delimitados:

Contexto de Validacion - Orquesta solicitudes, coordina evaluaciones, registra el rastro de auditoria
Contexto de Reglas - Gestiona definiciones de reglas y evaluacion de expresiones
Contexto de Limites - Gestiona limites de gasto y seguimiento de uso

Prerrequisitos

Antes de comenzar, asegurate de tener:

Docker y Docker Compose instalados
Go 1.25.5+ (para desarrollo local)
PostgreSQL 16+ (incluido en Docker Compose)
API Key para autenticacion

Dependencias de infraestructura

Tracer requiere los siguientes componentes:

Componente	Version	Proposito
PostgreSQL	16+	Persistencia de datos y rastro de auditoria

Puertos

Puertos predeterminados utilizados por los servicios de Tracer:

Servicio	Puerto	Descripcion
Tracer API	8080	API REST principal
PostgreSQL	5432	Base de datos

Paso 1: Configurar el entorno

Puedes ejecutar Tracer con Docker Compose o localmente para desarrollo.

Opcion A: Docker Compose (recomendado)

Esta es la forma mas rapida de comenzar. PostgreSQL se inicia automaticamente con el servicio.

Clona el repositorio e inicia los servicios:

# Clone the repository
git clone https://github.com/lerianstudio/tracer.git
cd tracer

# Setup environment
cp .env.example .env

# Start all services
make up

Verifica el estado de los servicios:

# Check Tracer health
curl http://localhost:8080/health

# Check readiness (database connection)
curl http://localhost:8080/ready

Opcion B: Ejecucion 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="8080"
export LOG_LEVEL="INFO"

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

Variables de entorno esenciales

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

Paso 2: Autenticarse en la API

Tracer usa autenticacion con API Key para todas las solicitudes.

Autenticacion con API Key

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

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

Ejemplo con cURL

# Check API health (no authentication required)
curl http://localhost:8080/health

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

Las API Keys deben mantenerse seguras. Nunca expongas tu API Key en codigo del lado del cliente o repositorios publicos.

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
`MONTHLY`	Monto máximo por mes	Se reinicia el 1° del mes
`PER_TRANSACTION`	Monto máximo por transacción individual	No requiere seguimiento

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

Ciclo de vida del límite

Los límites siguen el mismo ciclo de vida que las reglas: DRAFT → ACTIVE → INACTIVE. Activa un límite para comenzar su aplicación.

Monitorear uso

Consulta GET /v1/limits/{limitId}/usage para verificar el consumo actual. El indicador nearLimit se activa al 80% de utilización para gestión proactiva. 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 metadata personalizada

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. 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, puedes crear una regla con:

Expresión: amount > 1000000 (montos superiores a R$ 10.000)
Acción: DENY
Alcance: Aplicar solo a transacciones CARD

Ciclo de vida de la regla

Las reglas se crean en estado DRAFT. Para iniciar la evaluación, activa la regla usando POST /v1/rules/{ruleId}/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.

Endpoints de salud

Endpoint	Descripcion
`GET /health`	Verificacion de actividad (aplicacion ejecutandose)
`GET /ready`	Verificacion de disponibilidad (base de datos disponible)

Metricas principales

Tracer expone metricas compatibles con Prometheus:

tracer_validations_total{decision} - Total de validaciones por decision
tracer_validation_duration_seconds - Histograma de latencia de validacion
tracer_rule_evaluations_total - Total de evaluaciones de reglas
tracer_limit_checks_total{result} - Verificaciones de limites por resultado
tracer_auth_failures_total{reason} - Fallos de autenticacion por motivo
tracer_active_rules - Numero de reglas activas

Verificacion

Confirma que todo esta funcionando correctamente.

Lista de verificacion

Servicios Docker iniciados y saludables
Autenticacion con API Key funcionando
Limite de gasto configurado
Transaccion de prueba validada exitosamente
Regla creada y activada

Prueba de conectividad

# Check API health (liveness)
curl http://localhost:8080/health

# Check readiness (database connection)
curl http://localhost:8080/ready

Próximos pasos

Has configurado exitosamente Tracer y validado tu primera transaccion. Desde aqui, puedes explorar funciones mas avanzadas:

Guia de integracion - Aprende como integrar tu sistema de autorizacion con Tracer
Motor de reglas - Crea reglas de validacion sofisticadas con expresiones CEL
Limites de gasto - Configura y gestiona limites de gasto por alcance y periodo
Auditoria y cumplimiento - Consulta el historial de validaciones y comprende el rastro de auditoria

Referencia rápida

Endpoints y conceptos clave para consulta rápida.

Endpoints principales

Operacion	Metodo	Endpoint
Verificacion de salud	GET	`/health`
Verificacion de disponibilidad	GET	`/ready`
Validar transaccion	POST	`/v1/validations`
Obtener validacion	GET	`/v1/validations/{validationId}`
Listar validaciones	GET	`/v1/validations`
Crear limite	POST	`/v1/limits`
Obtener limite	GET	`/v1/limits/{limitId}`
Actualizar limite	PATCH	`/v1/limits/{limitId}`
Obtener uso del limite	GET	`/v1/limits/{limitId}/usage`
Crear regla	POST	`/v1/rules`
Obtener regla	GET	`/v1/rules/{ruleId}`
Actualizar regla	PATCH	`/v1/rules/{ruleId}`
Activar regla	POST	`/v1/rules/{ruleId}/activate`
Desactivar regla	POST	`/v1/rules/{ruleId}/deactivate`
Eliminar regla	DELETE	`/v1/rules/{ruleId}`

Tipos de transaccion

Tipo	Descripcion	Ejemplos de subType
`CARD`	Transacciones basadas en tarjeta	`debit`, `credit`, `prepaid`
`WIRE`	Transferencias bancarias	`domestic`, `international`, `ach`
`PIX`	Pago instantaneo brasileno	`instant`, `scheduled`
`CRYPTO`	Criptomoneda	`bitcoin`, `ethereum`, `stablecoin`

Tipos de decision

Decision	Descripcion	Tu sistema deberia
`ALLOW`	Tracer recomienda aprobacion	Proceder con la transaccion
`DENY`	Tracer recomienda denegacion	Bloquear la transaccion e informar al usuario
`REVIEW`	Tracer recomienda revision	Enviar a revision manual en tu sistema

Tracer devuelve decisiones como recomendaciones. Tu sistema es responsable de implementar la accion apropiada basada en cada decision.

​Por qué usar Tracer

​Que es Tracer

​Como funciona

​Contextos principales

​Prerrequisitos

​Dependencias de infraestructura

​Puertos

​Paso 1: Configurar el entorno

​Opcion A: Docker Compose (recomendado)

​Opcion B: Ejecucion local

​Variables de entorno esenciales

​Paso 2: Autenticarse en la API

​Autenticacion con API Key

​Ejemplo con cURL

​Paso 3: Configurar un límite de gasto

​Tipos de límite

​Alcances

​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

​Ciclo de vida de la regla

​Observabilidad

​Endpoints de salud

​Metricas principales

​Verificacion

​Lista de verificacion

​Prueba de conectividad

​Próximos pasos

​Referencia rápida

​Endpoints principales

​Tipos de transaccion

​Tipos de decision

Por qué usar Tracer

Que es Tracer

Como funciona

Contextos principales

Prerrequisitos

Dependencias de infraestructura

Puertos

Paso 1: Configurar el entorno

Opcion A: Docker Compose (recomendado)

Opcion B: Ejecucion local

Variables de entorno esenciales

Paso 2: Autenticarse en la API

Autenticacion con API Key

Ejemplo con cURL

Paso 3: Configurar un límite de gasto

Tipos de límite

Alcances

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

Ciclo de vida de la regla

Observabilidad

Endpoints de salud

Metricas principales

Verificacion

Lista de verificacion

Prueba de conectividad

Próximos pasos

Referencia rápida

Endpoints principales

Tipos de transaccion

Tipos de decision