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

> Cómo Tracer mantiene rastros de auditoría para cumplimiento SOX/GLBA y cómo consultar el historial de validaciones.

export const GSOX = ({children}) => <Tooltip headline="SOX" tip="Ley Sarbanes-Oxley — una ley estadounidense que exige estrictos estándares de registro financiero y auditoría, requiriendo rastros de auditoría inmutables." cta="Ver glosario" href="/es/glossary">
    {children}
  </Tooltip>;

export const GAuditTrail = ({children}) => <Tooltip headline="Registro de auditoría" tip="Un registro cronológico e inmutable de cada acción y transacción en el sistema — esencial para el cumplimiento regulatorio y la resolución de disputas." cta="Ver glosario" href="/es/glossary">
    {children}
  </Tooltip>;

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.

<Tip>
  **¿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.
</Tip>

Tracer mantiene un <GAuditTrail>rastro de auditoría</GAuditTrail> 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                                      |
| ------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------- |
| <GSOX>**SOX**</GSOX> (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                      |

<Note>
  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.
</Note>

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

```json theme={null}
{
  "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.

<Note>
  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.
</Note>

***

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

```http theme={null}
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

```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 (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

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

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

<Note>
  Al usar paginación con cursor, `sort_by` y `sort_order` se fijan desde la consulta original.
</Note>

### 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` | 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?"

```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 de cumplimiento mensual

"Mostrar todas las transacciones denegadas para 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 utilización de límites

"¿Qué transacciones excedieron 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 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

<Warning>
  **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.
</Warning>

### 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/{id}
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                                      |

<Note>
  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`.
</Note>

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    |