> ## 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. # Guía de integración > Cómo integrar tu sistema de autorización con Tracer para validación de transacciones en tiempo real. export const GMetadata = ({children}) => {children} ; Integrar Tracer significa decidir en qué punto de tu flujo de autorización hacer la llamada de validación, qué datos enviar y cómo tratar las tres decisiones posibles. El patrón es corto: tu sistema recopila el contexto completo de la transacción, llama a `POST /v1/validations`, actúa sobre ALLOW / DENY / REVIEW y sigue adelante. Tracer nunca vuelve a llamar a tu stack — no hay webhooks ni callbacks; la integración termina con la respuesta. **Qué cambia en tu operación:** la decisión sale de lógica in-process y va a una llamada externa. La llamada es síncrona (request/response, sin webhooks), así que queda en el camino crítico de la transacción. Bien hecha, agrega menos de 80ms p99 y te da un punto único de política y auditoría. Mal hecha — sin timeout, sin retry, sin fallback — se vuelve un punto único de falla. **El trade-off honesto:** estás agregando un hop de red. La buena noticia es que el contrato es simple: idempotente por `requestId`, sin callbacks, respuesta determinística de tres estados. La mala noticia es que tienes que pensar en timeouts, retries y qué hacer si Tracer no está disponible — la mayor parte de esta guía es sobre eso. **¿Para quién es esta guía?** Ingenieros de integración escribiendo la solicitud desde tu sistema a Tracer, y arquitectos decidiendo dónde queda la llamada en el flujo. Analistas de riesgo/fraude que escriben reglas pueden saltar a la [Guía del motor de reglas](./rule-engine.mdx); compliance puede leer la [Guía de auditoría y cumplimiento](./audit-compliance.mdx). Esta guía cubre los requisitos del payload, el flujo de integración y las prácticas que mantienen la llamada de validación dentro de tu budget de latencia. Tracer queda **fuera** de tu ledger: nunca se conecta a Midaz. Tu aplicación orquesta ambos — llama a Tracer para validar, y solo envía la transacción a Midaz si la decisión es `ALLOW`. Tracer evalúa tus **políticas y límites** configurados contra el contexto que envías, no los saldos de las cuentas — el ledger sigue siendo la fuente de verdad de lo que una cuenta tiene. ## Visión general de la integración *** Tracer está diseñado para ser llamado por **sistemas de autorización** (pasarelas de pago, orquestadores de flujo de trabajo o procesadores de transacciones) que necesitan decisiones de validación en tiempo real. La integración sigue un patrón simple de solicitud-respuesta: Integración de solicitud-respuesta en la que un sistema de autorización llama a Tracer para obtener una decisión de validación y solo envía la transacción a Midaz cuando la decisión es ALLOW **Principio clave:** Tracer no obtiene datos externos durante la validación. Tu sistema es responsable de proporcionar todo el contexto necesario para la evaluación de reglas. *** ## Patrón Payload-Complete *** Tracer utiliza el **Patrón Payload-Complete**, lo que significa que todo el contexto requerido para la validación debe incluirse en la solicitud. Este diseño asegura: | Beneficio | Descripción | | ----------------------- | -------------------------------------------------------------------------------------------------- | | **Latencia predecible** | Sin llamadas externas durante la validación; el tiempo de respuesta se mantiene por debajo de 80ms | | **Simplicidad** | Una sola solicitud contiene todo lo necesario para la decisión | | **Confiabilidad** | Sin dependencia de servicios externos durante la validación | | **Flexibilidad** | Tu sistema controla la frescura de los datos y la lógica de enriquecimiento | ### Tus responsabilidades Como sistema integrador, eres responsable de: 1. **Enriquecer el payload** con datos de cuenta, segmento, portafolio y comercio antes de llamar a Tracer 2. **Proporcionar contexto preciso** para la evaluación de reglas y límites—Tracer no puede obtener datos faltantes 3. **Manejar la decisión** (ALLOW, DENY o REVIEW) apropiadamente en tu flujo de trabajo 4. **Implementar lógica de reintento** si Tracer no está disponible temporalmente 5. **Gestionar flujos de revisión** cuando Tracer devuelve `REVIEW`—Tracer no incluye gestión de casos Tracer valida lo que envías. Si tu payload carece de contexto (ej., estado de la cuenta, membresía de segmento), las reglas que dependen de esos datos no pueden evaluar correctamente. Siempre asegúrate de que los payloads estén completos antes del envío. ### Responsabilidades de Tracer Tracer es responsable de: 1. **Evaluar reglas** contra el contexto proporcionado 2. **Verificar límites** contra el uso actual 3. **Registrar el rastro de auditoría** para cumplimiento 4. **Devolver la decisión** con información detallada *** ## Flujo de integración *** Sigue estos pasos para integrar tu sistema con Tracer. ### Paso 1: Preparar el contexto de la transacción Antes de llamar a Tracer, recopila todos los datos relevantes de tus sistemas: Pasos para preparar el contexto de la transacción y llamar a Tracer, desde reunir los datos de tus sistemas hasta actuar según la decisión devuelta ### Paso 2: Llamar a la API de Tracer Envía una solicitud POST a `/v1/validations` con el contexto completo de la transacción incluyendo: * Detalles de la transacción (tipo, subTipo, monto, moneda, timestamp) * Información de la cuenta (requerido) * Opcional: segmento, portafolio, comercio y metadata personalizada Para la estructura completa del payload y detalles de campos, consulta la [Referencia de API](/es/reference/tracer/validate-transaction). ### Paso 3: Manejar la respuesta Procesa la decisión devuelta por Tracer: | Decisión | Acción | | -------- | --------------------------------------------------------------------- | | `ALLOW` | Proceder con la transacción | | `DENY` | Rechazar la transacción; mostrar el motivo al usuario si es apropiado | | `REVIEW` | Poner en cola para revisión manual en tu sistema de revisión | La respuesta incluye el `validationId` para correlación del rastro de auditoría, detalles sobre qué reglas coincidieron e información del uso actual del límite. ### Usando metadata Metadata te permite pasar campos personalizados que tus reglas pueden evaluar. Usa esto para contexto como canal, información del dispositivo, nivel del cliente o cualquier atributo específico del negocio. Las claves de metadata deben ser alfanuméricas con guiones bajos solamente, máximo 64 caracteres. Máximo 50 entradas por solicitud. *** ## Idempotencia de solicitudes *** Las solicitudes de validación son **idempotentes** basadas en el campo `requestId`. Si envías el mismo `requestId` dos veces, Tracer devuelve el resultado en caché de la primera solicitud en lugar de procesarla de nuevo. | Código de respuesta | Significado | | ------------------- | ---------------------------------------------------------- | | `201 Created` | Validación nueva procesada | | `200 OK` | Solicitud duplicada detectada; resultado en caché devuelto | El cuerpo de la respuesta es idéntico en ambos casos. Tu cliente debe tratar ambos códigos de estado como éxito. **Por qué importa:** timeouts de red y reintentos pueden causar solicitudes duplicadas. Sin idempotencia, una solicitud reintentada podría contar doble contra los límites o crear registros de auditoría duplicados. El `requestId` garantiza semántica de procesamiento exactamente-una-vez. **Contrato de idempotencia:** * Mismo `requestId` → misma respuesta (garantizado) * `requestId` diferente → procesamiento independiente (incluso si los datos de la transacción son idénticos) Genera siempre un `requestId` único (UUID) para cada nueva transacción. Reutilizar un `requestId` de una transacción anterior devolverá el resultado antiguo, no procesará la nueva transacción. *** ## Autenticación *** Tracer soporta dos modos de autenticación que pueden usarse independientemente o combinados. ### Autenticación por API key La opción más simple. Envía tu API key en el encabezado `X-API-Key` en cada solicitud. | Variable de entorno | Descripción | | --------------------------------- | ----------------------------------------------------------------------------- | | `API_KEY_ENABLED` | Habilita la autenticación por API key (predeterminado: `false`) | | `API_KEY` | El valor de la clave secreta | | `API_KEY_ENABLED_ONLY_VALIDATION` | Usa API key solo para el endpoint `/v1/validations` (predeterminado: `false`) | ### Autenticación por plugin (Access Manager) Para despliegues enterprise, Tracer puede delegar la autenticación al [Lerian Access Manager](/es/platform/access-manager/auth-plugin). Esto habilita autenticación centralizada entre todos los servicios Lerian. | Variable de entorno | Descripción | | --------------------- | --------------------------------------------------------------------------- | | `PLUGIN_AUTH_ENABLED` | Habilita autenticación por plugin (predeterminado: `false`) | | `PLUGIN_AUTH_ADDRESS` | URL del servicio de autenticación (predeterminado: `http://localhost:4000`) | ### Prioridad de autenticación Cuando ambos modos están habilitados, Tracer usa esta prioridad: 1. Si `PLUGIN_AUTH_ENABLED=true` y el endpoint no está marcado para API-key-only → Autenticación por plugin 2. Si `API_KEY_ENABLED=true` o el endpoint está marcado para API-key-only → Autenticación por API key Los endpoints de infraestructura (health checks, sonda de versión, spec OpenAPI) omiten autenticación y no forman parte de la superficie pública `/v1/*` documentada en esta referencia. El endpoint `/v1/validations` puede configurarse para autenticación solo por API key vía `API_KEY_ENABLED_ONLY_VALIDATION=true`. Es útil en escenarios de alto throughput donde la autenticación por plugin agrega latencia inaceptable. **Esta flag es incompatible con el modo multi-tenant** (`MULTI_TENANT_ENABLED=true`) — el servicio no inicia, fallando con el código de error `0458`. ### Autenticación multi-tenant Cuando `MULTI_TENANT_ENABLED=true`, Tracer cambia su modelo de autenticación: * **Plugin auth es obligatorio.** El servicio falla al iniciar con el código de error `0457` si `PLUGIN_AUTH_ENABLED=false`. * **Toda solicitud `/v1/*` debe llevar un JWT bearer token** emitido por [Access Manager](/es/platform/access-manager/access-manager): `Authorization: Bearer `. * **El `tenantId` se resuelve a partir del claim del JWT**, no de un encabezado, path, body, metadata o alcance de regla. No existe encabezado `X-Tenant-ID` — pasar el identificador del tenant en cualquier otro lugar que no sea el claim del token no es soportado y se ignora. * Cada tenant opera en su propia base de datos PostgreSQL. La conexión específica del tenant es resuelta por el servicio de la plataforma de multi-tenancy en el momento de la solicitud. * **Los endpoints públicos (`/health`, `/readyz`, `/version`, `/swagger/*`) permanecen sin autenticación** también en modo multi-tenant — el requisito del bearer token aplica solo a `/v1/*`. Si el JWT está ausente, malformado o expirado, la solicitud retorna HTTP 401 con `"code": "Unauthenticated"` (el mismo código usado cuando falta la API key; no se emite un código TRC separado). Si el despliegue multi-tenant alcanza su límite de tenants activos por instancia, las solicitudes para tenants fríos retornan HTTP 503 con el código de error `0466` y un encabezado `Retry-After`. El cliente debe hacer backoff y reintentar; el límite se restablece automáticamente conforme el pool LRU desaloja tenants fríos. Consulta [Multi-tenancy](/es/multi-tenancy) para el modelo de tenants de la plataforma. *** ## Consideraciones de rendimiento *** Optimiza tu integración para baja latencia y alta confiabilidad. ### Presupuesto de tiempo de espera Tracer está diseñado para responder en menos de **80ms (p99)**. Configura el tiempo de espera de tu cliente en consecuencia: | Configuración | Valor recomendado | | ---------------------------- | ----------------- | | Tiempo de espera del cliente | 100ms | | Tiempo de espera de conexión | 50ms | | Tiempo de espera de lectura | 100ms | ### Estrategia de reintento Implementa lógica de reintento para fallos transitorios: ``` On 5xx error or timeout: - Wait 10ms - Retry once - If still failing, apply fallback policy ``` No reintentes en errores 4xx; estos indican solicitudes inválidas que fallarán nuevamente. ### Comportamiento de respaldo Decide qué sucede cuando Tracer no está disponible: | Estrategia | Cuándo usar | | ------------------------------- | ----------------------------------------------------------------------- | | **Fail-open** | Permitir la transacción si Tracer está caído (priorizar disponibilidad) | | **Fail-closed** | Denegar la transacción si Tracer está caído (priorizar seguridad) | | **Poner en cola para revisión** | Poner la transacción en cola para revisión manual | Tu elección depende de tu tolerancia al riesgo y requisitos de negocio. **Tropezones comunes en la integración:** * **"Mi reintento creó una validación duplicada en el rastro de auditoría."** Reutiliza el mismo `requestId` en todos los reintentos. Tracer deduplica por ese campo — la segunda llamada devuelve el resultado en caché (HTTP 200) sin crear un evento duplicado. Si generas un UUID nuevo en cada retry, pierdes la idempotencia. * **"Mi cliente tiene timeout de 30 segundos pero Tracer sigue procesando."** Tracer respeta sus propios deadlines (objetivo \~80ms p99). Si tu cliente se rinde en la llamada, el trabajo de Tracer ya se va a desperdiciar al retornar la respuesta. Configura el timeout del cliente agresivamente (100ms) y confía en el camino de retry. * **"Mi validación está siendo rechazada con el código de error `0421` (timestamp demasiado antiguo) en transacciones legítimas."** La tolerancia predeterminada es 24 horas. Verifica el reloj del servidor y el `transactionTimestamp` que estás enviando — si procesas en batch con atraso, necesitas setear el timestamp al momento real de la transacción, no al momento de la llamada a Tracer. * **"Transacciones de prueba aparecen en la auditoría de producción."** Todas las validaciones se registran, incluidas las de entornos de prueba/staging que llaman a la misma instancia de Tracer. Usa `metadata.environment` (o similar) para taguear y filtrar tráfico de prueba si compartes Tracer entre entornos. *** ## Frescura de los datos *** Dado que tú controlas el enriquecimiento del payload, la frescura de los datos es tu responsabilidad. Tracer confía en los datos que proporcionas y no puede detectar información obsoleta. | Tipo de dato | Recomendación de frescura | Riesgo si obsoleto | | ------------------------ | ----------------------------------------------- | -------------------------------------------------------------- | | Estado de la cuenta | Tiempo real o casi tiempo real | Las transacciones en cuentas suspendidas pueden ser permitidas | | Membresía de segmento | Puede ser cacheado (cambia con poca frecuencia) | Límites o reglas incorrectas pueden aplicarse | | Asignación de portafolio | Puede ser cacheado (cambia con poca frecuencia) | Coincidencia de alcance incorrecta | | Datos del comercio | Puede ser cacheado con actualización periódica | Las reglas de riesgo pueden no activarse correctamente | Los datos obsoletos llevan a decisiones incorrectas. Si una cuenta fue suspendida pero tu cache la muestra como activa, Tracer permitirá transacciones que deberían ser denegadas. Tu capa de enriquecimiento es la fuente de verdad para Tracer. *** ## Formato de fecha y hora *** Todos los campos de fecha y hora deben usar **formato RFC3339** con zona horaria obligatoria: **Formatos válidos:** ``` 2026-01-30T10:30:00Z (UTC) 2026-01-30T10:30:00-03:00 (São Paulo timezone) 2026-01-30T00:00:00+00:00 (UTC explicit) ``` **Formatos inválidos:** ``` 2026-01-30 (date only - rejected) 2026-01-30T10:30:00 (missing timezone - rejected) ``` *** ## Lista de verificación de integración *** Antes de ir a producción, verifica: * [ ] API Key está configurada y segura * [ ] Tiempo de espera del cliente está configurado en 100ms * [ ] Lógica de reintento está implementada para errores 5xx * [ ] Comportamiento de respaldo está definido * [ ] Todos los campos requeridos están poblados * [ ] Las marcas de tiempo usan formato RFC3339 con zona horaria * [ ] Los códigos de moneda son mayúsculas ISO 4217 * [ ] El manejo de decisiones está implementado (ALLOW/DENY/REVIEW) * [ ] Los IDs de validación se registran para correlación del rastro de auditoría *** ## Ejemplo de integración (pseudocódigo) *** ```python theme={null} def validate_transaction(transaction): # Step 1: Enrich payload payload = { "requestId": generate_uuid(), "transactionType": transaction.type, "amount": transaction.amount, "currency": transaction.currency.upper(), "transactionTimestamp": now_rfc3339(), "account": get_account_context(transaction.account_id), "segment": get_segment_context(transaction.segment_id), "merchant": get_merchant_context(transaction.merchant_id), "metadata": transaction.custom_fields } # Step 2: Call Tracer try: response = http_post( url="https://tracer.example.com/v1/validations", headers={"X-API-Key": API_KEY}, json=payload, timeout_ms=100 ) except Timeout: return apply_fallback_policy() except ServerError: return retry_once_or_fallback() # Step 3: Handle decision if response.decision == "ALLOW": return proceed_with_transaction() elif response.decision == "DENY": return reject_transaction(response.reason) elif response.decision == "REVIEW": return queue_for_manual_review(response.validationId) ``` *** ## Próximos pasos *** * **[Motor de reglas](./rule-engine.mdx)** - Crea reglas que evalúan contra el contexto que proporcionas * **[Límites de gasto](./spending-limits.mdx)** - Configura límites que se aplican a los alcances de tus transacciones * **[Auditoría y cumplimiento](./audit-compliance.mdx)** - Consulta el historial de validaciones y el rastro de auditoría