> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Primeros pasos con Tracer > Guía de inicio rápido para configurar y usar Tracer, la plataforma de validación de transacciones en tiempo real y control de gastos de Lerian. export const GMetadata = ({children}) => {children} ; export const GAuditTrail = ({children}) => {children} ; 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 `if`s 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](./what-is-tracer.mdx). Si ya lo tienes corriendo y necesitas la mecánica de la API, salta al [Inicio rápido de la API de Tracer](/es/reference/tracer/tracer-api-quick-start). 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](/es/reference/tracer/tracer-api-quick-start). ## 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 * **Rastro 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 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 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: 1. **Contexto de Validación** - Orquesta solicitudes, coordina evaluaciones, registra el rastro de auditoría 2. **Contexto de Reglas** - Gestiona definiciones de reglas y evaluación de expresiones 3. **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.26+** (para desarrollo local — la versión exacta del toolchain está declarada en el `go.mod` del repositorio) * [ ] **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: ```bash theme={null} 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: ```bash theme={null} # 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: ` | Desarrollo local, BYOC single-customer, o cualquier despliegue con `MULTI_TENANT_ENABLED=false` (predeterminado). | | **Multi-tenant (SaaS / BYOC Multi-Tenant)** | `Authorization: Bearer ` | Cualquier despliegue con `MULTI_TENANT_ENABLED=true`. El JWT es emitido por [Access Manager](/es/platform/access-manager/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`: ```http theme={null} 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`: ```http theme={null} 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 ```bash theme={null} # Single-tenant: List rules curl -H "X-API-Key: your-secure-api-key" \ http://localhost:4020/v1/rules ``` ```bash theme={null} # 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 | 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](./spending-limits.mdx). ### 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 ```bash theme={null} 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 ```bash theme={null} 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](./spending-limits.mdx). ### 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](./spending-limits.mdx). *** ## 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 ```bash theme={null} 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 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`. 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](/es/reference/tracer/validate-transaction). *** ## 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: ```bash theme={null} 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 ```bash theme={null} 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](./rule-engine.mdx). *** ## 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](./integration-guide.mdx)** - Aprende cómo integrar tu sistema de autorización con Tracer * **[Motor de reglas](./rule-engine.mdx)** - Escribe reglas de validación en CEL y gestiona su ciclo de vida * **[Límites de gasto](./spending-limits.mdx)** - Configura y gestiona límites de gasto por alcance y período * **[Auditoría y cumplimiento](./audit-compliance.mdx)** - 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](/es/reference/tracer/tracer-api-quick-start) 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](./rule-engine.mdx). * **Gestionar límites**: `/v1/limits` (CRUD + ciclo de vida + `/usage`) — consulta la [Guía de límites de gasto](./spending-limits.mdx). Para el catálogo completo de endpoints, schemas de request/response y códigos de error, consulta la [referencia de la API](/es/openapi/v3-current/tracer.yaml). ### 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.