Guía de integración

Esta guía explica cómo integrar sistemas externos con Tracer, incluyendo los requisitos del payload, el flujo de integración y las mejores prácticas para lograr un rendimiento óptimo.

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

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.

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(),
        "timestamp": 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

​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

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