Início rápido da API do Tracer

Este guia é para desenvolvedores. Se você procura uma visão de negócio sobre o que o Tracer faz, veja O que é o Tracer?.

Este guia leva você da criação da primeira regra e limite de gastos até a validação de uma transação e a revisão da trilha de auditoria.

Antes de começar

Você precisa de:

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

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

O modo de autenticação depende do deploy. Um deploy self-hosted com chave de API usa X-API-Key. Na Lerian Cloud, use Authorization: Bearer $JWT, que o Access Manager emite com a claim tenantId, e substitua cada -H "X-API-Key: $API_KEY" deste guia por -H "Authorization: Bearer $JWT". O Tracer resolve o tenant a partir do token automaticamente, então nunca envie o identificador do tenant em nenhum outro campo.

Etapa 1: Criar uma regra

Crie uma regra de validação com uma expressão CEL. Toda nova regra começa com status 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",
   "expression": "amount > 1000000",
   "action": "DENY",
   "scopes": [
     {
       "scheme": "CARD"
     }
   ]
 }'

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

Salve o ruleId. Você vai usá-lo para ativar a regra.

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

Etapa 2: Ativar a regra

Ative a regra. O Tracer passa a avaliá-la nas 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",
  "expression": "amount > 1000000",
  "action": "DENY",
  "scopes": [
    {
      "transactionType": "CARD",
      "scheme": "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 da regra

Status	Comportamento
`DRAFT`	Criada, mas não avaliada durante as validações
`ACTIVE`	Avaliada durante a validação, nas transações cujo escopo corresponde
`INACTIVE`	Pausada e excluída da avaliação

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

Etapa 3: Criar um limite de gastos

Crie um limite de gastos para controlar valores de transação por escopo e período de tempo. Assim como as regras, os limites começam com status DRAFT. O campo opcional resetTime começa cada período em um horário do dia UTC. O exemplo começa cada dia às 03:00 UTC.

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",
   "asset": "BRL",
   "resetTime": "03:00",
   "scopes": [
     {
       "segmentId": "019c96a0-0b4e-7079-8be0-ab6bdccf975f",
       "scheme": "CARD"
     }
   ]
 }'

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

Tipos de limite

Tipo	Contagem do período	Caso de uso
`DAILY`	Uma nova contagem começa a cada dia no horário de reinício (00:00 UTC por padrão)	Limites de gastos diários
`WEEKLY`	Uma nova contagem começa a cada segunda-feira no horário de reinício (00:00 UTC por padrão)	Limites de gastos semanais
`MONTHLY`	Uma nova contagem começa no dia 1 do mês no horário de reinício (00:00 UTC por padrão)	Controle de orçamento mensal
`CUSTOM`	Uma contagem única para todo o intervalo	Janelas fixas de campanha ou evento
`PER_TRANSACTION`	O Tracer não mantém contagem e verifica cada transação isoladamente	Máximos por transação

Ative o limite da mesma forma que você 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"

Etapa 4: Validar uma transação

Envie uma transação ao Tracer para validação em tempo real contra as regras e limites que se aplicam a ela. Para decidir apenas pelas regras, sem verificar nem contar nenhum limite, envie a mesma requisição para POST /v1/validations/rules-only. Veja Validação apenas por regras.

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",
   "scheme": "CARD",
   "subType": "debit",
   "amount": "1500.00",
   "asset": "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",
  "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 limiar	Prosseguir com a transação
`DENY`	Uma regra de negação correspondeu, um limite foi excedido ou o padrão sem correspondência foi aplicado	Bloquear a transação
`REVIEW`	Uma regra de revisão correspondeu, ou uma expressão de regra falhou para a requisição	Encaminhar para revisão manual

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

Esquemas de pagamento

Esquema	Subtipos de exemplo	Descrição
`CARD`	debit, credit, prepaid	Transações de cartão
`WIRE`	domestic, international, ach	Transferências eletrônicas
`PIX`	instant, scheduled	Pagamentos instantâneos brasileiros
`CRYPTO`	bitcoin, ethereum, stablecoin	Transações de criptomoeda

scheme aceita de 1 a 50 caracteres entre A-Z, 0-9, _ e -, depois que o Tracer remove os espaços das pontas e converte o valor para maiúsculas. Os quatro valores acima são exemplos, não uma lista fechada. transactionType é o nome obsoleto de scheme. Uma requisição de validação deve trazer um dos dois. Se você enviar os dois, eles devem ter o mesmo valor, ou o Tracer retorna 0540. subType é uma string de formato livre (até 50 caracteres, normalizada para minúsculas). Os subtipos listados são exemplos comuns, não uma lista fechada.

Etapa 5: Verificar o uso do limite

Leia quanto do limite o período atual já consumiu. Para o consumo por trás de uma única decisão, leia limitUsageDetails na resposta de POST /v1/validations.

Referência da API: Consultar 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
}

currentUsage aqui cobre o período atual do limite, para o escopo que mais consumiu. Ele inclui a capacidade retida por reservas não confirmadas do ledger do Midaz.

Etapa 6: Revisar eventos de auditoria

O Tracer registra decisões de validação e alterações de configuração em um log de auditoria imutável. Consulte eventos de auditoria para relatórios de compliance e depuração.

Referência da API: Listar eventos de auditoria

cURL

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

Tipos de evento 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

Esta tabela mostra os tipos de evento mais comuns. Para a lista completa (incluindo eventos de atualização, exclusão, rascunho e ciclo de vida de reserva), veja Auditoria e compliance.

Etapa 7: Verificar a integridade da auditoria

Verifique a cadeia de hash criptográfica dos eventos de auditoria.

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 de negócio do ciclo de vida de validação e conceitos essenciais.

Motor de regras

Guia detalhado de expressões CEL e configuração avançada de regras.

Limites de gastos

Configure e gerencie limites por escopo, período e esquema de pagamento.

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 Eventos de Auditoria

API de Dashboards

Tratamento de erros

Eventos

Início rápido da API do Tracer

Antes de começar

Etapa 1: Criar uma regra

Etapa 2: Ativar a regra

Ciclo de vida da regra

Etapa 3: Criar um limite de gastos

Tipos de limite

Etapa 4: Validar uma transação

Tipos de decisão

Esquemas de pagamento

Etapa 5: Verificar o uso do limite

Etapa 6: Revisar eventos de auditoria

Tipos de evento de auditoria

Etapa 7: Verificar a integridade da auditoria

Próximos passos

Primeiros passos com o Tracer

Motor de regras

Limites de gastos

Tratamento de erros

​Antes de começar

​Etapa 1: Criar uma regra

​Etapa 2: Ativar a regra

​Ciclo de vida da regra

​Etapa 3: Criar um limite de gastos

​Tipos de limite

​Etapa 4: Validar uma transação

​Tipos de decisão

​Esquemas de pagamento

​Etapa 5: Verificar o uso do limite

​Etapa 6: Revisar eventos de auditoria

​Tipos de evento de auditoria

​Etapa 7: Verificar a integridade da auditoria

​Próximos passos

Primeiros passos com o Tracer

Motor de regras

Limites de gastos

Tratamento de erros

Antes de começar

Etapa 1: Criar uma regra

Etapa 2: Ativar a regra

Ciclo de vida da regra

Etapa 3: Criar um limite de gastos

Tipos de limite

Etapa 4: Validar uma transação

Tipos de decisão

Esquemas de pagamento

Etapa 5: Verificar o uso do limite

Etapa 6: Revisar eventos de auditoria

Tipos de evento de auditoria

Etapa 7: Verificar a integridade da auditoria

Próximos passos