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": "550e8400-e29b-41d4-a716-446655440000",
  "transactionType": "CARD",
  "subType": "debit",
  "amount": 150000,
  "currency": "BRL",
  "transactionTimestamp": "2026-01-30T10:30:00Z",
  "account": {
    "accountId": "660e8400-e29b-41d4-a716-446655440001",
    "type": "checking",
    "status": "active"
  },
  "segment": {
    "segmentId": "770e8400-e29b-41d4-a716-446655440002",
    "name": "corporate"
  },
  "merchant": {
    "merchantId": "990e8400-e29b-41d4-a716-446655440004",
    "name": "Store ABC",
    "category": "5411",
    "country": "BR"
  },
  "metadata": {
    "channel": "MOBILE_APP",
    "deviceId": "device-abc123"
  }
}
'
{ "requestId": "550e8400-e29b-41d4-a716-446655440000", "validationId": "ff0e8400-e29b-41d4-a716-446655440010", "decision": "ALLOW", "reason": "Transaction approved", "matchedRuleIds": [], "evaluatedRuleIds": [ "aa1e8400-e29b-41d4-a716-446655440011", "bb1e8400-e29b-41d4-a716-446655440012" ], "limitUsageDetails": [ { "limitId": "cc1e8400-e29b-41d4-a716-446655440013", "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.