> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Auditoría y cumplimiento
> Entiende cómo el registro de auditoría inmutable y encadenado por hash de Tracer cumple con los requisitos de SOX y GLBA, y consulta el historial de validaciones para la generación de informes de cumplimiento.
export const GSOX = ({children}) =>
{children}
;
export const GAuditTrail = ({children}) =>
{children}
;
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 registro de auditoría 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 |
| ------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------- |
| **SOX** (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:
```json theme={null}
{
"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
```http theme={null}
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
```http theme={null}
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
```http theme={null}
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?"
```http theme={null}
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"
```http theme={null}
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?"
```http theme={null}
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?"
```http theme={null}
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:
1. **Encuentra el ID de validación** en tus registros de transacciones o en el historial de Tracer
2. **Recupera los detalles completos** con GET /v1/validations/{id}
3. **Revisa la instantánea de la solicitud** para ver los datos de la solicitud
4. **Revisa las reglas coincidentes** para entender el motivo de la decisión
5. **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 |