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.lerian.io 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.lerian.io/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.lerian.io/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.lerian.io/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
`MONTHLY`	Reseta no 1° de cada mês	Controle de orçamento mensal
`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.lerian.io/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.lerian.io/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.lerian.io/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.lerian.io/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.lerian.io/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.

​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