Auditoría y cumplimiento

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 manipular 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

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 que incluye el hash del registro anterior, formando una cadena append-only. Manipular cualquier registro pasado rompe la cadena para todos los registros subsecuentes.
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:

{
  "valid": true,
  "totalChecked": 12345,
  "firstInvalidId": null
}

Si la cadena está íntegra, valid es true y firstInvalidId se omite. Si un registro fue modificado, valid es false y firstInvalidId apunta al primer registro donde el hash recalculado difiere del hash almacenado. Esta es la base criptográfica para las garantías de evidencia de manipulación exigidas por SOX/GLBA.

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. No hay ventana de tiempo implícita — usa start_date y end_date para acotar el resultado, de lo contrario la respuesta cubre todo dentro del período de retención.

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)
`end_date`	RFC3339	Fin del rango de fechas (exclusivo)
`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

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 (inicio inclusivo, fin exclusivo)
`event_type`	enum	Filtrar por tipo de evento (ver tabla arriba)
`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. El firstInvalidId apunta al punto de divergencia real — comienza la investigación ahí, no en el registro que consultaste.

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:

Encuentra el ID de validación desde tus logs de transacciones o el historial de Tracer
Recupera los detalles completos usando GET /v1/validations/
Revisa la instantánea de la solicitud para ver qué datos fueron proporcionados
Verifica las reglas coincidentes para entender por qué se tomó la decisión
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"`
Presupuesto de evaluación excedido	Devuelve HTTP 504 con TRC-0229	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

Documentation Index

​Visión general del cumplimiento

​Arquitectura del rastro de auditoría

​Qué se registra

​Inmutabilidad y cadena de hash

​Retención de datos

​Períodos de retención

​Consideraciones de cumplimiento

​Consultando el historial de validaciones

​Consulta básica

​Consulta filtrada

​Filtros disponibles

​Requisito de formato de fecha

​Paginación

​Ordenamiento

​Obteniendo detalles de validación

​Consultando eventos de auditoría

​Tipos de evento

​Filtros

​Casos de uso

​Detalle de un evento

​Escenarios de informes de cumplimiento

​Escenario 1: Investigación de auditoría

​Escenario 2: Informe de cumplimiento mensual

​Escenario 3: Análisis de efectividad de reglas

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

​Mejores prácticas para cumplimiento

​Mantenimiento de registros

​Preparación para auditoría

​Flujo de trabajo de investigación

​Comportamiento de no-match y auditoría

​Referencia rápida

​Endpoints

​Resumen de retención

Visión general del cumplimiento

Arquitectura del rastro de auditoría

Qué se registra

Inmutabilidad y cadena de hash

Retención de datos

Períodos de retención

Consideraciones de cumplimiento

Consultando el historial de validaciones

Consulta básica

Consulta filtrada

Filtros disponibles

Requisito de formato de fecha

Paginación

Ordenamiento

Obteniendo detalles de validación

Consultando eventos de auditoría

Tipos de evento

Filtros

Casos de uso

Detalle de un evento

Escenarios de informes de cumplimiento

Escenario 1: Investigación de auditoría

Escenario 2: Informe de cumplimiento mensual

Escenario 3: Análisis de efectividad de reglas

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

Mejores prácticas para cumplimiento

Mantenimiento de registros

Preparación para auditoría

Flujo de trabajo de investigación

Comportamiento de no-match y auditoría

Referencia rápida

Endpoints

Resumen de retención