Guía de integración

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; compliance puede leer la Guía de auditoría y cumplimiento.

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.

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:

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:

Enriquecer el payload con datos de cuenta, segmento, portafolio y comercio antes de llamar a Tracer
Proporcionar contexto preciso para la evaluación de reglas y límites—Tracer no puede obtener datos faltantes
Manejar la decisión (ALLOW, DENY o REVIEW) apropiadamente en tu flujo de trabajo
Implementar lógica de reintento si Tracer no está disponible temporalmente
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:

Evaluar reglas contra el contexto proporcionado
Verificar límites contra el uso actual
Registrar el rastro de auditoría para cumplimiento
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:

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 personalizada

Para la estructura completa del payload y detalles de campos, consulta la Referencia de API.

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

Si PLUGIN_AUTH_ENABLED=true y el endpoint no está marcado para API-key-only → Autenticación por plugin
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 TRC-0327.

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 TRC-0326 si PLUGIN_AUTH_ENABLED=false.
Toda solicitud /v1/* debe llevar un JWT bearer token emitido por Access Manager: Authorization: Bearer <jwt>.
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 Tenant Manager de la plataforma 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 TRC-0335 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 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 TRC-0228 (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)

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 - Crea reglas que evalúan contra el contexto que proporcionas
Límites de gasto - Configura límites que se aplican a los alcances de tus transacciones
Auditoría y cumplimiento - Consulta el historial de validaciones y el rastro de auditoría

​Visión general de la integración

​Patrón Payload-Complete

​Tus responsabilidades

​Responsabilidades de Tracer

​Flujo de integración

​Paso 1: Preparar el contexto de la transacción

​Paso 2: Llamar a la API de Tracer

​Paso 3: Manejar la respuesta

​Usando metadata

​Idempotencia de solicitudes

​Autenticación

​Autenticación por API key

​Autenticación por plugin (Access Manager)

​Prioridad de autenticación

​Autenticación multi-tenant

​Consideraciones de rendimiento

​Presupuesto de tiempo de espera

​Estrategia de reintento

​Comportamiento de respaldo

​Frescura de los datos

​Formato de fecha y hora

​Lista de verificación de integración

​Ejemplo de integración (pseudocódigo)

​Próximos pasos

Visión general de la integración

Patrón Payload-Complete

Tus responsabilidades

Responsabilidades de Tracer

Flujo de integración

Paso 1: Preparar el contexto de la transacción

Paso 2: Llamar a la API de Tracer

Paso 3: Manejar la respuesta

Usando metadata

Idempotencia de solicitudes

Autenticación

Autenticación por API key

Autenticación por plugin (Access Manager)

Prioridad de autenticación

Autenticación multi-tenant

Consideraciones de rendimiento

Presupuesto de tiempo de espera

Estrategia de reintento

Comportamiento de respaldo

Frescura de los datos

Formato de fecha y hora

Lista de verificación de integración

Ejemplo de integración (pseudocódigo)

Próximos pasos