Saltar al contenido principal
POST
/
v1
/
validations
Validar una Transaccion
curl --request POST \
  --url https://tracer.lerian.io/v1/validations \
  --header 'Content-Type: <content-type>' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "requestId": "019c96a0-10ce-75fc-a273-dc799079a99c",
  "transactionType": "CARD",
  "subType": "debit",
  "amount": "1500.00",
  "currency": "BRL",
  "transactionTimestamp": "2026-01-30T10:30:00Z",
  "account": {
    "accountId": "019c96a0-0c0c-7221-8cf3-13313fb60081",
    "type": "checking",
    "status": "active"
  },
  "segment": {
    "segmentId": "019c96a0-0b4e-7079-8be0-ab6bdccf975f",
    "name": "corporate"
  },
  "merchant": {
    "merchantId": "019c96a0-4f70-7678-e1f2-7b8c9d0e1f2a",
    "name": "Store ABC",
    "category": "5411",
    "country": "BR"
  },
  "metadata": {
    "channel": "MOBILE_APP",
    "deviceId": "device-abc123"
  }
}
'
{
  "requestId": "019c96a0-10ce-75fc-a273-dc799079a99c",
  "validationId": "019c96a0-10d2-7193-8841-0d7347efd09a",
  "decision": "ALLOW",
  "reason": "Transacción aprobada",
  "matchedRuleIds": [],
  "evaluatedRuleIds": [
    "019c96a0-1071-7a0d-9916-a831221de252",
    "019c96a0-4b30-7234-a1b2-3d4e5f6a7b8c"
  ],
  "limitUsageDetails": [
    {
      "limitId": "019c96a0-0c0d-7915-84b9-e497bfee9916",
      "limitAmount": "50000.00",
      "currentUsage": "16500.00",
      "exceeded": false,
      "period": "DAILY"
    }
  ],
  "processingTimeMs": 23
}

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.

Autorizaciones

​
X-API-Key
string
header
requerido

API Key authentication. Used by single-tenant deployments (MULTI_TENANT_ENABLED=false). Sent on every /v1/* request.

Encabezados

​
Content-Type
string
requerido

El tipo de medio del recurso. Debe ser application/json.

​
X-API-Key
string
requerido

La clave API para autenticacion. Este encabezado es requerido para todos los endpoints excepto verificaciones de salud.

​
X-Request-Id
string<uuid>

Un identificador unico usado para rastrear y seguir cada solicitud.

Cuerpo

application/json

Solicitud de validacion de transaccion. Todo el contexto requerido para la validacion debe ser incluido (Patron Payload-Complete).

​
requestId
string<uuid>
requerido

ID unico generado por el cliente para idempotencia y correlacion de rastro de auditoria.

​
transactionType
enum<string>
requerido

Tipo de transaccion (metodo de pago).

Opciones disponibles:
CARD,
WIRE,
PIX,
CRYPTO
​
amount
string
requerido

Monto de la transacción como cadena decimal (ej., "1500.00"). Debe ser un valor decimal positivo.

​
currency
string
requerido

Codigo de moneda ISO 4217 (mayusculas). Los codigos en minusculas son rechazados.

Required string length: 3
​
transactionTimestamp
string<date-time>
requerido

Marca de tiempo de la transaccion en formato RFC3339 con zona horaria.

​
account
object
requerido

Contexto de cuenta para validacion.

​
subType
string

Subtipo de transaccion para contexto adicional (ej., debito, credito, prepago).

Maximum string length: 50
​
segment
object

Contexto de segmento (opcional). Si se proporciona, segmentId es requerido.

​
portfolio
object

Contexto de portafolio (opcional). Si se proporciona, portfolioId es requerido.

​
merchant
object

Contexto de comerciante (opcional, recomendado para transacciones con tarjeta). Si se proporciona, merchantId es requerido.

​
metadata
object

Pares clave-valor personalizados para expresiones de reglas.

Respuesta

Solicitud duplicada detectada (replay idempotente). Retorna el resultado de validación en caché de la solicitud original. El cuerpo de respuesta es idéntico al de la respuesta 201 original.

Resultado de validacion de transaccion.

​
requestId
string<uuid>

Eco del identificador de solicitud proporcionado por el cliente.

​
validationId
string<uuid>

Identificador unico generado por el servidor para este registro de validacion.

​
decision
enum<string>

Decision de validacion (ALLOW, DENY o REVIEW).

Opciones disponibles:
ALLOW,
DENY,
REVIEW
​
reason
string

Razon legible para humanos de la decision.

​
matchedRuleIds
string<uuid>[]

IDs de reglas que coincidieron y activaron la decision.

​
evaluatedRuleIds
string<uuid>[]

IDs de todas las reglas que fueron evaluadas.

​
limitUsageDetails
object[]

Detalles sobre cada limite verificado durante la validacion.

​
processingTimeMs
number<double>

Tiempo de procesamiento en milisegundos (objetivo < 80ms p99).

​
evaluatedAt
string<date-time>

Marca de tiempo del servidor cuando comenzó la evaluación, en formato RFC3339.

​
totalRulesLoaded
integer

Número total de reglas cargadas para evaluación.

​
truncated
boolean

Si la respuesta fue truncada debido a límites de tamaño.