Primeros pasos con Tracer

Esta guía te guiará a través de la configuración de Tracer y la ejecución de tu primera validación. En solo unos pocos pasos, tendrás un entorno de trabajo 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
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

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.5+ (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	8080	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.

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

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="8080"
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	`8080`
`LOG_LEVEL`	Nivel de registro	`INFO`, `DEBUG`, `ERROR`

Paso 2: Autenticarse en la API

Tracer usa autenticación con API Key para todas las solicitudes.

Autenticación 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 código del lado del cliente o repositorios públicos.

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	Descripción
`GET /health`	Verificación de actividad (aplicación ejecutándose)
`GET /ready`	Verificación de disponibilidad (base de datos disponible)

Métricas principales

Tracer expone métricas compatibles con Prometheus:

tracer_validations_total{decision} - Total de validaciones por decisión
tracer_validation_duration_seconds - Histograma de latencia de validación
tracer_rule_evaluations_total - Total de evaluaciones de reglas
tracer_limit_checks_total{result} - Verificaciones de límites por resultado
tracer_auth_failures_total{reason} - Fallos de autenticación por motivo
tracer_active_rules - Numero de reglas activas

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

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 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 - Crea reglas de validación sofisticadas con expresiones CEL
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

Endpoints y conceptos clave para consulta rápida.

Endpoints principales

Operación	Método	Endpoint
Verificación de salud	GET	`/health`
Verificación de disponibilidad	GET	`/ready`
Validar transacción	POST	`/v1/validations`
Obtener validación	GET	`/v1/validations/{validationId}`
Listar validaciones	GET	`/v1/validations`
Crear límite	POST	`/v1/limits`
Obtener límite	GET	`/v1/limits/{limitId}`
Actualizar límite	PATCH	`/v1/limits/{limitId}`
Obtener uso del límite	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 transacción

Tipo	Descripción	Ejemplos de subType
`CARD`	Transacciones basadas en tarjeta	`debit`, `credit`, `prepaid`
`WIRE`	Transferencias bancarias	`domestic`, `international`, `ach`
`PIX`	Pago instantáneo brasileño	`instant`, `scheduled`
`CRYPTO`	Criptomoneda	`bitcoin`, `ethereum`, `stablecoin`

Tipos de decisión

Decisión	Descripción	Tu sistema debería
`ALLOW`	Tracer recomienda aprobación	Proceder con la transacción
`DENY`	Tracer recomienda denegación	Bloquear la transacción e informar al usuario
`REVIEW`	Tracer recomienda 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

​Autenticación 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

​Métricas principales

​Verificación

​Lista de verificación

​Prueba de conectividad

​Próximos pasos

​Referencia rápida

​Endpoints principales

​Tipos de transacción

​Tipos de 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

Autenticación 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

Métricas principales

Verificación

Lista de verificación

Prueba de conectividad

Próximos pasos

Referencia rápida

Endpoints principales

Tipos de transacción

Tipos de decisión