Auditoría y cumplimiento

Los auditores, los oficiales de cumplimiento y los equipos de disputas usan esta capa para responder una pregunta: “¿Por qué esta transacción recibió esta decisión, y podemos demostrar que nadie alteró esa respuesta?” Qué cambia en tu operación: la evidencia de un control pasa de “déjame extraer registros de N sistemas y conciliar marcas de tiempo” a “aquí está el registro inmutable, encadenado criptográficamente, que muestra que esta transacción recibió esta decisión porque esta regla específica se activó en este momento.” Concesión que hay que reconocer: no existe “eliminar” ni “editar” en los registros de auditoría, por diseño. Un disparador TRUNCATE en el nivel de base de datos bloquea la eliminación masiva. El hash SHA-256 de cada registro incluye el hash del registro anterior, de modo que eliminar o recalificar la fecha de un registro rompe la cadena en todo lo que sigue después. Si necesitas eliminar un registro por razones legales (como el derecho al olvido de GDPR sobre PII), la respuesta es la minimización de datos desde el principio, no la edición retroactiva.

¿Para quién es esta guía? Oficiales de cumplimiento y auditores que verifican qué garantiza Tracer, equipos de disputas que consultan el historial de validaciones, y desarrolladores que generan informes con los endpoints de auditoría. Las secciones de descripción general de cumplimiento y retención no requieren conocimiento de la API. Las secciones de consulta y verificación asumen conocimientos básicos de REST.

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 la generación de informes de cumplimiento.

Descripción general de cumplimiento

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

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

Arquitectura del registro 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 la solicitud	Payload de entrada completo tal como se recibió
Instantánea de la respuesta	Respuesta completa, incluida la decisión y los detalles
Decisión	ALLOW, DENY o REVIEW
Motivo	Por qué se tomó la decisión
Reglas evaluadas	Todas las reglas que se evaluaron
Reglas coincidentes	Reglas que se activaron (si las hay)
Detalles del límite	Información de uso de los límites verificados
Tiempo de procesamiento	Cuánto tardó 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 reintentas una solicitud de validación con el mismo requestId, Tracer almacena solo el primer evento de auditoría. Esto garantiza que el registro 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 de escritura única y están encadenados criptográficamente:

No puedes modificar un registro después de crearlo.
Un disparador TRUNCATE protege la tabla de auditoría en el nivel de base de datos y bloquea la eliminación masiva.
Cada registro almacena un hash SHA-256 calculado sobre la identidad del registro, la marca de tiempo, el actor y el hash del registro anterior, lo que forma una cadena de solo anexado. Eliminar, reordenar o recalificar la fecha de un registro 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 ante inserciones concurrentes.

Puedes verificar la cadena en cualquier momento con 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, inclusive. 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. El campo message informa la alteración. Esta es la base criptográfica de las garantías de evidencia de alteración de SOX/GLBA. Cuando la verificación falla, 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 registro de auditoría está diseñado para auditorías de cumplimiento. Puedes reconstruir exactamente lo que ocurrió en cualquier validación, incluso años después. También puedes demostrar que los registros nunca cambiaron después de creados.

Retención de datos

Tracer retiene los 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	Mínimo 7 años	Requisito de cumplimiento de SOX/GLBA
Reglas (activas/inactivas)	Indefinido	Continuidad operativa
Reglas / Límites (eliminados)	Eliminación lógica: la fila se conserva indefinidamente para auditoría, excluida de los listados de la API	El rastro de cumplimiento debe perdurar más que la visibilidad operativa
Límites	Indefinido	Continuidad operativa
Registros de la aplicación	90 días	Depuración y resolución de problemas

Consideraciones de cumplimiento

Requisito de SOX: mantener los registros durante 7 años a partir de la fecha del informe de auditoría
Requisito de GLBA: retener registros que demuestren el cumplimiento de las normas de privacidad
Exportación de datos: puedes exportar registros para sistemas de auditoría externos

Consultar 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 predeterminada solo cuando faltan tanto start_date como end_date. Envía uno de los dos, o ambos, para consultar un rango más antiguo. Con solo start_date, el rango avanza desde esa fecha sin fin. Con solo end_date, el rango retrocede 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 (inclusive). Por defecto, 90 días atrás cuando no se proporciona ninguna fecha
`end_date`	RFC3339	Fin del rango de fechas (inclusive). Por defecto, el final del día de hoy cuando no se proporciona ninguna fecha
`decision`	enum	Filtra por ALLOW, DENY o REVIEW
`account_id`	UUID	Filtra por cuenta
`segment_id`	UUID	Filtra por segmento
`portfolio_id`	UUID	Filtra por portafolio
`transaction_type`	enum	Filtra por CARD, WIRE, PIX, CRYPTO
`matched_rule_id`	UUID	Filtra por la regla que coincidió
`exceeded_limit_id`	UUID	Filtra por el límite que se excedió

