Guia de integracion

Esta guia explica como integrar sistemas externos con Tracer, incluyendo los requisitos del payload, el flujo de integracion y las mejores practicas para lograr un rendimiento optimo.

Vision general de la integracion

Tracer esta disenado para ser llamado por sistemas de autorizacion (pasarelas de pago, orquestadores de flujo de trabajo o procesadores de transacciones) que necesitan decisiones de validacion en tiempo real. La integracion sigue un patron simple de solicitud-respuesta:

Principio clave: Tracer no obtiene datos externos durante la validacion. Tu sistema es responsable de proporcionar todo el contexto necesario para la evaluacion de reglas.

Patron Payload-Complete

Tracer utiliza el Patron Payload-Complete, lo que significa que todo el contexto requerido para la validacion debe incluirse en la solicitud. Este diseno asegura:

Beneficio	Descripcion
Latencia predecible	Sin llamadas externas durante la validacion; el tiempo de respuesta se mantiene por debajo de 80ms
Simplicidad	Una sola solicitud contiene todo lo necesario para la decision
Confiabilidad	Sin dependencia de servicios externos durante la validacion
Flexibilidad	Tu sistema controla la frescura de los datos y la logica 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 evaluacion de reglas y limites—Tracer no puede obtener datos faltantes
Manejar la decision (ALLOW, DENY o REVIEW) apropiadamente en tu flujo de trabajo
Implementar logica de reintento si Tracer no esta disponible temporalmente
Gestionar flujos de revision cuando Tracer devuelve REVIEW—Tracer no incluye gestion de casos

Tracer valida lo que envias. Si tu payload carece de contexto (ej., estado de la cuenta, membresia de segmento), las reglas que dependen de esos datos no pueden evaluar correctamente. Siempre asegurate de que los payloads esten completos antes del envio.

Responsabilidades de Tracer

Tracer es responsable de:

Evaluar reglas contra el contexto proporcionado
Verificar limites contra el uso actual
Registrar el rastro de auditoria para cumplimiento
Devolver la decision con informacion 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 esta disenado para responder en menos de 80ms (p99). Configura el tiempo de espera de tu cliente en consecuencia:

Configuracion	Valor recomendado
Tiempo de espera del cliente	100ms
Tiempo de espera de conexion	50ms
Tiempo de espera de lectura	100ms

Estrategia de reintento

Implementa logica 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 invalidas que fallaran nuevamente.

Comportamiento de respaldo

Decide que sucede cuando Tracer no esta disponible:

Estrategia	Cuando usar
Fail-open	Permitir la transaccion si Tracer esta caido (priorizar disponibilidad)
Fail-closed	Denegar la transaccion si Tracer esta caido (priorizar seguridad)
Poner en cola para revision	Poner la transaccion en cola para revision manual

Tu eleccion depende de tu tolerancia al riesgo y requisitos de negocio.

Frescura de los datos

Dado que tu controlas el enriquecimiento del payload, la frescura de los datos es tu responsabilidad. Tracer confia en los datos que proporcionas y no puede detectar informacion obsoleta.

Tipo de dato	Recomendacion de frescura	Riesgo si obsoleto
Estado de la cuenta	Tiempo real o casi tiempo real	Las transacciones en cuentas suspendidas pueden ser permitidas
Membresia de segmento	Puede ser cacheado (cambia con poca frecuencia)	Limites o reglas incorrectas pueden aplicarse
Asignacion de portafolio	Puede ser cacheado (cambia con poca frecuencia)	Coincidencia de alcance incorrecta
Datos del comercio	Puede ser cacheado con actualizacion periodica	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 permitira transacciones que deberian 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 validos:

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

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 produccion, verifica:

API Key esta configurada y segura
Tiempo de espera del cliente esta configurado en 100ms
Logica de reintento esta implementada para errores 5xx
Comportamiento de respaldo esta definido
Todos los campos requeridos estan poblados
Las marcas de tiempo usan formato RFC3339 con zona horaria
Los codigos de moneda son mayusculas ISO 4217
El manejo de decisiones esta implementado (ALLOW/DENY/REVIEW)
Los IDs de validacion se registran para correlacion del rastro de auditoria

Ejemplo de integracion (pseudocodigo)

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)

Proximos pasos

Motor de reglas - Crea reglas que evaluan contra el contexto que proporcionas
Limites de gasto - Configura limites que se aplican a los alcances de tus transacciones
Auditoria y cumplimiento - Consulta el historial de validaciones y el rastro de auditoria

​Vision general de la integracion

​Patron 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 integracion (pseudocodigo)

​Proximos pasos

Vision general de la integracion

Patron 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 integracion (pseudocodigo)

Proximos pasos