> ## 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. # Primeiros passos com o Tracer > Guia de início rápido para configurar e usar o Tracer, a plataforma de validação de transações em tempo real e controle de gastos da Lerian. export const GMetadata = ({children}) => {children} ; export const GAuditTrail = ({children}) => {children} ; O Tracer é a camada que seu sistema de autorização ou onboarding chama antes de uma transação seguir adiante. Ele roda suas políticas de fraude, risco e limites em milissegundos e retorna ALLOW, DENY ou REVIEW — então a decisão fica em um único lugar, não espalhada no código do produto. **O que muda na sua operação:** a lógica de decisão deixa de viver em `if`s espalhados por vários serviços. Mudanças em regras sobem por API no mesmo dia, não na próxima release. Auditoria deixa de ser "vou montar logs de N sistemas e cruzar timestamps" para virar "este é o registro imutável de por que esta transação recebeu esta decisão". **O trade-off honesto:** você adiciona uma chamada HTTP no caminho crítico de cada transação (alvo p99 abaixo de 80ms). Em troca, ganha um ponto único de política, auditoria e analytics — e tira lógica duplicada do código do produto. **Para quem é este guia?** Desenvolvedores (jr ou sr) integrando o Tracer pela primeira vez. Se você está avaliando o Tracer em nível de produto/estratégia, comece por [O que é o Tracer](./what-is-tracer.mdx). Se já tem rodando e precisa da mecânica da API, vá direto para o [Início rápido da API do Tracer](/pt/reference/tracer/tracer-api-quick-start). Este guia orienta você na configuração do **Tracer** e na execução da sua primeira validação. Em poucos passos, você terá um ambiente funcional pronto para validar transações em tempo real. Para instruções passo a passo com exemplos de requisições e respostas da API, consulte o [Início rápido da API do Tracer](/pt/reference/tracer/tracer-api-quick-start). ## Por que usar o Tracer *** * **Validação em tempo real**: Tome decisões ALLOW/DENY/REVIEW em menos de 80ms (p99) * **Regras flexíveis**: Motor de regras baseado em expressões para lógica de negócios personalizada * **Controle de gastos**: Configure limites por conta, portfólio, segmento e período * **Trilha de auditoria completa**: Registros de validação imutáveis para conformidade SOX/GLBA * **Agnóstico a produtos**: Suporta qualquer tipo de transação (Card, Wire, PIX, Crypto) Ao final deste guia, você irá: * Entender a arquitetura e os conceitos principais do Tracer * Ter um ambiente de desenvolvimento funcional * Executar sua primeira validação de transação * Configurar um limite de gastos *** ## O que é o Tracer *** O Tracer é uma plataforma de validação de transações que avalia regras e limites e retorna decisões instantâneas. Seu sistema chama o Tracer antes de executar transações e age com base na decisão (ALLOW, DENY ou REVIEW) de acordo com sua lógica de negócios. ### Como funciona Como o Tracer processa uma requisição de validação nos seus contextos de Validação, Regras e Limites e retorna uma decisão ALLOW, DENY ou REVIEW Neste fluxo: * **Regras** avaliam expressões contra o contexto da transação * **Limites** verificam os limites de gastos para os escopos aplicáveis * **Decisão** retorna ALLOW, DENY ou REVIEW com base nos resultados da avaliação ### Contextos principais O Tracer é construído em torno de três contextos delimitados: 1. **Contexto de Validação** - Orquestra requisições, coordena avaliações, registra trilha de auditoria 2. **Contexto de Regras** - Gerencia definições de regras e avaliação de expressões 3. **Contexto de Limites** - Gerencia limites de gastos e rastreamento de uso *** ## Pré-requisitos *** Antes de começar, certifique-se de ter: * [ ] **Docker** e **Docker Compose** instalados * [ ] **Go 1.26+** (para desenvolvimento local — a versão exata do toolchain está declarada no `go.mod` do repositório) * [ ] **PostgreSQL 16+** (incluído no Docker Compose) * [ ] **API Key** para autenticação ### Dependências de infraestrutura O Tracer requer os seguintes componentes: | Componente | Versão | Finalidade | | ---------- | ------ | ------------------------------------------- | | PostgreSQL | 16+ | Persistência de dados e trilha de auditoria | ### Portas Portas padrão utilizadas pelos serviços do Tracer: | Serviço | Porta | Descrição | | ---------- | ----- | ------------------ | | Tracer API | 4020 | API REST principal | | PostgreSQL | 5432 | Banco de dados | *** ## Passo 1: Configure o ambiente *** Você pode executar o Tracer com Docker Compose ou localmente para desenvolvimento. ### Opção A: Docker Compose (recomendado) Esta é a forma mais rápida de começar. O PostgreSQL inicia automaticamente com o serviço. O Tracer está disponível para clientes licenciados; seu repositório é mantido internamente. Os passos a seguir presumem que você já tem acesso aos arquivos do projeto Tracer necessários. Navegue até o diretório do projeto Tracer para iniciar os serviços: ```bash theme={null} cd tracer # Configure o ambiente cp .env.example .env # Inicie todos os serviços make up ``` ### Opção B: Execução local Para desenvolvimento, você pode executar o Tracer localmente: ```bash theme={null} # Defina as variáveis de ambiente export DB_HOST="localhost" export DB_NAME="tracer" export API_KEY="your-secure-api-key" export API_KEY_ENABLED="true" export SERVER_PORT="4020" export LOG_LEVEL="INFO" # Inicie o serviço go run cmd/app/main.go ``` ### Variáveis de ambiente essenciais | Variável | Descrição | Exemplo | | ----------------- | ---------------------------------- | ------------------------ | | `DB_HOST` | Host do PostgreSQL | `localhost` | | `DB_NAME` | Nome do banco de dados PostgreSQL | `tracer` | | `API_KEY` | API Key para autenticação | `your-secure-api-key` | | `API_KEY_ENABLED` | Habilitar autenticação por API Key | `true`, `false` | | `SERVER_PORT` | Porta da API | `4020` | | `LOG_LEVEL` | Nível de log | `INFO`, `DEBUG`, `ERROR` | *** ## Passo 2: Autentique na API *** O Tracer suporta dois modos de autenticação. Qual você usa depende da topologia de implantação: | Implantação | Header de auth | Quando usar | | ------------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Single-tenant** | `X-API-Key: ` | Desenvolvimento local, BYOC single-customer, ou qualquer implantação com `MULTI_TENANT_ENABLED=false` (padrão). | | **Multi-tenant (SaaS / BYOC Multi-Tenant)** | `Authorization: Bearer ` | Qualquer implantação com `MULTI_TENANT_ENABLED=true`. O JWT é emitido pelo [Access Manager](/pt/platform/access-manager/access-manager) e carrega a claim `tenantId`. | Os passos restantes deste guia usam a forma single-tenant (API Key) porque a maior parte das configurações locais de desenvolvimento roda assim. Se seu ambiente for multi-tenant, substitua `X-API-Key: your-secure-api-key` por `Authorization: Bearer $JWT` em todos os exemplos. ### API Key (single-tenant) Inclua a API Key no header `X-API-Key`: ```http theme={null} GET /v1/rules X-API-Key: your-secure-api-key ``` ### Bearer JWT (multi-tenant) Inclua o JWT emitido pelo Access Manager no header `Authorization`: ```http theme={null} GET /v1/rules Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... ``` O Tracer extrai a claim `tenantId` do JWT e roteia a requisição para o banco do tenant correto. **Você nunca passa o identificador do tenant em header, path, body ou escopo de regra** — o token é a única fonte de verdade. ### Exemplo com cURL ```bash theme={null} # Single-tenant: lista as regras curl -H "X-API-Key: your-secure-api-key" \ http://localhost:4020/v1/rules ``` ```bash theme={null} # Multi-tenant: lista as regras curl -H "Authorization: Bearer $JWT" \ https://tracer.sandbox.lerian.net/v1/rules ``` API Keys e JWTs devem ser mantidos em segurança. Nunca exponha-os em código do lado do cliente ou repositórios públicos. A autenticação por API Key está **desabilitada por padrão** (`API_KEY_ENABLED=false`). O arquivo `.env.example` mantém isso desligado para que o desenvolvimento local funcione sem configuração, mas uma implantação de produção **deve** definir `API_KEY_ENABLED=true` (single-tenant) ou `MULTI_TENANT_ENABLED=true` e `PLUGIN_AUTH_ENABLED=true` (multi-tenant) antes de expor o serviço. *** ## Passo 3: Configure um limite de gastos *** Limites de gastos controlam valores de transação por escopo e período. Crie um limite usando `POST /v1/limits`. ### Tipos de limite | Tipo | Descrição | Comportamento de reset | | ----------------- | ----------------------------------------------------- | ------------------------------------------ | | `DAILY` | Valor máximo por dia | Reseta à meia-noite UTC | | `WEEKLY` | Valor máximo por semana | Reseta toda segunda-feira à meia-noite UTC | | `MONTHLY` | Valor máximo por mês | Reseta no 1° do mês | | `CUSTOM` | Valor máximo para um intervalo de datas personalizado | Reseta ao final do período personalizado | | `PER_TRANSACTION` | Valor máximo por transação individual | Não requer rastreamento | Para configuração detalhada de todos os tipos de limite, incluindo janelas de tempo e períodos personalizados, consulte o [Guia de limites de gastos](./spending-limits.mdx). ### Escopos Aplique limites a contextos específicos: * **Segmento**: Aplica a todas as contas de um segmento (ex.: clientes corporativos) * **Portfólio**: Aplica a contas de um portfólio * **Conta**: Aplica a uma conta específica * **Tipo de transação**: Aplica apenas a CARD, WIRE, PIX ou CRYPTO ### Criar um limite ```bash theme={null} curl -X POST http://localhost:4020/v1/limits \ -H "X-API-Key: your-secure-api-key" \ -H "Content-Type: application/json" \ -d '{ "name": "Limite Diário Cartão Corporativo", "description": "Limite diário de gastos para transações de cartão corporativo", "limitType": "DAILY", "maxAmount": "50000.00", "currency": "BRL", "scopes": [ { "segmentId": "550e8400-e29b-41d4-a716-446655440000", "transactionType": "CARD" } ] }' ``` ### Ativar um limite ```bash theme={null} curl -X POST http://localhost:4020/v1/limits/{id}/activate \ -H "X-API-Key: your-secure-api-key" ``` ### Ciclo de vida do limite Limites são criados com status `DRAFT` e seguem o ciclo de vida `DRAFT` → `ACTIVE` → `INACTIVE`. Limites inativos podem retornar a `DRAFT` para edição ou ser deletados permanentemente. Ative um limite para começar a aplicação. Para o ciclo de vida completo e regras de transição, consulte o [Guia de limites de gastos](./spending-limits.mdx). ### Monitore o uso Consulte `GET /v1/limits/{id}/usage` para verificar o consumo atual. O indicador `nearLimit` fica `true` quando a utilização é **estritamente maior que 80%** (`utilizationPercent > 80`), dando aos operadores um aviso antes que o limite seja excedido. Para opções de configuração detalhadas, consulte o [Guia de limites de gastos](./spending-limits.mdx). *** ## Passo 4: Valide sua primeira transação *** Com os limites configurados, você está pronto para validar uma transação usando `POST /v1/validations`. ### Envie uma transação para validação Envie uma requisição de validação com o contexto da transação incluindo: * Detalhes da transação (tipo, valor, moeda, timestamp) * Informações da conta * Opcional: segmento, portfólio, comerciante e metadata personalizada ```bash theme={null} curl -X POST http://localhost:4020/v1/validations \ -H "X-API-Key: your-secure-api-key" \ -H "Content-Type: application/json" \ -d '{ "requestId": "550e8400-e29b-41d4-a716-446655440104", "transactionType": "CARD", "subType": "credit", "amount": "1500.00", "currency": "BRL", "transactionTimestamp": "2026-02-20T12:00:00Z", "account": { "id": "550e8400-e29b-41d4-a716-446655440100" }, "merchant": { "id": "550e8400-e29b-41d4-a716-446655440103", "category": "5411", "name": "Test Merchant" }, "metadata": { "channel": "mobile" } }' ``` O `transactionTimestamp` deve ser recente: timestamps no futuro são rejeitados com o código de erro `0419` (tolerância de 1 minuto de dessincronização de relógio), e timestamps com mais de 24 horas são rejeitados com o código de erro `0421`. O Tracer avalia todas as regras e limites ativos, então retorna uma de três decisões: | Decisão | Significado | Seu sistema deve | | -------- | -------------------------------------------------------- | ------------------------------ | | `ALLOW` | Transação aprovada | Prosseguir com a transação | | `DENY` | Transação negada (regra correspondeu ou limite excedido) | Bloquear a transação | | `REVIEW` | Requer revisão manual | Enfileirar para revisão humana | A resposta inclui detalhes sobre quais regras foram avaliadas, quais corresponderam e o uso atual do limite — útil para depuração e suporte ao cliente. **Por que o Tracer retorna uma decisão em vez de bloquear direto.** O Tracer é uma camada de decisão, não um gateway de autorização. O sistema que faz a chamada é quem detém a relação com o cliente, conhece o canal e decide o que fazer com um DENY — por exemplo, seu sistema emissor de cartão pode honrar um `DENY` numa pre-auth de stand-in mas ainda assim querer capturar a requisição para analytics. Ao retornar a decisão, o Tracer encaixa em qualquer fluxo de autorização sem ser dono da UX voltada para o cliente. Para a estrutura completa do payload e detalhes de campos, consulte a [Referência da API](/pt/reference/tracer/validate-transaction). *** ## Passo 5: Crie uma regra de validação *** Regras permitem definir lógica de negócios personalizada que é avaliada durante a validação. Crie uma regra usando o endpoint `POST /v1/rules` com uma expressão, ação e escopos opcionais. Por exemplo, para bloquear transações de alto valor: ```bash theme={null} curl -X POST http://localhost:4020/v1/rules \ -H "X-API-Key: your-secure-api-key" \ -H "Content-Type: application/json" \ -d '{ "name": "Bloquear transações de cartão de alto valor", "description": "Negar transações de cartão acima de R$ 10.000", "expression": "amount > 10000", "action": "DENY", "scopes": [ { "transactionType": "CARD" } ] }' ``` ### Ativar uma regra ```bash theme={null} curl -X POST http://localhost:4020/v1/rules/{id}/activate \ -H "X-API-Key: your-secure-api-key" ``` Regras ativas são servidas a partir de um cache em memória que atualiza a cada `RULE_SYNC_POLL_INTERVAL_SECONDS` (padrão `10`). Regras recém-ativadas podem levar **até \~10 segundos** para começar a ser avaliadas, e desativações entram em vigor no próximo sync. Planeje os testes de integração de acordo. ### Ciclo de vida da regra Regras seguem o mesmo ciclo de vida dos limites: `DRAFT` → `ACTIVE` → `INACTIVE`. Para iniciar a avaliação, ative a regra usando `POST /v1/rules/{id}/activate`. Regras ativas podem ser desativadas e reativadas conforme necessário. Para informações detalhadas sobre expressões de regras e gerenciamento do ciclo de vida, consulte o [Guia do motor de regras](./rule-engine.mdx). *** ## Observabilidade *** O Tracer expõe endpoints para monitoramento e observabilidade. ### Métricas principais O Tracer expõe métricas compatíveis com OpenTelemetry via exportador OTLP, além de métricas customizadas da aplicação: * `tracer_auth_failures_total{reason}` - Falhas de autenticação por motivo (missing\_api\_key, invalid\_api\_key) * `tracer_audit_persist_failures_total` - Falhas de persistência de registro de auditoria (risco de conformidade) * `tracer_validation_rollback_failures_total` - Falhas de rollback de uso em decisões REVIEW (lacunas de consistência eventual que se auto-corrigem nas fronteiras de período) Métricas padrão de requisições HTTP são fornecidas automaticamente pelo middleware OpenTelemetry Fiber. *** ## Verificação *** Confirme que tudo está funcionando corretamente. ### Lista de verificação * [ ] Serviços Docker iniciados e saudáveis * [ ] Autenticação por API Key funcionando * [ ] Limite de gastos configurado * [ ] Transação de teste validada com sucesso * [ ] Regra criada e ativada *** ## Próximos passos *** Você configurou o Tracer com sucesso e validou sua primeira transação. A partir daqui, você pode explorar recursos mais avançados: * **[Guia de integração](./integration-guide.mdx)** - Aprenda como integrar seu sistema de autorização com o Tracer * **[Motor de regras](./rule-engine.mdx)** - Escreva regras de validação em CEL e gerencie seu ciclo de vida * **[Limites de gastos](./spending-limits.mdx)** - Configure e gerencie limites de gastos por escopo e período * **[Auditoria e conformidade](./audit-compliance.mdx)** - Consulte o histórico de validações e entenda a trilha de auditoria *** ## Referência rápida *** Os três fluxos que você vai usar mais: * **Validar uma transação**: `POST /v1/validations` — veja o [Início rápido da API do Tracer](/pt/reference/tracer/tracer-api-quick-start) para o formato da requisição. * **Gerenciar regras**: `/v1/rules` (CRUD + endpoints de ciclo de vida `/activate`, `/deactivate`, `/draft`) — veja o [Guia do motor de regras](./rule-engine.mdx). * **Gerenciar limites**: `/v1/limits` (CRUD + ciclo de vida + `/usage`) — veja o [Guia de limites de gastos](./spending-limits.mdx). Para o catálogo completo de endpoints, schemas de request/response e códigos de erro, consulte a [referência da API](/pt/openapi/v3-current/tracer.yaml). ### O que seu sistema deve fazer com cada decisão | Decisão | Tracer recomenda | Seu sistema deve | | -------- | ---------------- | --------------------------------------------- | | `ALLOW` | Aprovação | Prosseguir com a transação | | `DENY` | Negação | Bloquear a transação e informar o usuário | | `REVIEW` | Revisão | Enfileirar para revisão manual no seu sistema | O Tracer retorna decisões como recomendações. Seu sistema é responsável por implementar a ação apropriada com base em cada decisão.