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 para políticas e historial de validaciones. 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. Tracer queda fuera de tu ledger: nunca llama 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.

Midaz también puede accionar Tracer mediante un seam de reserva opcional por ledger. Sigue siendo unidireccional, Ledger → Tracer. El resto de esta guía cubre el patrón HTTP orquestado por la aplicación; el contrato del seam se documenta abajo.

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 — Figura 1. Visión general de la integración con Tracer

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.

Seam de reserva del Ledger Midaz

Este seam opt-in pertenece al HTTP v2 de Ledger, no al HTTP v2 de Tracer. El HTTP v1 de Ledger nunca lo invoca. La API HTTP pública de Tracer sigue siendo solo v1, incluidas sus operaciones de reserva bajo /v1. El servicio gRPC lerian.midaz.reservation.v1.ReservationService es un transporte interno entre servicios, no una API pública v2. Configura TRACER_BASE_URL para inyectar el seam; cuando no está configurado, el Ledger no hace llamadas de reserva. El cliente inyectado solo se usa cuando el tracer.mode por ledger es advisory o enforce; un modo no configurado u off omite las reservas incluso si TRACER_BASE_URL está configurado. Un skip por llamada autorizado también evita el seam. gRPC es el transporte predeterminado: configura TRACER_GRPC_PORT en Tracer y apunta TRACER_BASE_URL a ese listener gRPC. Con TRACER_TRANSPORT=rest, apúntalo al listener HTTP de Tracer. Ambos transportes usan el mismo servicio de reservas y las mismas cinco transiciones:

Transición	Acción de Ledger
`Reserve`	Retiene capacidad de límite antes de confirmar la transacción. Los reintentos son idempotentes en la granularidad `(transactionId, limitId, scopeKey, periodKey)`.
`ConfirmByTransaction`	Confirma todas las retenciones de una transacción; reintentar después del estado terminal es un no-op y puede devolver `flipped=0`.
`ReleaseByTransaction`	Devuelve todas las retenciones de una transacción; reintentar después del estado terminal es un no-op y puede devolver `flipped=0`.
`Confirm`	Confirma una retención; reintentar una reserva terminal es un no-op.
`Release`	Devuelve una retención; reintentar una reserva terminal es un no-op.

En llamadas multi-tenant, REST reenvía el tenant en el header X-Tenant-Id y gRPC lo reenvía como metadata x-tenant-id; ninguno de los dos transportes lo incluye en el mensaje de reserva. El listener solo puede confiar en este valor con mTLS directo o detrás de un sidecar verificado de service mesh. Con TRACER_TLS_MODE=mtls, cada lado presenta y verifica certificados. Los modos TLS mesh y vacío requieren un sidecar que aplique mTLS; sin él, la conexión entre el proceso y el listener usa texto plano y un caller no confiable puede falsificar el tenant. Tracer activa su listener gRPC solo cuando TRACER_GRPC_PORT está configurado. La semántica de fallos es explícita. Una denegación de reserva es una respuesta exitosa, no un error de transporte: advisory registra el resultado y continúa, mientras que enforce rechaza la transacción antes de cualquier movimiento de saldo, independientemente de failPosture. failPosture se aplica a cualquier error de la llamada de reserva: closed rechaza y open continúa sin una reserva. Los fallos de confirmación y liberación generan advertencias y no bloquean; el reaper de TTL de Tracer reconcilia una transición terminal perdida.

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
Almacenar el historial de validaciones para investigación e informes
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 — Figura 2. Flujo de integración con Tracer

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, código de activo, 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 correlacionar el historial de validaciones, 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 validación 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 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: 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 servicio de la plataforma de multi-tenancy en el momento de la solicitud.
Los endpoints públicos (/health, /readyz, /metrics, /version) 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). Un caso es distinto: un token que se parsea pero no lleva el claim sub se rechaza de entrada con HTTP 401 y el código de error 0474. El claim sub es lo que usa el escritor de auditoría para atribuir la acción a un principal, así que Tracer falla de forma explícita en lugar de registrar el cambio contra un actor de sistema genérico — asegúrate de que tus tokens de Access Manager siempre lo incluyan. 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 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.” 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 otra validación. 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.
“Las transacciones de prueba aparecen en el historial de validaciones 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 etiquetar 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:

Ejemplo de integración (pseudocódigo)

def validate_transaction(transaction):
    # Step 1: Enrich payload
    payload = {
        "requestId": generate_uuid(),
        "transactionType": transaction.type,
        "amount": transaction.amount,
        "asset": transaction.asset.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
Historial de validaciones y cumplimiento - Consulta el historial de validaciones y úsalo en tus procesos de cumplimiento

Resumen

Guías

Console

Operaciones

Guía de integración

Visión general de la integración

Seam de reserva del Ledger Midaz

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

​Seam de reserva del Ledger Midaz

​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

Seam de reserva del Ledger Midaz

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