Auditoría y cumplimiento

Descubre cómo Tracer mantiene rastros de auditoría para cumplimiento SOX/GLBA y cómo consultar el historial completo de validaciones desde Lerian Console.

Auditores, oficiales de cumplimiento y equipos de disputas usan esta capa para responder a una pregunta: “¿Por qué esta transacción recibió esta decisión, y podemos probar que nadie alteró esa respuesta?”

Qué cambia en tu operación: la evidencia de control deja de ser “voy a sacar logs de N sistemas y reconciliar timestamps” y se vuelve “este es el registro inmutable, encadenado criptográficamente, mostrando que esta transacción recibió esta decisión porque esta regla específica disparó en este momento”. Ese cambio es el punto entero.

El trade-off honesto: no existe “borrar” ni “editar” en registros de auditoría — por diseño. Un trigger de TRUNCATE a nivel de base de datos bloquea eliminación masiva; el hash SHA-256 de cada registro incluye el hash del anterior, así que eliminar un registro o alterar su fecha rompe la cadena en todo lo que viene después. Si necesitas eliminar un registro por razón legal (GDPR derecho al olvido sobre PII, por ejemplo), la respuesta es minimización de datos por adelantado, no edición retroactiva.

¿Para quién es esta guía? Oficiales de cumplimiento y auditores chequeando qué garantiza Tracer, equipos de disputas consultando historial de validaciones, y devs construyendo reportes contra los endpoints de auditoría. La visión general de cumplimiento y las secciones de retención no asumen conocimiento de API; las secciones de consulta y verify asumen REST básico.

Tracer mantiene un completo e inmutable de todas las decisiones de validación. Esta guía explica cómo funciona el sistema de auditoría y cómo consultar el historial de validaciones para informes de cumplimiento.

​

Visión general del cumplimiento

---

Tracer está diseñado para cumplir con los requisitos de auditoría de regulaciones financieras incluyendo:

Regulación	Requisito	Cómo Tracer cumple
(Sarbanes-Oxley)	Rastro de auditoría completo de decisiones financieras	Cada validación se registra con contexto completo
GLBA (Gramm-Leach-Bliley)	Protección de datos financieros del cliente	Datos encriptados en reposo y en tránsito
Auditoría general	Capacidad de reconstruir decisiones	Registros inmutables con instantáneas de entrada/salida

---

​

Arquitectura del rastro de auditoría

---

Tracer registra cada decisión de validación con contexto completo para cumplimiento e investigación.

​

Qué se registra

Cada validación crea un registro de auditoría inmutable que contiene:

Dato	Descripción
Instantánea de solicitud	Payload de entrada completo como se recibió
Instantánea de respuesta	Respuesta completa incluyendo decisión y detalles
Decisión	ALLOW, DENY o REVIEW
Motivo	Por qué se tomó la decisión
Reglas evaluadas	Todas las reglas que fueron evaluadas
Reglas coincidentes	Reglas que se dispararon (si las hay)
Detalles de límites	Información de uso para los límites verificados
Tiempo de procesamiento	Cuánto tomó la validación
Marca de tiempo	Cuándo ocurrió la validación

Los eventos de auditoría se deduplican para las validaciones de transacciones. Si una solicitud de validación se reintenta con el mismo requestId, solo se almacena el primer evento de auditoría. Esto garantiza que el rastro de auditoría refleje eventos de negocio únicos, no patrones de reintento de la API.

​

Inmutabilidad y cadena de hash

Los registros de auditoría son write-once y encadenados criptográficamente:

• Los registros no pueden modificarse después de la creación.
• La tabla de auditoría está protegida a nivel de base de datos: un trigger de TRUNCATE bloquea eliminaciones masivas.
• Cada registro almacena un hash SHA-256 calculado sobre la identidad, la marca de tiempo y el actor del registro, más el hash del registro anterior, formando una cadena append-only. Eliminar un registro, reordenarlo o alterar su fecha hace que todos los registros posteriores fallen la verificación.
• Un pg_advisory_xact_lock serializa las escrituras de la cadena de hash para mantener el orden estable bajo inserciones concurrentes.

Puedes verificar la cadena en cualquier momento usando GET /v1/audit-events/{id}/verify, que devuelve:

{
  "isValid": true,
  "totalChecked": 12345,
  "message": "Hash chain integrity verified successfully"
}

La verificación cubre la cadena desde su primer registro hasta el registro que indicas, incluido. Cuando todos los hashes siguen coincidiendo, isValid es true y message lo confirma. Cuando un registro ya no coincide con su hash almacenado, isValid es false y message reporta la manipulación. Esta es la base criptográfica para las garantías de evidencia de manipulación exigidas por SOX/GLBA.

