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 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 autenticação depende do deploy. Deploys single-tenant usam X-API-Key. Deploys multi-tenant (SaaS / BYOC Multi-Tenant) usam Authorization: Bearer $JWT, que o Access Manager emite com a claim tenantId. No modo multi-tenant, 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. Veja Multi-tenancy para o modelo.

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",
   "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ê 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",
  "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 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.

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",
   "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",
  "asset": "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 limite

Tipo	Contagem do período	Caso de uso
`DAILY`	Uma nova contagem começa a cada dia calendário às 00:00 UTC	Limites de gastos diários
`WEEKLY`	Uma nova contagem começa a cada semana ISO, na segunda-feira às 00:00 UTC	Limites de gastos semanais
`MONTHLY`	Uma nova contagem começa no dia 1 do mês às 00:00 UTC	Controle de orçamento mensal
`CUSTOM`	Uma contagem única para todo o intervalo	Janelas fixas de campanha ou evento
`PER_TRANSACTION`	Nenhuma contagem é mantida — cada transação é verificada 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.

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",
   "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",
  "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 limiar	Prosseguir com a transação
`DENY`	Uma regra de negação correspondeu ou um limite foi excedido	Bloquear a transação
`REVIEW`	Uma regra de revisão correspondeu, nenhuma regra de negação foi acionada	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).

Tipos de transação

Tipo	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

transactionType aceita apenas os quatro valores acima. 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

Revise o consumo acumulado de um limite. 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,
  "resetAt": "2026-03-06T00:00:00Z"
}

currentUsage aqui soma os contadores de uso registrados para o limite, entre períodos e escopos.

Etapa 6: Revisar eventos de auditoria

Toda decisão de validação e alteração de configuração é registrada 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 para confirmar que nenhum registro foi adulterado. Isso é essencial para compliance 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 de negócio do ciclo de vida de validação e conceitos essenciais.

Motor de regras

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

Limites de gastos

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

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

Tipos de transação

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

​Tipos de transação

​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

Tipos de transação

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