> ## 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 **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?](/pt/tracer/what-is-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.sandbox.lerian.net` 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 ` — o JWT é emitido pelo [Access Manager](/pt/platform/access-manager/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](/pt/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](/pt/reference/tracer/create-rule) ```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", "description": "Deny transactions above BRL 10,000 for card payments", "expression": "amount > 1000000", "action": "DENY", "scopes": [ { "transactionType": "CARD" } ] }' ``` ```json theme={null} { "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](/pt/reference/tracer/activate-rule) ```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", "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](/pt/reference/tracer/create-limit) ```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", "currency": "BRL", "scopes": [ { "segmentId": "019c96a0-0b4e-7079-8be0-ab6bdccf975f", "transactionType": "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", "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 | | `WEEKLY` | Reseta semanalmente | Tetos de gasto semanais | | `MONTHLY` | Reseta no 1° de cada mês | Controle de orçamento mensal | | `CUSTOM` | Reseta após o período personalizado configurado | Janelas fixas de campanha ou evento | | `PER_TRANSACTION` | Sem rastreamento — avaliado por transação | Máximos por transação individual | Ative o limite da mesma forma que 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" ``` ## 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](/pt/reference/tracer/validate-transaction) ```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", "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" } }' ``` ```json theme={null} { "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](/pt/reference/tracer/retrieve-limit-usage) ```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, "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](/pt/reference/tracer/list-audit-events) ```bash cURL theme={null} curl -X GET "https://tracer.sandbox.lerian.net/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](/pt/reference/tracer/verify-audit-event) ```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 *** Visão geral do ciclo de vida de validação e conceitos principais. Aprofundamento em expressões CEL e configuração avançada de regras. Configure e gerencie limites por escopo, período e tipo de transação. Lista completa de códigos de erro e como resolvê-los.