En una verificación fallida, firstInvalidId lleva un número de secuencia interno del registro divergente. No es un id de evento de auditoría, así que no es un valor que puedas pasar a GET /v1/audit-events/{id}.

El rastro de auditoría está diseñado para auditorías de cumplimiento. Puedes reconstruir exactamente lo que sucedió para cualquier validación, incluso años después, y probar que los registros no fueron modificados a posteriori.

---

​

Retención de datos

---

Tracer retiene datos según los requisitos regulatorios y las necesidades operativas.

​

Períodos de retención

Tipo de dato	Período de retención	Motivo
Registros de validación	7 años mínimo	Requisito de cumplimiento SOX/GLBA
Reglas (activas/inactivas)	Indefinido	Continuidad operacional
Reglas / Límites (eliminados)	Soft-delete: fila preservada indefinidamente para auditoría, excluida de los listados de la API	El rastro de cumplimiento debe sobrevivir a la visibilidad operativa
Límites	Indefinido	Continuidad operacional
Logs de aplicación	90 días	Depuración y resolución de problemas

​

Consideraciones de cumplimiento

• Requisito SOX: Mantener registros por 7 años desde la fecha del informe de auditoría
• Requisito GLBA: Retener registros que demuestren cumplimiento con las reglas de privacidad
• Exportación de datos: Los registros pueden exportarse para sistemas de auditoría externos

---

​

Consultando el historial de validaciones

---

Usa el endpoint GET /v1/validations para consultar validaciones históricas.

​

Consulta básica

GET /v1/validations
X-API-Key: {api_key}

Devuelve las validaciones en orden cronológico inverso con paginación por cursor.

Una consulta sin fechas cubre los últimos 90 días, no todo el período de retención. Tracer aplica esa ventana por defecto solo cuando faltan tanto start_date como end_date. Envía una de las dos — o ambas — para consultar un rango más antiguo: con solo start_date, el rango corre hacia adelante desde esa fecha sin fin; con solo end_date, corre hacia atrás desde esa fecha sin inicio.

​

Consulta filtrada

GET /v1/validations?start_date=2026-01-01T00:00:00Z&end_date=2026-01-31T23:59:59Z&decision=DENY
X-API-Key: {api_key}

​

Filtros disponibles

Parámetro	Tipo	Descripción
start_date	RFC3339	Inicio del rango de fechas (inclusivo). Por defecto, hace 90 días cuando no se envía ninguna de las dos fechas
end_date	RFC3339	Fin del rango de fechas (inclusivo). Por defecto, el fin de hoy cuando no se envía ninguna de las dos fechas
decision	enum	Filtrar por ALLOW, DENY o REVIEW
account_id	UUID	Filtrar por cuenta
segment_id	UUID	Filtrar por segmento
portfolio_id	UUID	Filtrar por portafolio
transaction_type	enum	Filtrar por CARD, WIRE, PIX, CRYPTO
matched_rule_id	UUID	Filtrar por regla que coincidió
exceeded_limit_id	UUID	Filtrar por límite que fue excedido

​

Requisito de formato de fecha

Los parámetros de fecha deben usar formato RFC3339 con zona horaria obligatoria. Los formatos de solo fecha son rechazados.

Válido:

start_date=2026-01-01T00:00:00Z
start_date=2026-01-01T00:00:00-03:00

Inválido:

start_date=2026-01-01  (rejected - missing time and timezone)

​

Paginación

Los resultados usan paginación basada en cursor. La respuesta incluye campos nextCursor y hasMore para navegar a través de los resultados.

Parámetro	Predeterminado	Máximo	Descripción
limit	100	1000	Resultados por página
cursor	-	-	Cursor de paginación de la respuesta anterior

Al usar paginación con cursor, sort_by y sort_order se fijan desde la consulta original.

​

Ordenamiento

GET /v1/validations?sort_by=created_at&sort_order=DESC

Parámetro	Opciones	Predeterminado
sort_by	created_at, processing_time_ms	createdAt
sort_order	ASC, DESC	DESC

---

​

Obteniendo detalles de validación

---

Recupera detalles completos para una validación específica usando GET /v1/validations/{id}.

La respuesta contiene todo lo necesario para entender una decisión de validación:

• Instantánea de solicitud: El payload de entrada completo como se recibió
• Instantánea de respuesta: Respuesta completa incluyendo decisión y motivo
• Reglas evaluadas: Todas las reglas que fueron verificadas
• Reglas coincidentes: Reglas que se dispararon (si las hay)
• Detalles de límites: Información de uso para los límites verificados
• Timestamps: Cuándo ocurrió la validación y tiempo de procesamiento

