Início rápido da API do Tracer

Este guia é destinado a desenvolvedores. Se você está procurando uma visão geral de nível de negócio sobre o que o Tracer faz, veja O que é o Tracer?.

Coloque o Tracer em funcionamento em minutos. Este guia percorre a jornada completa, desde criar sua primeira regra e limite de gasto até validar uma transação e revisar a auditoria.

Antes de começar

Você precisa de:

Uma instância do Tracer em funcionamento
Credenciais para um dos dois modos de autenticação suportados

Todos os exemplos usam cURL. Substitua $API_KEY pela sua chave de API (single-tenant) ou $JWT pelo seu token Bearer (multi-tenant), e https://tracer.sandbox.lerian.net pela URL do seu Tracer.

O modo de auth depende da implantação. Implantações single-tenant usam X-API-Key. Implantações multi-tenant (SaaS / BYOC Multi-Tenant) usam Authorization: Bearer <jwt> — o JWT é emitido pelo Access Manager e carrega a claim tenantId. Em modo multi-tenant, substitua todo -H "X-API-Key: $API_KEY" deste guia por -H "Authorization: Bearer $JWT". O Tracer resolve o tenant a partir do token automaticamente — nunca passe o identificador do tenant em qualquer outro campo. Consulte Multi-tenancy para o modelo.

Passo 1: Criar uma regra

Crie uma regra de validação com uma expressão CEL. As regras são sempre criadas no estado DRAFT — elas não afetam transações até que você as ative.

Referência da API: Criar regra

cURL

curl -X POST "https://tracer.sandbox.lerian.net/v1/rules" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: $API_KEY" \
 -d '{
   "name": "Block high-value transactions",
   "description": "Deny transactions above BRL 10,000 for card payments",
   "expression": "amount > 1000000",
   "action": "DENY",
   "scopes": [
     {
       "transactionType": "CARD"
     }
   ]
 }'

{
  "ruleId": "019c96a0-4b20-7123-9a1b-2c3d4e5f6a7b",
  "name": "Block high-value transactions",
  "description": "Deny transactions above BRL 10,000 for card payments",
  "expression": "amount > 1000000",
  "action": "DENY",
  "scopes": [
    {
      "transactionType": "CARD"
    }
  ],
  "status": "DRAFT",
  "createdAt": "2026-03-05T10:00:00Z",
  "updatedAt": "2026-03-05T10:00:00Z"
}

Salve o ruleId. Você usará ele para ativar a regra.

Valores monetários (amount da transação, maxAmount do limite de gastos e contadores de uso) são expressos como strings decimais, por exemplo "1500.00" ou "10000.00".

Passo 2: Ativar a regra

Ative a regra para que ela seja avaliada contra as transações recebidas.

Referência da API: Ativar regra

cURL

curl -X POST "https://tracer.sandbox.lerian.net/v1/rules/019c96a0-4b20-7123-9a1b-2c3d4e5f6a7b/activate" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: $API_KEY"

{
  "ruleId": "019c96a0-4b20-7123-9a1b-2c3d4e5f6a7b",
  "name": "Block high-value transactions",
  "description": "Deny transactions above BRL 10,000 for card payments",
  "expression": "amount > 1000000",
  "action": "DENY",
  "scopes": [
    {
      "transactionType": "CARD"
    }
  ],
  "status": "ACTIVE",
  "createdAt": "2026-03-05T10:00:00Z",
  "updatedAt": "2026-03-05T10:01:00Z"
}

O status da regra muda de DRAFT para ACTIVE.

Ciclo de vida das regras

Status	Comportamento
`DRAFT`	Criada mas não avaliada durante as validações
`ACTIVE`	Avaliada contra cada transação recebida
`INACTIVE`	Pausada e excluída da avaliação

Regras INACTIVE podem voltar para DRAFT para reedição usando POST /v1/rules/{id}/draft.

Passo 3: Criar um limite de gasto

Crie um limite de gasto para controlar valores de transações por escopo e período de tempo. Assim como as regras, os limites começam no estado DRAFT.

Referência da API: Criar limite

cURL

curl -X POST "https://tracer.sandbox.lerian.net/v1/limits" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: $API_KEY" \
 -d '{
   "name": "Daily Corporate Limit",
   "description": "Daily spending limit for corporate segment",
   "limitType": "DAILY",
   "maxAmount": "50000.00",
   "currency": "BRL",
   "scopes": [
     {
       "segmentId": "019c96a0-0b4e-7079-8be0-ab6bdccf975f",
       "transactionType": "CARD"
     }
   ]
 }'

