Auditoría y cumplimiento

Entiende cómo funciona el registro de auditoría inmutable y encadenado por hash de Tracer, y consulta el historial de validaciones para la generación de informes de 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?”

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: 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. Eliminar, reordenar o recalificar la fecha de un registro hace que la verificación falle. 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. La sección de retención no requiere conocimiento de la API. Las secciones de consulta y verificación asumen conocimientos básicos de REST.

Tracer mantiene un registro de auditoría inmutable de 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.

​

Arquitectura del registro de auditoría

---

Tracer registra decisiones con contexto completo para cumplimiento e investigación: cada llamada a POST /v1/validations, cada llamada a POST /v1/validations/rules-only y cada reserva del ledger de Midaz que retiene capacidad.

​

Qué se registra

El registro de auditoría de una validación contiene:

Dato	Descripción
Instantánea de la solicitud	La solicitud tal como Tracer la registró con la decisión
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, y Tracer enlaza los registros en una cadena de hash. Eliminar, reordenar o recalificar la fecha de un registro hace que falle la verificación de los registros enlazados con él.

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

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

La verificación cubre el registro que indicas y sus vínculos en la cadena de hash. Cuando todos los hashes que comprueba 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.

Un registro que Tracer aún no encadenó a la cadena responde 409 con el código 0566. Vuelve a intentar tras unos segundos.

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}.

---

​

Retención de datos

---

​

Períodos de retención

Tipo de dato	Período de retención	Motivo
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

---

​

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. El registro de una reserva con más de un origen coincide con cualquiera de sus cuentas de origen
segment_id	UUID	Filtra por segmento
portfolio_id	UUID	Filtra por portafolio
scheme	string	Filtra por esquema de pago, como CARD o PIX. transaction_type es el nombre obsoleto de este filtro
matched_rule_id	UUID	Filtra por la regla que coincidió
exceeded_limit_id	UUID	Filtra por el límite que se excedió
transaction_id	UUID	Filtra por la transacción del ledger de Midaz sobre la que decidió una reserva. Un valor que no es un UUID responde 400

Las fechas usan RFC3339, o yyyy-mm-dd o yyyy-mm-dd hh:mm:ss, leídas en UTC. Una fecha final sin hora cubre el día completo.

​

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: los datos de la solicitud
• 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
• Transacción del ledger: el transactionId de una reserva del ledger de Midaz, con su organizationId y ledgerId
• Orígenes: En una reserva con más de una cuenta de origen, el resultado de cada origen: cuenta, monto, decisión, reglas que coincidieron y límites excedidos
• 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 POST /v1/validations o POST /v1/validations/rules-only (también disponible mediante GET /v1/validations). Solo una solicitud solo por reglas marca su snapshot con rulesOnly: true. Una reserva del ledger de Midaz escribe en su lugar su registro de validación y eventos RESERVATION_RESERVED
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	Ciclo de vida de reserva en dos fases en el punto de integración con el ledger: capacidad retenida, confirmada, devuelta al abortar o expirada

​

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 regla, límite o reserva
action	enum	VALIDATE, CREATE, UPDATE, DELETE, ACTIVATE, DEACTIVATE, DRAFT, RESERVE, CONFIRM, RELEASE, EXPIRE, SKIP
result	enum	SUCCESS, FAILED (para CRUD) o ALLOW, DENY, REVIEW (para validaciones)
resource_type	enum	transaction, rule, limit, reservation
resource_id	UUID	El ID del recurso afectado
actor_type / actor_id	string	user, api_key o system, más el ID del actor
account_id / segment_id / portfolio_id / scheme / 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 confirmar que puedes recuperar los datos necesarios
• Verifica que los rangos de fechas funcionen correctamente con tus requisitos de zona horaria

​

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. Para una transacción del ledger de Midaz, usa GET /v1/validations?transaction_id={transactionId}
2. Recupera los detalles completos con GET /v1/validations/
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. En una transacción del ledger de Midaz, GET /v1/validations/{id}/reservations lista las retenciones con su estado

---

​

Comportamiento sin coincidencias y auditoría

---

Cuando se ejecuta una validación solo por reglas 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 en una validación solo por reglas	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 0564	Sin registro de validación; puede emitirse un evento de fallo de auditoría
Error de base de datos durante una reserva	La reserva responde un error al ledger de Midaz y no retiene nada	No se persiste ningún registro de validación

Establece DEFAULT_DECISION_WHEN_NO_MATCH=DENY. 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 las retenciones de la transacción de una validación	GET	/v1/validations/{id}/reservations
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
Reglas/límites activos	Indefinido