---

​

Consultando eventos de auditoría

---

Además de los registros de validación, Tracer también expone un log de eventos de auditoría genérico vía GET /v1/audit-events. Esta es la única forma de ver los cambios de ciclo de vida de reglas y límites — quién las creó, actualizó, activó, desactivó, regresó a borrador o eliminó.

​

Tipos de evento

eventType	Cuándo se emite
TRANSACTION_VALIDATED	Una solicitud de validación fue procesada (también disponible vía GET /v1/validations)
RULE_CREATED / RULE_UPDATED	Regla creada o modificada
RULE_ACTIVATED / RULE_DEACTIVATED	Regla movida a ACTIVE / INACTIVE
RULE_DRAFTED	Regla movida de INACTIVE de vuelta a DRAFT para reedición
RULE_DELETED	Regla eliminada vía soft-delete
LIMIT_CREATED / LIMIT_UPDATED	Límite creado o modificado
LIMIT_ACTIVATED / LIMIT_DEACTIVATED	Límite movido a ACTIVE / INACTIVE
LIMIT_DRAFTED	Límite movido de INACTIVE de vuelta a DRAFT para reedición
LIMIT_DELETED	Límite eliminado vía soft-delete
RESERVATION_RESERVED / RESERVATION_CONFIRMED / RESERVATION_RELEASED / RESERVATION_EXPIRED / RESERVATION_SKIPPED	Ciclo de vida de la reserva en dos fases en la costura con el ledger: capacidad retenida, confirmada, devuelta al abortar, expirada u omitida en un fail-open del ledger

Los eventos de reserva aparecen en el log pero ningún filtro los selecciona: event_type, action y resource_type aceptan solo los valores listados en la tabla de abajo, y un valor de reserva en cualquiera de ellos se rechaza con el error 0009. Para leer eventos de reserva, consulta por rango de fechas y pagina los resultados.

​

Filtros

GET /v1/audit-events acepta los mismos filtros de rango de fechas y alcance que GET /v1/validations, más filtros específicos para eventos de ciclo de vida:

Parámetro	Tipo	Descripción
start_date / end_date	RFC3339	Rango de fechas (ambos inclusivos). Si no se envía ninguna, la consulta cubre los últimos 90 días
event_type	enum	TRANSACTION_VALIDATED, o un tipo de evento del ciclo de vida de reglas o límites
action	enum	VALIDATE, CREATE, UPDATE, DELETE, ACTIVATE, DEACTIVATE, DRAFT
result	enum	SUCCESS, FAILED (para CRUD) o ALLOW, DENY, REVIEW (para validaciones)
resource_type	enum	transaction, rule, limit
resource_id	UUID	ID del recurso afectado
actor_type / actor_id	string	user o system, más el ID del actor
account_id / segment_id / portfolio_id / transaction_type / matched_rule_id	UUID/enum	Mismos filtros de alcance que las validaciones
limit, cursor, sort_by, sort_order	—	Paginación por cursor (predeterminado limit 100, máx 1000; sort_by acepta created_at o event_type)

​

Casos de uso

• ¿Quién activó esta regla? GET /v1/audit-events?resource_type=rule&resource_id={ruleId}&action=ACTIVATE
• Todos los cambios en reglas en la última semana: GET /v1/audit-events?resource_type=rule&start_date=...&end_date=...
• Todas las eliminaciones de límites en 2026: GET /v1/audit-events?resource_type=limit&action=DELETE&start_date=2026-01-01T00:00:00Z

​

Detalle de un evento

Usa GET /v1/audit-events/{id} para recuperar un registro de auditoría específico, incluyendo el snapshot del estado en el momento del evento.

---

​

Escenarios de informes de cumplimiento

---

Consultas comunes para informes de auditoría y cumplimiento.

​

Escenario 1: Investigación de auditoría

“¿Por qué fue denegada esta transacción el 15 de enero?”

GET /v1/validations/{id}

La respuesta muestra la solicitud exacta recibida, todas las reglas evaluadas, qué regla o límite causó la denegación, y la marca de tiempo.

​

Escenario 2: Informe de cumplimiento mensual

“Mostrar todas las transacciones denegadas para cuentas corporativas en enero”

GET /v1/validations?start_date=2026-01-01T00:00:00Z&end_date=2026-02-01T00:00:00Z&decision=DENY&segment_id=corporate-segment-uuid&limit=1000

​

Escenario 3: Análisis de efectividad de reglas

“¿Qué transacciones fueron denegadas por una regla de fraude específica?”

GET /v1/validations?matched_rule_id=fraud-rule-uuid&decision=DENY&limit=1000

​

Escenario 4: Revisión de utilización de límites

