> ## 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 > Configura Tracer con Docker Compose, aprende sus contextos de validación principales y ejecuta tu primera llamada de validación de transacción con ALLOW, DENY o REVIEW. export const GMetadata = ({children}) => {children} ; 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](./what-is-tracer.mdx). 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](/es/reference/products/tracer/tracer-api-quick-start). 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](/es/reference/products/tracer/tracer-api-quick-start). ## 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 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: 1. **Contexto de Validation** - orquesta las solicitudes, coordina la evaluación y almacena el historial de validación 2. **Contexto de Rules** - administra las definiciones de reglas y la evaluación de expresiones 3. **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: ```bash theme={null} 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: ```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` | 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](/es/platform/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`: ```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 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 ```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 ``` 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](./spending-limits.mdx). ### 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 ```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", "asset": "BRL", "scopes": [ { "segmentId": "550e8400-e29b-41d4-a716-446655440000", "transactionType": "CARD" } ] }' ``` ### Activa 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 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](./spending-limits.mdx). ### 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](./spending-limits.mdx). *** ## 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 metadatos personalizados ```bash theme={null} 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](/es/reference/products/tracer/validate-transaction). *** ## 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: ```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" } ] }' ``` 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 ```bash theme={null} 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](./rule-engine.mdx). *** ## 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](./integration-guide.mdx)** - aprende a integrar tu sistema de autorización con Tracer * **[Motor de reglas](./rule-engine.mdx)** - escribe reglas de validación en CEL y administra su ciclo de vida * **[Límites de gasto](./spending-limits.mdx)** - configura y administra límites de gasto por alcance y período * **[Historial de validación y cumplimiento](./audit-compliance.mdx)** - 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](/es/reference/products/tracer/tracer-api-quick-start) 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](./rule-engine.mdx). * **Administrar 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, los esquemas de solicitud/respuesta y los 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 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.