Pular para o conteúdo principal
POST
/
v1
/
validations
Validar uma Transação
curl --request POST \
  --url https://tracer.lerian.io/v1/validations \
  --header 'Content-Type: <content-type>' \
  --header 'X-API-Key: <x-api-key>' \
  --data '
{
  "requestId": "019c96a0-10ce-75fc-a273-dc799079a99c",
  "transactionType": "CARD",
  "subType": "debit",
  "amount": 150000,
  "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": "Transaction approved",
  "matchedRuleIds": [],
  "evaluatedRuleIds": [
    "019c96a0-1071-7a0d-9916-a831221de252",
    "019c96a0-4b30-7234-a1b2-3d4e5f6a7b8c"
  ],
  "limitUsageDetails": [
    {
      "limitId": "019c96a0-0c0d-7915-84b9-e497bfee9916",
      "limitAmount": 5000000,
      "currentUsage": 1650000,
      "exceeded": false,
      "period": "DAILY"
    }
  ],
  "processingTimeMs": 23
}

Cabeçalhos

​
Content-Type
string
obrigatório

O tipo de mídia do recurso. Deve ser application/json.

​
X-API-Key
string
obrigatório

A chave de API para autenticação. Este header é obrigatório para todos os endpoints, exceto verificações de integridade.

​
X-Request-Id
string<uuid>

Um identificador único usado para rastrear cada requisição.

Corpo

application/json

Requisição de validação de transação. Todo o contexto necessário para a validação deve ser incluído (Padrão Payload-Complete).

​
requestId
string<uuid>
obrigatório

ID único gerado pelo cliente para idempotência e correlação na trilha de auditoria.

​
transactionType
enum<string>
obrigatório

Tipo de transação (método de pagamento).

Opções disponíveis:
CARD,
WIRE,
PIX,
CRYPTO
​
amount
integer
obrigatório

Valor da transação em centavos (menor unidade monetária). Deve ser um inteiro positivo.

Intervalo obrigatório: x >= 1
​
currency
string
obrigatório

Código de moeda ISO 4217 (maiúsculas). Códigos em minúsculas são rejeitados.

Required string length: 3
​
transactionTimestamp
string<date-time>
obrigatório

Timestamp da transação no formato RFC3339 com fuso horário.

​
account
object
obrigatório

Contexto da conta para validação.

​
subType
string

Subtipo da transação para contexto adicional (ex.: débito, crédito, pré-pago).

Maximum string length: 50
​
segment
object

Contexto do segmento (opcional). Se fornecido, segmentId é obrigatório.

​
portfolio
object

Contexto do portfólio (opcional). Se fornecido, portfolioId é obrigatório.

​
merchant
object

Contexto do estabelecimento (opcional, recomendado para transações de cartão). Se fornecido, merchantId é obrigatório.

​
metadata
object

Pares chave-valor personalizados para expressões de regras.

Resposta

Indica que a validação foi processada com sucesso e retorna a decisão.

Resultado da validação de transação.

​
requestId
string<uuid>

Eco do identificador de requisição fornecido pelo cliente.

​
validationId
string<uuid>

Identificador único gerado pelo servidor para este registro de validação.

​
decision
enum<string>

Decisão da validação (ALLOW, DENY ou REVIEW).

Opções disponíveis:
ALLOW,
DENY,
REVIEW
​
reason
string

Motivo legível da decisão.

​
matchedRuleIds
string<uuid>[]

IDs das regras que corresponderam e dispararam a decisão.

​
evaluatedRuleIds
string<uuid>[]

IDs de todas as regras que foram avaliadas.

​
limitUsageDetails
object[]

Detalhes sobre cada limite verificado durante a validação.

​
processingTimeMs
integer

Tempo de processamento em milissegundos (meta < 80ms p99).

​
totalRulesLoaded
integer

Número total de regras carregadas para avaliação.

​
truncated
boolean

Se a resposta foi truncada devido a limites de tamanho.