1. Solicitudes de validación
| Field | Description | Used in |
|---|---|---|
| requestId | ID único generado por el cliente para idempotencia y correlación de auditoría | Tracer |
| transactionType | Tipo de transacción: CARD, WIRE, PIX o CRYPTO | Tracer |
| subType | Subtipo de transacción para contexto adicional (ej., debit, credit) | Tracer |
| amount | Monto de la transacción como cadena decimal, por ejemplo "100.00" (debe ser positivo) | Tracer |
| currency | Código de moneda ISO 4217 (3 letras mayúsculas) | Tracer |
| transactionTimestamp | Cuándo ocurrió la transacción (formato RFC 3339 con zona horaria) | Tracer |
2. Respuestas de validación
| Field | Description | Used in |
|---|---|---|
| validationId | Identificador único generado por el servidor para el registro de validación | Tracer |
| decision | Decisión de validación: ALLOW, DENY o REVIEW | Tracer |
| reason | Razón legible de la decisión | Tracer |
| matchedRuleIds | IDs de las reglas que coincidieron y dispararon la decisión | Tracer |
| evaluatedRuleIds | IDs de todas las reglas que fueron evaluadas | Tracer |
| processingTimeMs | Tiempo de procesamiento en milisegundos | Tracer |
| totalRulesLoaded | Número total de reglas cargadas para evaluación | Tracer |
| truncated | Si la respuesta fue truncada por límites de tamaño | Tracer |
3. Reglas
| Field | Description | Used in |
|---|---|---|
| ruleId | Identificador único de la regla | Tracer |
| name | Nombre legible de la regla (único dentro de su contexto, máx. 255 caracteres) | Tracer |
| description | Propósito y explicación de la lógica de la regla (máx. 1000 caracteres) | Tracer |
| expression | Expresión CEL que debe evaluar a booleano (máx. 5000 caracteres) | Tracer |
| action | Acción ejecutada cuando la expresión evalúa a true: ALLOW, DENY o REVIEW | Tracer |
| scopes | Array de alcances que determinan a qué transacciones aplica esta regla | Tracer |
| status | Estado del ciclo de vida de la regla: DRAFT, ACTIVE, INACTIVE o DELETED | Tracer |
| activatedAt | Cuándo se activó la regla por última vez (null si nunca se activó) | Tracer |
| deactivatedAt | Cuándo se desactivó la regla por última vez (null si nunca se desactivó) | Tracer |
4. Límites de gasto
| Field | Description | Used in |
|---|---|---|
| limitId | Identificador único del límite | Tracer |
| name | Nombre legible del límite (globalmente único, máx. 255 caracteres) | Tracer |
| description | Propósito y explicación de uso del límite (máx. 1000 caracteres) | Tracer |
| limitType | Tipo de límite: DAILY, WEEKLY, MONTHLY, CUSTOM o PER_TRANSACTION (inmutable después de la creación) | Tracer |
| maxAmount | Monto decimal máximo como cadena, por ejemplo "1000.00" | Tracer |
| currency | Código de moneda ISO 4217 (inmutable después de la creación) | Tracer |
| scopes | Array de alcances que determinan a qué transacciones aplica este límite | Tracer |
| status | Estado del ciclo de vida del límite: DRAFT, ACTIVE, INACTIVE o DELETED | Tracer |
| activeTimeStart | Hora de inicio de la ventana activa en formato HH:mm; se omite cuando el límite está activo todo el día | Tracer |
| activeTimeEnd | Hora de fin de la ventana activa en formato HH:mm; se omite cuando el límite está activo todo el día | Tracer |
| customStartDate | Fecha de inicio para límites CUSTOM; requerida cuando limitType es CUSTOM | Tracer |
| customEndDate | Fecha de fin para límites CUSTOM; requerida cuando limitType es CUSTOM | Tracer |
5. Uso de límites
| Field | Description | Used in |
|---|---|---|
| limitAmount | Monto total del límite como cadena decimal | Tracer |
| currentUsage | Uso proyectado después de aplicar la transacción, como cadena decimal | Tracer |
| exceeded | Si el límite fue excedido durante la validación | Tracer |
| period | Tipo de período del límite: DAILY, WEEKLY, MONTHLY, CUSTOM o PER_TRANSACTION | Tracer |
| scope | Descripción legible del alcance (ej., “account:uuid”, “segment:uuid”) | Tracer |
| attemptedAmount | Monto de la transacción siendo validada, como cadena decimal | Tracer |
6. Alcances y direccionamiento
| Field | Description | Used in |
|---|---|---|
| accountId | Identificador de cuenta para direccionamiento de alcance | Tracer |
| segmentId | Identificador de segmento para direccionamiento de alcance | Tracer |
| portfolioId | Identificador de portafolio para direccionamiento de alcance | Tracer |
| merchantId | Identificador de comercio para direccionamiento de alcance | Tracer |
| transactionType | Filtro de tipo de transacción: CARD, WIRE, PIX o CRYPTO | Tracer |
| category | Código de categoría de comercio (4 dígitos MCC según ISO 18245) | Tracer |
| country | País del comercio (ISO 3166-1 alpha-2, 2 letras mayúsculas) | Tracer |