{
  "limitId": "019c96a0-4a10-7dfe-b5c1-8a1b2c3d4e5f",
  "name": "Daily Corporate Limit",
  "description": "Daily spending limit for corporate segment",
  "limitType": "DAILY",
  "maxAmount": "50000.00",
  "currency": "BRL",
  "scopes": [
    {
      "segmentId": "019c96a0-0b4e-7079-8be0-ab6bdccf975f",
      "transactionType": "CARD"
    }
  ],
  "status": "DRAFT",
  "resetAt": "2026-03-06T00:00:00Z",
  "createdAt": "2026-03-05T10:02:00Z",
  "updatedAt": "2026-03-05T10:02:00Z"
}

Tipos de limites

Tipo	Comportamento de reset	Caso de uso
`DAILY`	Reseta à meia-noite UTC	Tetos de gasto diários
`WEEKLY`	Reseta semanalmente	Tetos de gasto semanais
`MONTHLY`	Reseta no 1° de cada mês	Controle de orçamento mensal
`CUSTOM`	Reseta após o período personalizado configurado	Janelas fixas de campanha ou evento
`PER_TRANSACTION`	Sem rastreamento — avaliado por transação	Máximos por transação individual

Ative o limite da mesma forma que ativou a regra:

cURL

curl -X POST "https://tracer.sandbox.lerian.net/v1/limits/019c96a0-4a10-7dfe-b5c1-8a1b2c3d4e5f/activate" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: $API_KEY"

Passo 4: Validar uma transação

Envie uma transação ao Tracer para validação em tempo real contra todas as regras e limites ativos. O Tracer não faz chamadas externas durante a avaliação, garantindo tempos de resposta abaixo de 80ms (p99).

Referência da API: Validar transação

cURL

curl -X POST "https://tracer.sandbox.lerian.net/v1/validations" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: $API_KEY" \
 -d '{
   "requestId": "019c96a0-10ce-75fc-a273-dc799079a99c",
   "transactionType": "CARD",
   "subType": "debit",
   "amount": "1500.00",
   "currency": "BRL",
   "transactionTimestamp": "2026-03-05T10:30:00Z",
   "account": {
     "accountId": "019c96a0-0c0c-7221-8cf3-13313fb60081",
     "type": "checking",
     "status": "active"
   },
   "segment": {
     "segmentId": "019c96a0-0b4e-7079-8be0-ab6bdccf975f",
     "name": "corporate"
   },
   "metadata": {
     "channel": "MOBILE_APP"
   }
 }'

{
  "requestId": "019c96a0-10ce-75fc-a273-dc799079a99c",
  "validationId": "019c96a0-4a10-7dfe-b5c1-8a1b2c3d4e5f",
  "decision": "ALLOW",
  "reason": "Transaction approved",
  "matchedRuleIds": [],
  "evaluatedRuleIds": [
    "019c96a0-4b20-7123-9a1b-2c3d4e5f6a7b"
  ],
  "limitUsageDetails": [
    {
      "limitId": "019c96a0-4a10-7dfe-b5c1-8a1b2c3d4e5f",
      "limitAmount": "50000.00",
      "currentUsage": "1500.00",
      "exceeded": false,
      "period": "DAILY"
    }
  ],
  "processingTimeMs": 23
}

Tipos de decisão

Decisão	Significado	Seu sistema deve
`ALLOW`	Todas as regras passaram, todos os limites dentro do threshold	Prosseguir com a transação
`DENY`	Uma regra deny correspondeu ou um limite foi excedido	Bloquear a transação
`REVIEW`	Uma regra review correspondeu, nenhuma regra deny ativada	Encaminhar para revisão manual

O Tracer retorna decisões como recomendações. Seu sistema é responsável por agir sobre a decisão (bloquear, aprovar ou enfileirar a transação).

Tipos de transação

Tipo	Subtipos	Descrição
`CARD`	debit, credit, prepaid	Transações com cartão
`WIRE`	domestic, international, ach	Transferências bancárias
`PIX`	instant, scheduled	Pagamentos instantâneos brasileiros
`CRYPTO`	bitcoin, ethereum, stablecoin	Transações de criptomoedas

Passo 5: Consultar uso de limites

