Guía de integración

Integrar Tracer implica decidir en qué punto de tu flujo de autorización haces la llamada de validación, qué datos envías y cómo gestionas las tres decisiones posibles. El patrón es corto: tu sistema reúne el contexto completo de la transacción, llama a POST /v1/validations, actúa según ALLOW / DENY / REVIEW y continúa. Tracer nunca vuelve a entrar en tu stack. No hay webhooks ni callbacks, y la integración termina con la respuesta. Qué cambia en tu operación: la toma de decisiones pasa de una lógica en proceso a una llamada externa. La llamada es síncrona (solicitud/respuesta, sin webhooks), así que queda en la ruta crítica de la transacción. Bien implementada, agrega menos de 80ms p99 y te da un punto único para las políticas y el historial de validación. Mal implementada (sin timeout, sin estrategia de reintento, sin fallback), se convierte en un punto único de falla. Trade-off: agregas un salto de red. El contrato es simple: idempotente por requestId, sin callbacks, respuesta determinista de tres estados. Debes pensar en los timeouts, los reintentos y qué hacer si Tracer es inaccesible. La mayor parte de esta guía trata sobre eso.

¿Para quién es esta guía? Ingenieros de integración que escriben la solicitud desde tu sistema hacia Tracer, y arquitectos que deciden en qué punto del flujo va la llamada. Los analistas de riesgo y fraude que escriben reglas pueden ir directamente a la guía del motor de reglas. El equipo de compliance puede leer en su lugar la guía de auditoría y compliance.

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 presupuesto de latencia. Tracer se ubica fuera de tu ledger: nunca llama a Midaz. Tu aplicación orquesta ambos. Llama a Tracer para validar y envía la transacción a Midaz solo si la decisión es ALLOW. Tracer evalúa tus políticas y límites configurados contra el contexto que envías, no contra los saldos de las cuentas. El ledger sigue siendo la fuente de verdad de lo que tiene una cuenta.

Midaz también puede llamar a 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 aparece más abajo.

Resumen de la integración

