> ## 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. **Este guia é para desenvolvedores.** Se você procura uma visão de negócio sobre o que o Tracer faz, veja [O que é o Tracer?](/pt/products/tracer/what-is-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](/pt/platform/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](/pt/platform/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](/pt/reference/products/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ê 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](/pt/reference/products/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 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](/pt/reference/products/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", "asset": "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", "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: ```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. Referência da API: [Validar transação](/pt/reference/products/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", "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", "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](/pt/reference/products/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" } ``` `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](/pt/reference/products/tracer/list-audit-events) ```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](/pt/products/tracer/audit-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](/pt/reference/products/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 de negócio do ciclo de vida de validação e conceitos essenciais. 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.