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
Uma chave de API válida para autenticação

Todos os exemplos usam cURL. Substitua $API_KEY pela sua chave de API e https://tracer.lerian.io pela URL do seu Tracer.

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.

Todos os valores monetários no Tracer são expressos na menor unidade da moeda (ex., centavos para BRL, cents para USD). R$ 10.000,00 = 1.000.000 centavos.

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 PATCH "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

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": 5000000,
   "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": 5000000,
  "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 PATCH "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 consistentes abaixo de 100ms.

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": 150000,
   "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": 5000000,
      "currentUsage": 150000,
      "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": 5000000,
  "currentUsage": 1500000,
  "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.

Primeiros passos

API de Saúde

API de Validações

API de Regras

API de Limites

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

Primeiros passos

API de Saúde

API de Validações

API de Regras

API de Limites

API de Eventos de Auditoria

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