Tracer espera llamadas de sistemas de autorización (gateways de pago, orquestadores de workflow 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. Resumen de la integración con Tracer

Tracer no busca datos externos durante la validación. Tu sistema debe proporcionar todo el contexto necesario para la evaluación de las reglas.

Seam de reserva de Midaz Ledger

Este seam opcional pertenece a Ledger HTTP v2. Ledger HTTP v1 nunca lo invoca. La API HTTP pública de Tracer es solo v1 y no tiene operaciones de reserva. Ledger llama al servicio gRPC lerian.midaz.reservation.v1.ReservationService. Este servicio es un transporte interno de servicio a servicio, no una API pública. Tracer siempre inicia este listener gRPC, en el puerto 4021 de forma predeterminada. Para usar otro puerto, define TRACER_GRPC_PORT con una dirección de escucha en el formato :4021. En Ledger, define TRACER_BASE_URL con la dirección del listener en el formato host:port. Cuando TRACER_BASE_URL no está definida, Ledger no hace ninguna llamada de reserva. Ledger llama a Tracer solo cuando el tracer.mode por ledger es advisory o enforce. Un modo no definido o off omite las reservas incluso cuando defines TRACER_BASE_URL. Un skip por llamada respetado también evita el seam. El seam tiene cinco transiciones:

Transición	Acción de Ledger
`Reserve`	Retiene capacidad de límite antes de que la transacción se confirme.
`ConfirmByTransaction`	Confirma cada hold de una transacción.
`ReleaseByTransaction`	Libera cada hold de una transacción.
`ConfirmById`	Confirma un hold.
`ReleaseById`	Libera un hold.

Orden de despliegue

Despliega Tracer antes de desplegar el Ledger de la misma versión de Midaz. Un Tracer anterior a v4.3.0 acepta solo los esquemas CARD, WIRE, PIX y CRYPTO. Rechaza una reserva con cualquier otro esquema. En modo enforce, el Ledger entonces rechaza la transacción con 0532. Un Tracer anterior a v4.3.0 tampoco puede leer una validación almacenada con cualquier otro esquema. Esto incluye un pod al que el despliegue gradual todavía no llegó. Después de que Tracer almacene una validación así, no regreses Tracer a una versión anterior a v4.3.0. Mientras se ejecute un Ledger de v4.2.0 o posterior, no regreses Tracer a una versión anterior a v4.2.0. Un Tracer anterior descarta el tipo de cuenta, los metadatos y el indicador de reversión de cada solicitud de reserva.

Reglas en una reserva

En cada Reserve, Tracer evalúa primero tus reglas activas, con el mismo evaluador que POST /v1/validations. Después reserva capacidad de límite. En una reserva, el valor predeterminado sin coincidencia no se aplica. Cuando ninguna regla coincide, la reserva continúa con la verificación de límites. Una reserva de reversión omite las reglas y aun así reserva capacidad de límite. La solicitud de reserva lleva el monto, el activo, el esquema de pago de la transacción, el timestamp de la transacción y los valores escalares de metadatos, como strings. También lleva el ID y el tipo de la primera cuenta de origen, y los ID del segmento y del portafolio de esa cuenta. No lleva merchant ni el nombre del segmento o del portafolio. Una reserva de reversión lleva el esquema de la transacción original. Los límites y las reglas con alcance por segmento, portafolio o esquema se aplican a la reserva. Una reserva sin esquema coincide solo con alcances que no indican esquema.

Resultados en Ledger

Una denegación de reserva es una respuesta exitosa, no un error de transporte. El modo advisory nunca bloquea la transacción. El modo enforce rechaza la transacción antes de cualquier movimiento de saldo:

Resultado de Tracer	Error de Ledger en modo `enforce`
Se excede un límite de gasto	`0177`
Una regla coincidente devuelve DENY	`0535`
Una regla coincidente devuelve REVIEW, o una regla no se puede evaluar	`0531`
Tracer rechaza la solicitud de reserva	`0532`, para cada `failPosture`
Tracer no está disponible	`0178` cuando `failPosture` es `closed`. Con `open`, la transacción continúa sin una reserva.

Con la postura abierta, Ledger también continúa sin verificaciones de reglas ni de límites cuando Tracer rechaza las credenciales de Ledger. Ledger también puede devolver 0536 para una reserva. La lista de errores de Midaz describe cada código. Las fallas de confirmación y liberación no bloquean la transacción.

Patrón Payload-Complete

Tracer usa el Patrón Payload-Complete. Cada solicitud debe llevar todo el contexto necesario para la validación. Este diseño garantiza:

Beneficio	Descripción
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 actualidad de los datos y la lógica de enriquecimiento

Tus responsabilidades

Como sistema que se integra, 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
Gestionar la decisión (ALLOW, DENY o REVIEW) de forma adecuada en tu workflow
Implementar lógica de reintento si Tracer no está disponible temporalmente
Gestionar los workflows 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 (por ejemplo, estado de la cuenta, membresía de segmento), las reglas que dependen de esos datos no pueden evaluarse correctamente. Confirma siempre que los payloads estén completos antes de enviarlos.

Responsabilidades de Tracer

Tracer es responsable de:

Evaluar las reglas según el contexto proporcionado
Verificar los límites según el uso actual
Almacenar el historial de validación 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, reúne todos los datos relevantes de tus sistemas:

Pasos para preparar el contexto de la transacción y llamar a Tracer, desde reunir los datos en tus sistemas hasta actuar según la decisión devuelta — Figura 2. Preparación del contexto de la transacción

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 (scheme, subType, amount, asset, timestamp)
Información de la cuenta (obligatorio)
Opcional: segmento, portafolio, comercio y personalizados

Para ver la estructura completa del payload y el detalle de los campos, consulta la referencia de la API.

Paso 3: Gestionar la respuesta

Procesa la decisión que devuelve Tracer:

Decisión	Acción
`ALLOW`	Continúa con la transacción
`DENY`	Rechaza la transacción; muestra el motivo al usuario si corresponde
`REVIEW`	Ponla en cola para revisión manual en tu sistema de revisión

La respuesta incluye el validationId para correlacionar con el historial de validación, detalles sobre qué reglas coincidieron e información sobre el uso actual de los límites.

Uso de metadatos

Los metadatos permiten pasar campos personalizados que tus reglas pueden evaluar. Úsalos para contexto como el canal, la información del dispositivo, el nivel del cliente o cualquier atributo específico del negocio.

Las claves de metadatos deben ser alfanuméricas, con guiones bajos como único carácter adicional permitido, y un máximo de 64 caracteres. Máximo de 50 entradas por solicitud.

Idempotencia de la solicitud

Las solicitudes de validación son idempotentes según el campo requestId. Si envías el mismo requestId dos veces, Tracer devuelve el resultado en caché de la primera solicitud en lugar de reprocesarla.

Código de respuesta	Significado
`201 Created`	Nueva validación procesada
`200 OK`	Solicitud duplicada detectada; se devuelve el resultado en caché

El cuerpo de la respuesta es idéntico en ambos casos. Se recomienda que tu cliente trate ambos códigos de estado como éxito. Los timeouts de red y los reintentos pueden causar solicitudes duplicadas. Sin idempotencia, una solicitud reintentada podría contarse dos veces contra los límites o crear registros de validación duplicados. El requestId garantiza una 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 transacción nueva. Reutilizar un requestId de una transacción anterior devolverá el resultado antiguo, no procesará la transacción nueva.

Validación solo por reglas

POST /v1/validations/rules-only recibe la misma solicitud que POST /v1/validations y devuelve la misma respuesta y los mismos errores. Tracer decide solo por tus reglas y no verifica ni cuenta ningún límite de gasto. Usa esta ruta para evaluar un crédito entrante sin consumir un límite. Las dos rutas comparten un único espacio de requestId. Un requestId ya usado en cualquiera de las dos rutas devuelve la decisión registrada para él, así que nunca reutilices un requestId entre las dos rutas. Tracer almacena una validación solo por reglas como cualquier otra. Aparece en GET /v1/validations y en las cifras del dashboard. Solo la instantánea de la solicitud en su evento de auditoría la marca, con rulesOnly: true.

Autenticación

Tracer admite dos modos de autenticación. Puedes usarlos de forma independiente o juntos.

Autenticación por clave de API

La opción más simple. Envía tu clave de API en el header X-API-Key con cada solicitud.

Variable de entorno	Descripción
`API_KEY_ENABLED`	Habilita la autenticación por clave de API (predeterminado: `false`)
`API_KEY`	El valor de la clave secreta
`API_KEY_ENABLED_ONLY_VALIDATION`	Usa la autenticación por clave de API, no la autenticación por plugin, en `POST /v1/validations` y `POST /v1/validations/rules-only` (predeterminado: `false`)

Autenticación por plugin (Access Manager)

Tracer puede delegar la autenticación al Lerian Access Manager. Esto permite la autenticación centralizada en todos los servicios de Lerian.

Variable de entorno	Descripción
`PLUGIN_AUTH_ENABLED`	Habilita la autenticación por plugin (predeterminado: `false`)
`PLUGIN_AUTH_ADDRESS`	URL del servicio de autenticación (predeterminado: `http://localhost:4000`)

Prioridad de autenticación

Cuando habilitas ambos modos, Tracer usa esta prioridad:

Si PLUGIN_AUTH_ENABLED=true y el endpoint no tiene la flag de solo clave de API → autenticación por plugin
Si API_KEY_ENABLED=true o el endpoint lleva la flag de solo clave de API → autenticación por clave de API

Los endpoints de infraestructura (health checks, sondeo de versión, especificación de OpenAPI) omiten la autenticación y no forman parte de la superficie pública de la API /v1/* documentada en esta referencia.

Puedes configurar POST /v1/validations y POST /v1/validations/rules-only para autenticación de solo clave de API mediante API_KEY_ENABLED_ONLY_VALIDATION=true. Esas rutas verifican entonces la clave de API solo cuando API_KEY_ENABLED=true. Esto resulta útil en escenarios de alto rendimiento donde la autenticación por plugin agrega una latencia inaceptable.

Autenticación en Lerian Cloud

En Lerian Cloud, la autenticación funciona así:

Cada solicitud a /v1/* debe llevar un token bearer JWT emitido por Access Manager: Authorization: Bearer <jwt>.
tenantId proviene del claim del JWT, no de un header, path, body, metadatos o alcance de regla. No existe un header X-Tenant-ID. El identificador del tenant no tiene efecto en ningún otro lugar más allá del claim del token.

Un token que se analiza correctamente pero no lleva el claim sub devuelve HTTP 401 y el código de error 0474 de inmediato. El claim sub es lo que el escritor de auditoría usa para atribuir la acción a un principal. Tracer falla de forma explícita en lugar de registrar el cambio contra un actor de sistema genérico. Confirma que tus tokens de Access Manager siempre lo lleven. Si el servicio está temporalmente al límite de capacidad para tu tenant, las solicitudes devuelven HTTP 503 con el código de error 0466 y un header Retry-After. Aplica backoff y reintenta.

Consideraciones de rendimiento

Optimiza tu integración para baja latencia y alta confiabilidad.

Presupuesto de timeout

Tracer apunta a responder en menos de 80ms (p99). Configura el timeout de tu cliente en consecuencia:

Configuración	Valor recomendado
Timeout del cliente	100ms
Timeout de conexión	50ms
Timeout de lectura	100ms

Estrategia de reintento

Implementa lógica de reintento para fallas transitorias:

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 de nuevo. Para los reintentos en 5xx/timeout, reutiliza el mismo requestId para aprovechar la idempotencia.

Comportamiento de fallback

Decide qué sucede cuando Tracer no está disponible:

Estrategia	Cuándo usarla
Fail-open	Permite la transacción si Tracer está caído (prioriza la disponibilidad)
Fail-closed	Deniega la transacción si Tracer está caído (prioriza la seguridad)
Queue for review	Pone la transacción en cola para revisión manual

Tu elección depende de tu tolerancia al riesgo y de los requisitos del negocio.

Errores comunes de integración:

“Mi reintento creó una validación duplicada.” Reutiliza el mismo requestId en 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 reintento, anulas la idempotencia.
“Mi cliente hace timeout a los 30 segundos, pero Tracer sigue procesando.” Tracer respeta sus propios plazos (meta de ~80ms p99). Si tu cliente abandona la llamada, Tracer de todas formas invierte ese trabajo en una respuesta. Configura el timeout del cliente de forma agresiva (100ms) y confía en la ruta de reintento.
“Tracer rechaza mi validación con el código de error 0421 (timestamp demasiado antiguo) en transacciones legítimas.” La tolerancia predeterminada es de 24 horas. Verifica el reloj de tu servidor y el transactionTimestamp que envías. Si procesas por lotes con retraso, define el timestamp en el momento real de la transacción, no en el momento en que llamas a Tracer.
“Las transacciones de prueba aparecen en el historial de validación de producción.” Tracer también registra las validaciones de entornos de prueba o staging que llaman a la misma instancia de Tracer. Usa metadata.environment (o algo similar) para etiquetar y filtrar el tráfico de prueba si compartes Tracer entre entornos.

Actualidad de los datos

Como tú controlas el enriquecimiento del payload, la actualidad de los datos es tu responsabilidad. Tracer confía en los datos que proporcionas y no puede detectar información desactualizada.

Tipo de dato	Recomendación de actualidad	Riesgo si está desactualizado
Estado de la cuenta	Tiempo real o casi en tiempo real	Se pueden permitir transacciones en cuentas suspendidas
Membresía de segmento	Se puede almacenar en caché (cambia con poca frecuencia)	Se pueden aplicar límites o reglas incorrectos
Asignación de portafolio	Se puede almacenar en caché (cambia con poca frecuencia)	Coincidencia de alcance incorrecta
Datos del comercio	Se puede almacenar en caché con actualización periódica	Es posible que las reglas de riesgo no se activen correctamente

Los datos desactualizados generan decisiones incorrectas. Si suspendiste una cuenta pero tu caché la muestra como activa, Tracer permitirá transacciones que se recomienda denegar. 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 el 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 pasar a producción, verifica lo siguiente:

Ejemplo de integración (pseudocódigo)

def validate_transaction(transaction):
    # Step 1: Enrich payload
    payload = {
        "requestId": generate_uuid(),
        "scheme": transaction.scheme,
        "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úen el contexto que proporcionas
Límites de gasto - Configura límites que se apliquen a los alcances de tus transacciones
Historial de validación y compliance - Consulta el historial de validación y úsalo en tus procesos de compliance

Resumen

Guías

Console

Operaciones

Guía de integración

Resumen de la integración

Seam de reserva de Midaz Ledger

Orden de despliegue

Reglas en una reserva

Resultados en Ledger

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: Gestionar la respuesta

Uso de metadatos

Idempotencia de la solicitud

Validación solo por reglas

Autenticación

Autenticación por clave de API

Autenticación por plugin (Access Manager)

Prioridad de autenticación

Autenticación en Lerian Cloud

Consideraciones de rendimiento

Presupuesto de timeout

Estrategia de reintento

Comportamiento de fallback

Actualidad de los datos

Formato de fecha y hora

Lista de verificación de integración

Ejemplo de integración (pseudocódigo)

Próximos pasos

​Resumen de la integración

​Seam de reserva de Midaz Ledger

​Orden de despliegue

​Reglas en una reserva

​Resultados en Ledger

​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: Gestionar la respuesta

​Uso de metadatos

​Idempotencia de la solicitud

​Validación solo por reglas

​Autenticación

​Autenticación por clave de API

​Autenticación por plugin (Access Manager)

​Prioridad de autenticación

​Autenticación en Lerian Cloud

​Consideraciones de rendimiento

​Presupuesto de timeout

​Estrategia de reintento

​Comportamiento de fallback

​Actualidad de los datos

​Formato de fecha y hora

​Lista de verificación de integración

​Ejemplo de integración (pseudocódigo)

​Próximos pasos

Resumen de la integración

Seam de reserva de Midaz Ledger

Orden de despliegue

Reglas en una reserva

Resultados en Ledger

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: Gestionar la respuesta

Uso de metadatos

Idempotencia de la solicitud

Validación solo por reglas

Autenticación

Autenticación por clave de API

Autenticación por plugin (Access Manager)

Prioridad de autenticación

Autenticación en Lerian Cloud

Consideraciones de rendimiento

Presupuesto de timeout

Estrategia de reintento

Comportamiento de fallback

Actualidad de los datos

Formato de fecha y hora

Lista de verificación de integración

Ejemplo de integración (pseudocódigo)

Próximos pasos