> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Início rápido da API do Tracer

> Coloque o Tracer em funcionamento: crie sua primeira regra e limite de gastos, valide uma transação e revise a trilha de auditoria usando as APIs REST do Tracer.

> [!TIP]
>
> **Este guia é para desenvolvedores.** Se você procura uma visão de negócio sobre o que o Tracer faz, veja [O que é o Tracer?](https://docs.lerian.studio/pt/products/tracer/what-is-tracer.md).

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.

> [!NOTE]
>
> **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](https://docs.lerian.studio/pt/platform/access-manager.md) 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.

> [!TIP]
>
> Referência da API: [Criar regra](https://docs.lerian.studio/pt/reference/products/tracer/create-rule.md)

```bash cURL theme={null}
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"
     }
   ]
 }'
```

```json theme={null}
{
  "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.

> [!NOTE]
>
> 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.

> [!TIP]
>
> Referência da API: [Ativar regra](https://docs.lerian.studio/pt/reference/products/tracer/activate-rule.md)

```bash cURL theme={null}
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"
```

```json theme={null}
{
  "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.

> [!TIP]
>
> Referência da API: [Criar limite](https://docs.lerian.studio/pt/reference/products/tracer/create-limit.md)

```bash cURL theme={null}
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"
     }
   ]
 }'
```

```json theme={null}
{
  "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:

```bash cURL theme={null}
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](https://docs.lerian.studio/pt/products/tracer/integration-guide.md#rules-only-validation).

> [!TIP]
>
> Referência da API: [Validar transação](https://docs.lerian.studio/pt/reference/products/tracer/validate-transaction.md)

```bash cURL theme={null}
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"
   }
 }'
```

```json theme={null}
{
  "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 |

> [!NOTE]
>
> 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`.

> [!TIP]
>
> Referência da API: [Consultar uso do limite](https://docs.lerian.studio/pt/reference/products/tracer/retrieve-limit-usage.md)

```bash cURL theme={null}
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"
```

```json theme={null}
{
  "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.

> [!TIP]
>
> Referência da API: [Listar eventos de auditoria](https://docs.lerian.studio/pt/reference/products/tracer/list-audit-events.md)

```bash cURL theme={null}
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](https://docs.lerian.studio/pt/products/tracer/audit-compliance.md).

## Etapa 7: Verificar a integridade da auditoria

***

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

> [!TIP]
>
> Referência da API: [Verificar evento de auditoria](https://docs.lerian.studio/pt/reference/products/tracer/verify-audit-event.md)

```bash cURL theme={null}
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"
```

```json theme={null}
{
  "isValid": true,
  "totalChecked": 1234,
  "message": "Hash chain integrity verified successfully"
}
```

## Próximos passos

***

> [card] [Primeiros passos com o Tracer](https://docs.lerian.studio/pt/products/tracer/getting-started.md)
>
> Visão de negócio do ciclo de vida de validação e conceitos essenciais.

> [card] [Motor de regras](https://docs.lerian.studio/pt/products/tracer/rule-engine.md)
>
> Guia detalhado de expressões CEL e configuração avançada de regras.

> [card] [Limites de gastos](https://docs.lerian.studio/pt/products/tracer/spending-limits.md)
>
> Configure e gerencie limites por escopo, período e esquema de pagamento.

> [card] [Tratamento de erros](https://docs.lerian.studio/pt/reference/products/tracer/tracer-error-list.md)
>
> Lista completa de códigos de erro e como resolvê-los.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.