Requisito de formato de fecha

Los parámetros de fecha deben usar el formato RFC3339 con zona horaria obligatoria. Tracer rechaza los formatos de solo fecha.

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 por cursor. La respuesta incluye los campos nextCursor y hasMore para navegar entre 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

La paginación por cursor conserva sort_by y sort_order de 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`	`created_at`
`sort_order`	ASC, DESC	DESC

Obtener detalles de una validación

Recupera los detalles completos de una validación específica con GET /v1/validations/{id}. La respuesta contiene todo lo necesario para entender una decisión de validación:

Instantánea de la solicitud: el payload de entrada completo tal como se recibió
Instantánea de la respuesta: respuesta completa, incluidos la decisión y el motivo
Reglas evaluadas: todas las reglas que Tracer verificó
Reglas coincidentes: reglas que se activaron (si las hay)
Detalles del límite: información de uso de los límites verificados
Marcas de tiempo: cuándo ocurrió la validación y el tiempo de procesamiento

Consultar eventos de auditoría

Más allá de los registros de validación, Tracer también expone un registro genérico de eventos de auditoría mediante GET /v1/audit-events. Esta es la única forma de ver los cambios de ciclo de vida de reglas y límites: quién los creó, actualizó, activó, desactivó, puso en borrador o eliminó.

Tipos de evento

`eventType`	Cuándo se emite
`TRANSACTION_VALIDATED`	Se procesó una solicitud de validación (también disponible mediante `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 volver a editarla
`RULE_DELETED`	Regla eliminada de forma lógica
`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 volver a editarlo
`LIMIT_DELETED`	Límite eliminado de forma lógica
`RESERVATION_RESERVED` / `RESERVATION_CONFIRMED` / `RESERVATION_RELEASED` / `RESERVATION_EXPIRED` / `RESERVATION_SKIPPED`	Ciclo de vida de reserva en dos fases en el punto de integración con el ledger: capacidad retenida, confirmada, devuelta al abortar, expirada u omitida por un fail-open del ledger

Los eventos de reserva aparecen en el registro, pero ningún filtro los selecciona. Los parámetros event_type, action y resource_type solo aceptan los valores listados en la tabla siguiente. Cada uno rechaza un valor de reserva con el error 0009. Para leer eventos de reserva, consulta por rango de fechas y recorre los resultados página por página.

Filtros

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

Parámetro	Tipo	Descripción
`start_date` / `end_date`	RFC3339	Rango de fechas (ambas inclusive). Si no se proporciona ninguna, la consulta cubre los últimos 90 días
`event_type`	enum	`TRANSACTION_VALIDATED`, o un tipo de evento de ciclo de vida de regla o límite
`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	El 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 (`limit` predeterminado 100, máximo 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 de reglas de la semana pasada: 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, incluida la instantánea del estado en el momento del evento.

Escenarios de generación de informes de cumplimiento

Consultas comunes para la generación de informes de auditoría y cumplimiento.

Escenario 1: investigación de auditoría

“¿Por qué se denegó 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 mensual de cumplimiento

“Muestra todas las transacciones denegadas de 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 uso de límites

“¿Qué transacciones excedieron los 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 el cumplimiento

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

Mantenimiento de registros

Almacena los ID de validación en tus registros de transacciones para facilitar la referencia cruzada
Registra el requestId que envías a Tracer para la correlación
Exporta con regularidad si necesitas registros en sistemas de auditoría externos

Errores comunes al leer el registro de auditoría:

“Puedo ver la validación, pero la regla que se activó ya fue eliminada.” Las reglas eliminadas se eliminan de forma lógica. La fila permanece 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, incluidas sus activaciones y la eliminación final.
“Dos reintentos del mismo requestId solo produjeron un evento de auditoría.” Esto es por diseño (deduplicación mediante idx_audit_events_validation_dedup). El registro de auditoría refleja eventos de negocio únicos, no patrones de reintento de la API. Si tu reintento produjo una decisión diferente, vale la pena investigarlo. Tracer debería devolver la respuesta original en caché.
“/verify dice que la cadena está rota en un registro que no toqué.” La cadena vincula cada registro con el anterior, así que una alteración o una corrupción de la base de datos en cualquier punto hace que todo lo posterior se reporte como inválido. Ejecuta /verify contra registros progresivamente anteriores para acotar dónde se rompe la cadena por primera vez.
“Mi consulta de auditoría regresó vacía para el año pasado.” Una consulta sin start_date ni end_date cubre los últimos 90 días. Proporciona el rango que necesitas.

Preparación para auditorías

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

Flujo de investigación

Al investigar una transacción específica:

Encuentra el ID de validación en tus registros de transacciones o en el historial de Tracer
Recupera los detalles completos con GET /v1/validations/
Revisa la instantánea de la solicitud para ver los datos de la solicitud
Revisa las reglas coincidentes para entender el motivo de la decisión
Verifica el estado del límite si corresponden límites

Comportamiento sin coincidencias y auditoría

Cuando se ejecuta una validación y ninguna regla coincide, Tracer devuelve una decisión predeterminada configurada en lugar de tratar la ausencia de coincidencias como un error. Esto es un valor de respaldo por solicitud, no una estrategia de resiliencia de infraestructura. La variable de entorno DEFAULT_DECISION_WHEN_NO_MATCH rige la decisión (predeterminado: ALLOW).

Escenario	Comportamiento	Registro de auditoría
Ninguna regla coincide	Devuelve `DEFAULT_DECISION_WHEN_NO_MATCH` (predeterminado `ALLOW`)	Se registra con `reason: "No matching rules found"`
Tiempo de espera de evaluación agotado	Devuelve HTTP 504 con el código de error `0422`	Sin registro de validación; puede emitirse un evento de fallo de auditoría
Error de base de datos durante la verificación del límite	Devuelve HTTP 500; toda la transacción de validación se revierte	No se persiste ningún registro de validación

Establece DEFAULT_DECISION_WHEN_NO_MATCH=DENY para una semántica de fail-closed en despliegues de alta seguridad. El servicio registra una advertencia al iniciar si esto permanece en el valor predeterminado ALLOW.

Las fallas de infraestructura (base de datos caída, caché obsoleta, tiempo de espera agotado) no recurren a ALLOW. Se manifiestan como errores HTTP al cliente, 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
Registros de la aplicación	90 días

Resumen

Guías

Console

Operaciones

Auditoría y cumplimiento

Descripción general de cumplimiento

Arquitectura del registro de auditoría

Qué se registra

Inmutabilidad y cadena de hash

Retención de datos

Períodos de retención

Consideraciones de cumplimiento

Consultar el historial de validaciones

Consulta básica

Consulta filtrada

Filtros disponibles

Requisito de formato de fecha

Paginación

Ordenamiento

Obtener detalles de una validación

Consultar eventos de auditoría

Tipos de evento

Filtros

Casos de uso

Detalle de un evento

Escenarios de generación de informes de cumplimiento

Escenario 1: investigación de auditoría

Escenario 2: informe mensual de cumplimiento

Escenario 3: análisis de efectividad de reglas

Escenario 4: revisión de uso de límites

Mejores prácticas para el cumplimiento

Mantenimiento de registros

Preparación para auditorías

Flujo de investigación

Comportamiento sin coincidencias y auditoría

Referencia rápida

Endpoints

Resumen de retención

​Descripción general de cumplimiento

​Arquitectura del registro de auditoría

​Qué se registra

​Inmutabilidad y cadena de hash

​Retención de datos

​Períodos de retención

​Consideraciones de cumplimiento

​Consultar el historial de validaciones

​Consulta básica

​Consulta filtrada

​Filtros disponibles

​Requisito de formato de fecha

​Paginación

​Ordenamiento

​Obtener detalles de una validación

​Consultar eventos de auditoría

​Tipos de evento

​Filtros

​Casos de uso

​Detalle de un evento

​Escenarios de generación de informes de cumplimiento

​Escenario 1: investigación de auditoría

​Escenario 2: informe mensual de cumplimiento

​Escenario 3: análisis de efectividad de reglas

​Escenario 4: revisión de uso de límites

​Mejores prácticas para el cumplimiento

​Mantenimiento de registros

​Preparación para auditorías

​Flujo de investigación

​Comportamiento sin coincidencias y auditoría

​Referencia rápida

​Endpoints

​Resumen de retención

Descripción general de cumplimiento

Arquitectura del registro de auditoría

Qué se registra

Inmutabilidad y cadena de hash

Retención de datos

Períodos de retención

Consideraciones de cumplimiento

Consultar el historial de validaciones

Consulta básica

Consulta filtrada

Filtros disponibles

Requisito de formato de fecha

Paginación

Ordenamiento

Obtener detalles de una validación

Consultar eventos de auditoría

Tipos de evento

Filtros

Casos de uso

Detalle de un evento

Escenarios de generación de informes de cumplimiento

Escenario 1: investigación de auditoría

Escenario 2: informe mensual de cumplimiento

Escenario 3: análisis de efectividad de reglas

Escenario 4: revisión de uso de límites

Mejores prácticas para el cumplimiento

Mantenimiento de registros

Preparación para auditorías

Flujo de investigación

Comportamiento sin coincidencias y auditoría

Referencia rápida

Endpoints

Resumen de retención