> ## 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 > Execute o Tracer a partir das imagens de container, conheça seus contextos principais de validação e faça sua primeira chamada de validação de transação com decisão ALLOW, DENY ou REVIEW. O Tracer é a camada que seu sistema de autorização ou onboarding chama antes que uma transação seja concluída. Ele executa suas políticas de fraude, risco e limite em milissegundos e retorna ALLOW, DENY ou REVIEW. A decisão passa a viver em um único lugar, em vez de espalhada pelo código do produto. **O que muda na sua operação:** a lógica de decisão deixa de viver em instruções `if` espalhadas pelos serviços. As mudanças de regra são aplicadas por uma chamada de API no mesmo dia, em vez de no próximo release. O histórico de validação te dá um único lugar para investigar por que uma transação recebeu sua decisão. **Trade-off:** você adiciona uma chamada HTTP ao caminho crítico de cada transação. A meta é p99 abaixo de 80 ms. Em troca, você ganha um ponto único para política e histórico de decisões, e remove lógica duplicada do código do produto. > [!TIP] > > **Para quem é este guia?** Desenvolvedores (juniores ou seniores) que estão integrando o Tracer pela primeira vez. Se você está avaliando o Tracer em nível de produto ou estratégia, comece por [O que é o Tracer](https://docs.lerian.studio/pt/products/tracer/what-is-tracer.md). Se você já tem o Tracer em funcionamento e precisa da mecânica da API, vá direto para o [Início rápido da API do Tracer](https://docs.lerian.studio/pt/reference/products/tracer/tracer-api-quick-start.md). Este guia mostra como configurar o Tracer e executar 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 da API com exemplos de requisição e resposta, veja o [Início rápido da API do Tracer](https://docs.lerian.studio/pt/reference/products/tracer/tracer-api-quick-start.md). ## Por que usar o Tracer *** * **Validação em tempo real**: tome decisões ALLOW/DENY/REVIEW em menos de 80 ms (p99) * **Regras flexíveis**: motor de regras baseado em expressões para lógica de negócio personalizada * **Controle de gastos**: configure limites por conta, portfólio, segmento e período * **Histórico de validação**: decisões armazenadas para investigação e relatórios * **Independente de produto**: valida transações de qualquer esquema de pagamento, como `CARD`, `WIRE`, `PIX` ou `CRYPTO` Ao final deste guia, você vai: * 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 uma transação. Em seguida, ele age sobre a decisão (ALLOW, DENY ou REVIEW) de acordo com sua lógica de negócio. ### Como funciona ![Como o Tracer processa uma requisição de validação pelos contextos de Validação, Regras e Limites e retorna uma decisão ALLOW, DENY ou REVIEW](https://mintcdn.com/lerian-49cb71fc/DzYecUhEaPz9p1hq/images/pt/d2/how-tracer-works.svg?fit=max\&auto=format\&n=DzYecUhEaPz9p1hq\&q=85\&s=111174c83b20568ea3592cc4706aab91) Figura 1. Como o Tracer funciona Neste fluxo: * **Regras** avaliam expressões em relação ao contexto da transação * **Limites** verificam os tetos 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 tem três contextos delimitados: 1. **Contexto de Validação** - Orquestra requisições, coordena a avaliação e armazena o histórico de validação 2. **Contexto de Regras** - Gerencia definições de regras e a avaliação de expressões 3. **Contexto de Limites** - Gerencia limites de gastos e o rastreamento de uso *** ## Pré-requisitos *** Antes de começar, confirme que você tem: * [ ] **Docker** instalado * [ ] **PostgreSQL 17**, com um banco de dados para o Tracer (`tracer` nos exemplos abaixo) * [ ] **API Key** para autenticação ### Dependências de infraestrutura O Tracer requer os seguintes componentes: | Componente | Versão | Finalidade | | - | - | - | | PostgreSQL | 17 | Persistência de dados. O Tracer usa seu próprio banco de dados `tracer` na instância primária compartilhada do PostgreSQL do Midaz; ele não vem com uma instância dedicada. | ### Portas Portas padrão usadas pelos serviços do Tracer: | Serviço | Porta | Descrição | | - | - | - | | Tracer API | 4020 | API REST principal | | Elo de reserva | 4021 | Serviço gRPC que o ledger do Midaz chama para reservar capacidade de limite | *** ## Passo 1: execute o Tracer *** O Tracer é distribuído como duas imagens públicas no Docker Hub. Use a mesma tag para as duas: | Imagem | Função | | - | - | | `lerianstudio/midaz-tracer-migrations` | Aplica o schema do Tracer no banco de dados e termina | | `lerianstudio/midaz-tracer` | Executa a API do Tracer | Os exemplos usam a tag `4.4.0`. O Tracer não aplica migrações quando inicia, então execute primeiro a imagem de migração. ### Aplique o schema ```bash theme={null} docker run --rm \ -e DB_HOST="your-postgres-host" \ -e DB_PORT="5432" \ -e DB_USER="your-postgres-user" \ -e DB_PASSWORD="your-postgres-password" \ -e DB_NAME="tracer" \ -e DB_SSL_MODE="disable" \ lerianstudio/midaz-tracer-migrations:4.4.0 ``` O container termina com status `0` quando o schema está atualizado. Você pode executá-lo de novo com segurança. ### Inicie o Tracer ```bash theme={null} docker run -d --name midaz-tracer \ -p 4020:4020 \ -e SERVER_ADDRESS=":4020" \ -e DB_HOST="your-postgres-host" \ -e DB_PORT="5432" \ -e DB_USER="your-postgres-user" \ -e DB_PASSWORD="your-postgres-password" \ -e DB_NAME="tracer" \ -e DB_SSL_MODE="disable" \ -e ALLOW_INSECURE_TLS="true" \ -e API_KEY_ENABLED="true" \ -e API_KEY="your-secure-api-key" \ lerianstudio/midaz-tracer:4.4.0 ``` `DB_SSL_MODE="disable"` e `ALLOW_INSECURE_TLS="true"` servem para um PostgreSQL local sem TLS. Em produção, defina `DB_SSL_MODE` como `require` ou mais forte e deixe `ALLOW_INSECURE_TLS` sem valor. ### Variáveis de ambiente essenciais | Variável | Descrição | Exemplo | | - | - | - | | `SERVER_ADDRESS` | Endereço de escuta da API | `:4020` | | `DB_HOST` | Host do PostgreSQL | `your-postgres-host` | | `DB_NAME` | Nome do banco de dados PostgreSQL | `tracer` | | `API_KEY` | API Key para autenticação | `your-secure-api-key` | | `API_KEY_ENABLED` | Habilita a autenticação por API Key | `true`, `false` | | `LOG_LEVEL` | Nível de log | `INFO`, `DEBUG`, `ERROR` | Para todas as variáveis, veja [Variáveis de ambiente](https://docs.lerian.studio/pt/products/tracer/tracer-environment-variables.md). *** ## Passo 2: autentique-se na API *** O Tracer aceita autenticação por API key e por plugin. A autenticação por plugin tem precedência quando as duas estão habilitadas, exceto em endpoints configurados como apenas API key. | Configuração de deploy e autenticação | Header de autenticação | Quando usar | | - | - | - | | **Self-hosted, autenticação por plugin habilitada** | Header `Authorization` com um token Bearer | `PLUGIN_AUTH_ENABLED=true`, a menos que o endpoint esteja configurado como apenas API key. | | **Self-hosted, autenticação por API key** | Header `X-API-Key` | A autenticação por plugin está desabilitada, ou o endpoint está configurado como apenas API key. | | **Lerian Cloud** | Header `Authorization` com um token Bearer | Sempre. O JWT é emitido pelo [Access Manager](https://docs.lerian.studio/pt/platform/access-manager.md) e carrega a claim `tenantId`. | Os passos seguintes usam o formato de API key porque a maioria das configurações de desenvolvimento local funciona assim. Se a autenticação por plugin se aplica à sua requisição, substitua `X-API-Key: your-secure-api-key` por `Authorization: Bearer $JWT` em todos os exemplos. ### API Key Inclua a API Key no header `X-API-Key`: ```http theme={null} GET /v1/rules X-API-Key: your-secure-api-key ``` ### Bearer JWT 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 de dados correto do tenant. **Você nunca passa o identificador do tenant em um header, path, body ou escopo de regra**. O token é a única fonte de verdade. ### Exemplo de cURL ```bash theme={null} # API key: List rules curl -H "X-API-Key: your-secure-api-key" \ http://localhost:4020/v1/rules ``` ```bash theme={null} # Bearer JWT: List rules curl -H "Authorization: Bearer $JWT" \ https://tracer.sandbox.lerian.net/v1/rules ``` > [!WARNING] > > Mantenha as API Keys e os JWTs seguros. Nunca os exponha em código client-side ou em repositórios públicos. > [!WARNING] > > A autenticação por API key vem **desabilitada por padrão** (`API_KEY_ENABLED=false`). Um deploy de produção **deve** definir `API_KEY_ENABLED=true` ou `PLUGIN_AUTH_ENABLED=true` antes de expor o serviço. *** ## Passo 3: configure um limite de gastos *** Os limites de gastos controlam os valores de transação por escopo e período. Crie um limite usando `POST /v1/limits`. ### Tipos de limite | Tipo | Descrição | Contagem do período | | - | - | - | | `DAILY` | Valor máximo por dia | Uma nova contagem começa a cada dia no horário de reinício (00:00 UTC por padrão) | | `WEEKLY` | Valor máximo por semana | Uma nova contagem começa a cada segunda-feira no horário de reinício (00:00 UTC por padrão) | | `MONTHLY` | Valor máximo por mês | Uma nova contagem começa no dia 1º do mês no horário de reinício (00:00 UTC por padrão) | | `CUSTOM` | Valor máximo para um intervalo de datas personalizado | Uma contagem para o intervalo inteiro | | `PER_TRANSACTION` | Máximo por transação única | Nenhuma contagem é mantida | Para a configuração detalhada de todos os tipos de limite, incluindo horários de reinício, janelas de tempo e períodos personalizados, veja o [Guia de limites de gastos](https://docs.lerian.studio/pt/products/tracer/spending-limits.md). ### Escopos Aplique limites a contextos específicos: * **Segmento**: aplica-se a todas as contas de um segmento (por exemplo, clientes corporativos) * **Portfólio**: aplica-se às contas de um portfólio * **Conta**: aplica-se a uma conta específica * **Esquema de pagamento**: aplica-se apenas a um esquema, como `CARD` ou `PIX` ### Crie 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": "Daily Corporate Card Limit", "description": "Daily spending limit for corporate card transactions", "limitType": "DAILY", "maxAmount": "50000.00", "asset": "BRL", "scopes": [ { "segmentId": "550e8400-e29b-41d4-a716-446655440000", "scheme": "CARD" } ] }' ``` ### Ative 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 Os limites começam no status `DRAFT` e seguem o ciclo de vida `DRAFT` → `ACTIVE` → `INACTIVE`. Limites inativos podem voltar para `DRAFT` para edição, ou você pode excluí-los. Ative um limite para começar a aplicá-lo. Para o ciclo de vida completo e as regras de transição, veja o [Guia de limites de gastos](https://docs.lerian.studio/pt/products/tracer/spending-limits.md). ### Monitore o uso Toda resposta de `POST /v1/validations` traz `limitUsageDetails`, com uma entrada por limite verificado pelo Tracer. Cada entrada traz o teto e o valor tentado. Para um limite que mantém uma contagem, ela também traz o consumo projetado do período atual: o valor já contado, a capacidade retida por reservas não confirmadas do ledger do Midaz e esta transação. O endpoint `GET /v1/limits/{id}/usage` informa o período atual do limite, para o escopo mais consumido. Para as opções detalhadas de configuração, veja o [Guia de limites de gastos](https://docs.lerian.studio/pt/products/tracer/spending-limits.md). *** ## 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 (esquema de pagamento, valor, ativo, timestamp) * Informações da conta * Opcional: segmento, portfólio, comerciante e metadados (Informações adicionais de chave-valor anexadas a entidades como contas ou transações, como IDs externos, números de referência ou códigos de departamento.) personalizados ```bash theme={null} TS=$(date -u +%Y-%m-%dT%H:%M:%SZ) 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", "scheme": "CARD", "subType": "credit", "amount": "1500.00", "asset": "BRL", "transactionTimestamp": "'"$TS"'", "account": { "accountId": "550e8400-e29b-41d4-a716-446655440100" }, "merchant": { "merchantId": "550e8400-e29b-41d4-a716-446655440103", "category": "5411", "name": "Test Merchant" }, "metadata": { "channel": "mobile" } }' ``` > [!NOTE] > > O `transactionTimestamp` deve ser recente, por isso o exemplo o gera. O Tracer rejeita um timestamp futuro com o código de erro `0419` (tolerância de 1 minuto para desvio de relógio). O Tracer rejeita um timestamp com mais de 24 horas com o código de erro `0421`. > [!NOTE] > > `requestId` é a chave de idempotência. Envie um novo UUID para cada tentativa. Se você repetir um, o Tracer retorna a decisão que já registrou para essa chave. Uma regra ativada nesse meio-tempo não vai parecer ter surtido efeito. O Tracer avalia as regras e os limites que se aplicam à transação e retorna uma das três decisões: | Decisão | Significado | O que seu sistema deve fazer | | - | - | - | | `ALLOW` | Transação aprovada | Prosseguir com a transação | | `DENY` | Transação negada (regra correspondida ou limite excedido) | Bloquear a transação | | `REVIEW` | Requer revisão manual | Colocar na fila para revisão humana | A resposta identifica as regras que o Tracer avaliou, as regras que corresponderam e o uso atual dos limites. Esse detalhe ajuda na depuração e no suporte ao cliente. > [!NOTE] > > **Por que o Tracer retorna uma decisão em vez de bloquear diretamente.** O Tracer é uma camada de decisão, não um gateway de autorização. O sistema que faz a chamada mantém o relacionamento com o cliente e conhece o canal. É ele quem decide o que fazer com um DENY. Por exemplo, seu sistema emissor de cartões pode acatar um `DENY` em uma pré-autorização stand-in. Ele ainda pode capturar a requisição para fins de analytics. Ao retornar uma decisão, o Tracer se encaixa em qualquer fluxo de autorização sem ser dono da UX voltada ao cliente. Para a estrutura completa do payload e os detalhes dos campos, veja a [Referência da API](https://docs.lerian.studio/pt/reference/products/tracer/validate-transaction.md). *** ## Passo 5: crie uma regra de validação *** As regras permitem definir lógica de negócio personalizada que é avaliada durante a validação. Crie uma regra usando o endpoint `POST /v1/rules` com uma expressão, uma 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": "Block high-value card transactions", "description": "Deny card transactions above R$ 10,000", "expression": "amount > 10000", "action": "DENY", "scopes": [ { "scheme": "CARD" } ] }' ``` > [!NOTE] > > O Tracer preserva a caixa e os espaços internos do nome, removendo apenas os espaços no início e no fim antes de armazenar. Pegue o `ruleId` da resposta e use-o na chamada de ativação abaixo. ### Ative uma regra ```bash theme={null} curl -X POST http://localhost:4020/v1/rules/{id}/activate \ -H "X-API-Key: your-secure-api-key" ``` > [!NOTE] > > A ativação tem efeito imediato na instância que atendeu à chamada de ativação. Uma configuração de instância única avalia a regra na sua próxima validação. Quando você roda várias instâncias atrás de um load balancer, as outras pegam a mudança na próxima sincronização de regras. O intervalo é `RULE_SYNC_POLL_INTERVAL_SECONDS`, com padrão `10`. A desativação se propaga da mesma forma. ### Ciclo de vida da regra As regras seguem o mesmo ciclo de vida dos limites: `DRAFT` → `ACTIVE` → `INACTIVE`. Para começar a avaliação, ative a regra usando `POST /v1/rules/{id}/activate`. Você pode desativar e reativar uma regra ativa conforme necessário. Para informações detalhadas sobre expressões de regras e gerenciamento do ciclo de vida, veja o [Guia do motor de regras](https://docs.lerian.studio/pt/products/tracer/rule-engine.md). *** ## Observabilidade *** O Tracer expõe endpoints para monitoramento e observabilidade. ### Principais métricas O Tracer expõe métricas compatíveis com OpenTelemetry via o exportador OTLP, além de métricas personalizadas da aplicação: * `tracer_auth_failures_total{reason}` - falhas de autenticação por motivo (missing\_api\_key, invalid\_api\_key) * `tracer_validation_rollback_failures_total` - falhas de rollback de uso durante decisões REVIEW (lacunas de consistência eventual que se autocorrigem nos limites do período) O middleware HTTP OpenTelemetry embutido no Tracer fornece automaticamente métricas padrão de requisições HTTP. *** ## Verificação *** Confirme que tudo está funcionando corretamente. ### Checklist * [ ] Container do Tracer iniciado e saudável * [ ] Autenticação por API Key funcionando * [ ] Limite de gastos configurado * [ ] Transação de teste validada com sucesso * [ ] Regra criada e ativada *** ## Próximos passos *** A partir daqui, você pode explorar recursos mais avançados: * **[Guia de integração](https://docs.lerian.studio/pt/products/tracer/integration-guide.md)** - aprenda a integrar seu sistema de autorização com o Tracer * **[Motor de regras](https://docs.lerian.studio/pt/products/tracer/rule-engine.md)** - escreva regras de validação em CEL e gerencie seu ciclo de vida * **[Limites de gastos](https://docs.lerian.studio/pt/products/tracer/spending-limits.md)** - configure e gerencie limites de gastos por escopo e período * **[Histórico de validação e compliance](https://docs.lerian.studio/pt/products/tracer/audit-compliance.md)** - consulte o histórico de validação e use-o em seus processos de compliance *** ## Referência rápida *** Os três fluxos que você mais vai usar: * **Validar uma transação**: `POST /v1/validations`. Veja o [Início rápido da API do Tracer](https://docs.lerian.studio/pt/reference/products/tracer/tracer-api-quick-start.md) 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](https://docs.lerian.studio/pt/products/tracer/rule-engine.md). * **Gerenciar limites**: `/v1/limits` (CRUD + ciclo de vida + `/usage`). Veja o [Guia de limites de gastos](https://docs.lerian.studio/pt/products/tracer/spending-limits.md). Para o catálogo completo de endpoints, os schemas de requisição/resposta e os códigos de erro, veja a [Referência da API](https://docs.lerian.studio/pt/openapi/v3-current/tracer.yaml). ### O que seu sistema deve fazer com cada decisão | Decisão | O Tracer recomenda | O que seu sistema deve fazer | | - | - | - | | `ALLOW` | Aprovação | Prosseguir com a transação | | `DENY` | Negação | Bloquear a transação e informar o usuário | | `REVIEW` | Revisão | Colocar na fila para revisão manual em seu sistema | > [!NOTE] > > O Tracer retorna decisões como recomendações. Seu sistema deve implementar a ação apropriada para cada decisão. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.