“¿Qué transacciones excedieron límites de gasto este mes?”

GET /v1/validations?start_date=2026-01-01T00:00:00Z&end_date=2026-02-01T00:00:00Z&exceeded_limit_id=daily-limit-uuid

---

​

Mejores prácticas para cumplimiento

---

Recomendaciones para mantener la preparación para auditorías.

​

Mantenimiento de registros

• Almacena los IDs de validación en tus registros de transacciones para fácil referencia cruzada
• Registra el requestId que envías a Tracer para correlación
• Exporta regularmente si necesitas registros en sistemas de auditoría externos

Tropezones comunes al leer el rastro de auditoría:

• “Puedo ver la validación pero la regla que disparó ya fue eliminada.” Las reglas eliminadas son soft-deleted — la fila queda en la base de datos, pero no aparece en GET /v1/rules. Para investigar, consulta GET /v1/audit-events?resource_type=rule&resource_id={ruleId} para ver el ciclo de vida de esa regla, incluyendo activaciones y el delete eventual.
• “Dos reintentos del mismo requestId solo produjeron un evento de auditoría.” Eso es por diseño (deduplicación vía idx_audit_events_validation_dedup). El rastro refleja eventos únicos de negocio, no patrones de retry de la API. Si tu reintento produjo una decisión diferente, vale investigar — Tracer debería devolver la respuesta original en caché.
• “El /verify dice que la cadena está rota en un registro que no toqué.” La cadena vincula cada registro al anterior, así que una manipulación o corrupción de DB en cualquier lugar hace que todo lo que viene después reporte inválido. Corre /verify contra registros progresivamente más antiguos para acotar dónde se rompe primero la cadena.
• “Mi consulta de auditoría volvió vacía para el año pasado.” Una consulta sin start_date ni end_date cubre los últimos 90 días. Envía el rango que quieres.

​

Preparación para auditoría

• Prueba las consultas antes de la temporada de auditorías para asegurar que puedes recuperar los datos necesarios
• Verifica los rangos de fechas funcionen correctamente con tus requisitos de zona horaria
• Documenta tu política de retención alineada con la retención de 7 años de Tracer

​

Flujo de trabajo de investigación

Al investigar una transacción específica:

1. Encuentra el ID de validación desde tus logs de transacciones o el historial de Tracer
2. Recupera los detalles completos usando GET /v1/validations/
3. Revisa la instantánea de la solicitud para ver qué datos fueron proporcionados
4. Verifica las reglas coincidentes para entender por qué se tomó la decisión
5. Verifica el estado de los límites si los límites estuvieron involucrados

---

​

Comportamiento de no-match y auditoría

---

Cuando una validación se ejecuta y ninguna regla coincide, Tracer devuelve una decisión predeterminada configurada en vez de tratar la ausencia de coincidencia como un error. Esto es un fallback por solicitud, no una estrategia de resiliencia ante fallas de infraestructura.

La decisión se gobierna por la variable de entorno DEFAULT_DECISION_WHEN_NO_MATCH (predeterminado: ALLOW).

Escenario	Comportamiento	Registro de auditoría
Ninguna regla coincide	Devuelve DEFAULT_DECISION_WHEN_NO_MATCH (predeterminado ALLOW)	Registrado con reason: "No matching rules found"
Timeout de evaluación	Devuelve HTTP 504 con el código de error 0422	Sin registro de validación; puede emitirse un evento de falla de auditoría
Error de base de datos durante la verificación de límite	Devuelve HTTP 500; toda la transacción de validación se revierte	Sin registro de validación persistido

Define DEFAULT_DECISION_WHEN_NO_MATCH=DENY para semántica fail-closed en despliegues de alta seguridad. El servicio registra una advertencia en el startup si esta variable permanece en el predeterminado ALLOW.

Las fallas de infraestructura (base de datos no disponible, cache desactualizada, timeout) no caen en ALLOW — se exponen al cliente como errores HTTP, y la transacción original no tiene registro de auditoría. Los operadores deben monitorear tracer_audit_persist_failures_total y el endpoint /readyz para detectar estos casos.

---

​

Referencia rápida

---

Endpoints clave e información de retención.

​

Endpoints

Operación	Método	Endpoint
Listar validaciones	GET	/v1/validations
Obtener validación	GET	/v1/validations/{id}
Listar eventos de auditoría	GET	/v1/audit-events
Obtener evento de auditoría	GET	/v1/audit-events/{id}
Verificar cadena de hash	GET	/v1/audit-events/{id}/verify

​

Resumen de retención

Dato	Retención
Registros de validación	7+ años
Reglas/límites activos	Indefinido
Logs de aplicación	90 días