DENY o REVIEW y alguien pregunta por qué. Esta guía te lleva desde la decisión que devolvió Tracer hasta una regla identificada o un límite de gasto identificado. Desde ahí llega al registro almacenado y a la entrada del que puedes entregar a un auditor meses después.
Qué cambia en tu operación: la respuesta a “¿por qué se bloqueó esto?” deja de ser una búsqueda en los registros. Cada decisión llega con los identificadores de lo que la produjo. El mismo registro responde por id años después, y puedes verificar su evento de auditoría contra la cadena de hashes.
Antes de empezar
- Tracer en ejecución y accesible, con una clave de API. Consulta Primeros pasos
- Una respuesta
DENYoREVIEWcon la que trabajar, o elvalidationIdde una - Familiaridad con lo que hacen las reglas y los límites. Consulta Motor de reglas y Límites de gasto
X-API-Key.
Paso 1: Leer la decisión que devolvió Tracer
POST /v1/validations responde con la decisión completa. Una solicitud nueva responde 201. Un requestId repetido responde 200 con la decisión que Tracer ya registró para esa clave.
Para conocer el esquema completo de solicitud y respuesta, consulta Validar una transacción.
Paso 2: Distinguir un rechazo por regla de un rechazo por límite
Lee
reason primero. Indica qué produjo la decisión, y te dice cuál de los dos pasos siguientes debes seguir.
reason lleva el mismo texto en las decisiones REVIEW (Rule matched with REVIEW action), y el paso 3 lee una revisión de la misma forma en que lee un rechazo.
En un rechazo por regla,
limitUsageDetails regresa vacío porque Tracer se detiene antes de la verificación de límites, no porque ningún límite aplique a la cuenta.Paso 3: Identificar la regla
matchedRuleIds enumera cada regla que coincidió, sin importar la acción que tenga cada una. Una regla DENY y una regla ALLOW pueden aparecer ambas en el mismo rechazo. Recupera cada una y lee su action para encontrar la regla detrás de la decisión:
name, description, expression, action y scopes que un colega necesita para ver por qué se activó. Consulta Recuperar una regla.
Compara matchedRuleIds con evaluatedRuleIds cuando la pregunta es la opuesta: “¿por qué mi regla no se activó?”. Tracer no evaluó una regla que esté ausente de evaluatedRuleIds. Empieza por su estado y su alcance en lugar de su expresión.
Paso 4: Identificar el límite de gasto
En un rechazo por
limit_exceeded, limitUsageDetails contiene una entrada por cada límite que Tracer verificó, y las entradas marcadas con "exceeded": true son las que el monto superaría:
attemptedAmount contra limitAmount. El campo currentUsage informa lo que el período actual y el alcance coincidente de ese límite contendrían si se incluyera esta transacción. En la entrada anterior, una compra de 1500 llevaría un tope diario de 50000 a 51500.
Un límite PER_TRANSACTION no lleva ningún conteo, así que su entrada informa currentUsage como 0, y attemptedAmount contra limitAmount es toda la comparación.
GET /v1/limits/{limitId} da el nombre y la configuración actuales del límite. Consulta Recuperar un límite. El registro de la decisión conserva el techo, el período y el alcance que aplicaban cuando Tracer tomó la decisión. Un límite modificado después no cambia lo que dice el registro.
Para saber cómo cuenta cada período y cómo se acumula el consumo, consulta Límites de gasto.
Paso 5: Recuperar el registro más tarde
Tracer almacena cada decisión bajo su
validationId:
transactionType, amount, asset, transactionTimestamp, account, y los campos opcionales segment, portfolio, merchant y metadata), además de los mismos decision, reason, matchedRuleIds, evaluatedRuleIds y limitUsageDetails que llevaba la respuesta original, y un createdAt. Consulta Recuperar una validación.
Presenta este registro en una disputa. Contiene la entrada y el resultado en un solo documento. No cambia cuando las reglas o los límites cambian después.
Paso 6: Encontrar registros cuando no tienes el id
GET /v1/validations enumera las decisiones almacenadas, de la más reciente a la más antigua, con paginación por cursor:
matched_rule_id={ruleId}: cada decisión almacenada con la que esta regla coincidióexceeded_limit_id={limitId}: cada decisión almacenada que este límite detuvo
validationId, decision, reason, amount, asset, transactionType, accountId, matchedRuleIds, exceededLimitIds, processingTimeMs y createdAt. Toma el validationId del que quieres y recupéralo con el paso 5 para obtener el registro completo. Consulta Listar validaciones para conocer todos los filtros y los campos de paginación.
Paso 7: Obtener el evento de auditoría detrás de la decisión
El registro de auditoría almacena la decisión bajo el
validationId como el resourceId del evento:
El mismo endpoint lleva el ciclo de vida de las reglas y los límites: quién los creó, activó o eliminó. Consulta Listar eventos de auditoría para conocer los filtros, y Auditoría y cumplimiento para los tipos de evento y los períodos de retención.
Paso 8: Verificar el evento de auditoría en una auditoría
Pasa el
eventId al endpoint de verificación:
isValid: true establece que cada registro desde el primero hasta el que nombraste sigue coincidiendo con el hash almacenado junto a él. Cada uno también enlaza con el hash del registro anterior. Dentro de ese tramo, ningún registro fue eliminado, reordenado ni refechado. totalChecked informa cuántos registros cubrió la verificación.
En una verificación fallida, isValid es false, message informa manipulación, y firstInvalidId lleva un número de secuencia interno para el registro divergente. Ese número no es un id de evento de auditoría, así que no es un valor para pasar a GET /v1/audit-events/{id}.
Consulta Verificar un evento de auditoría.
Entrega los dos juntos: el evento recuperado en el paso 7 es el contenido de la decisión, y el resultado de la verificación es la evidencia de que la cadena que lo contiene está intacta. La llamada de verificación informa sobre la cadena. No devuelve el registro.
Errores comunes
Códigos de error
La lista completa está en Lista de errores de Tracer.