Monitore quanto de um limite de gasto foi consumido no período atual.

Referência da API: Obter uso do limite

cURL

curl -X GET "https://tracer.sandbox.lerian.net/v1/limits/019c96a0-4a10-7dfe-b5c1-8a1b2c3d4e5f/usage" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: $API_KEY"

{
  "limitId": "019c96a0-4a10-7dfe-b5c1-8a1b2c3d4e5f",
  "limitAmount": "50000.00",
  "currentUsage": "15000.00",
  "utilizationPercent": 30.0,
  "nearLimit": false,
  "resetAt": "2026-03-06T00:00:00Z"
}

A flag nearLimit ativa em 80% de utilização, permitindo a gestão proativa de limites.

Passo 6: Revisar eventos de auditoria

Cada decisão de validação e mudança de configuração é registrada em um log de auditoria imutável. Consulte os eventos de auditoria para relatórios de compliance e debugging.

Referência da API: Listar eventos de auditoria

cURL

curl -X GET "https://tracer.sandbox.lerian.net/v1/audit-events?eventType=TRANSACTION_VALIDATED&startDate=2026-03-05T00:00:00Z&endDate=2026-03-06T00:00:00Z" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: $API_KEY"

Tipos de eventos de auditoria

Tipo de evento	Descrição
`TRANSACTION_VALIDATED`	Uma transação foi validada
`RULE_CREATED`	Uma nova regra foi criada
`RULE_ACTIVATED`	Uma regra foi ativada
`RULE_DEACTIVATED`	Uma regra foi desativada
`LIMIT_CREATED`	Um novo limite foi criado
`LIMIT_ACTIVATED`	Um limite foi ativado
`LIMIT_DEACTIVATED`	Um limite foi desativado

Passo 7: Verificar integridade da auditoria

Verifique a cadeia de hash criptográfica dos eventos de auditoria para confirmar que nenhum registro foi adulterado. Isso é essencial para conformidade com SOX e GLBA.

Referência da API: Verificar evento de auditoria

cURL

curl -X GET "https://tracer.sandbox.lerian.net/v1/audit-events/019c96a0-4a10-7dfe-b5c1-8a1b2c3d4e5f/verify" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: $API_KEY"

{
  "isValid": true,
  "totalChecked": 1234,
  "message": "Hash chain integrity verified successfully"
}

Próximos passos

Primeiros passos com o Tracer

Visão geral do ciclo de vida de validação e conceitos principais.

Motor de regras

Aprofundamento em expressões CEL e configuração avançada de regras.

Limites de gasto

Configure e gerencie limites por escopo, período e tipo de transação.

Tratamento de erros

Lista completa de códigos de erro e como resolvê-los.

Primeiros passos

API de Validações

API de Regras

API de Limites

API de Reservas

API de Eventos de Auditoria

Tratamento de erros

Início rápido da API do Tracer

Antes de começar

Passo 1: Criar uma regra

Passo 2: Ativar a regra

Ciclo de vida das regras

Passo 3: Criar um limite de gasto

Tipos de limites

Passo 4: Validar uma transação

Tipos de decisão

Tipos de transação

Passo 5: Consultar uso de limites

Passo 6: Revisar eventos de auditoria

Tipos de eventos de auditoria

Passo 7: Verificar integridade da auditoria

Próximos passos

Primeiros passos com o Tracer

Motor de regras

Limites de gasto

Tratamento de erros

​Antes de começar

​Passo 1: Criar uma regra

​Passo 2: Ativar a regra

​Ciclo de vida das regras

​Passo 3: Criar um limite de gasto

​Tipos de limites

​Passo 4: Validar uma transação

​Tipos de decisão

​Tipos de transação

​Passo 5: Consultar uso de limites

​Passo 6: Revisar eventos de auditoria

​Tipos de eventos de auditoria

​Passo 7: Verificar integridade da auditoria

​Próximos passos

Primeiros passos com o Tracer

Motor de regras

Limites de gasto

Tratamento de erros

Antes de começar

Passo 1: Criar uma regra

Passo 2: Ativar a regra

Ciclo de vida das regras

Passo 3: Criar um limite de gasto

Tipos de limites

Passo 4: Validar uma transação

Tipos de decisão

Tipos de transação

Passo 5: Consultar uso de limites

Passo 6: Revisar eventos de auditoria

Tipos de eventos de auditoria

Passo 7: Verificar integridade da auditoria

Próximos passos