> ## 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 > Configure o Tracer com Docker Compose, 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. export const GMetadata = ({children}) => {children} ; 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, não 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 para ser honesto:** 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. **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](./what-is-tracer.mdx). 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](/pt/reference/products/tracer/tracer-api-quick-start). 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](/pt/reference/products/tracer/tracer-api-quick-start). ## 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**: aceita qualquer tipo de transação (Card, Wire, Pix, 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 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** e **Docker Compose** instalados * [ ] **Go 1.26+** para desenvolvimento local (o `go.mod` do repositório declara a versão exata do toolchain) * [ ] **PostgreSQL 17** (a instância primária compartilhada do Midaz, iniciada pelo compose de infraestrutura da plataforma, não pelo compose do próprio Tracer) * [ ] **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 | | PostgreSQL | 5701 | Instância primária compartilhada do PostgreSQL do Midaz, conforme exposta pelo exemplo de infraestrutura fornecido (`DB_PORT`) | *** ## Passo 1: configure o ambiente *** Você pode executar o Tracer com Docker Compose ou localmente para desenvolvimento. ### Opção A: Docker Compose (recomendado) O próprio arquivo Compose do Tracer declara apenas dois serviços: a aplicação e um executor de migração de execução única. **O PostgreSQL não é um deles**. Ele vem do Compose de infraestrutura compartilhada da plataforma e deve estar saudável primeiro. O container da aplicação apenas inicia depois que o executor de migração aplica o schema e termina com sucesso. O serviço sempre inicia com um banco de dados já migrado. No Midaz v4, o Tracer é source-available sob a ELv2 no repositório e no release do Midaz. Ele continua rodando como um serviço próprio. Para desenvolvimento local, comece em `components/tracer`. Navegue até o diretório do projeto Tracer e inicie os serviços: ```bash theme={null} cd components/tracer # Setup environment cp .env.example .env # Start all services (brings up the shared infrastructure first, # then the migration runner, then Tracer) make up ``` ### Opção B: execução local Para desenvolvimento, você pode executar o Tracer localmente: ```bash theme={null} # Set environment variables 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" # Start the service 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` | Habilita a 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-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 | | ----------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Single-tenant, autenticação por plugin habilitada** | Header `Authorization` com um token Bearer | `MULTI_TENANT_ENABLED=false` e `PLUGIN_AUTH_ENABLED=true`, a menos que o endpoint esteja configurado como apenas API key. | | **Single-tenant, autenticação por API key** | Header `X-API-Key` | `MULTI_TENANT_ENABLED=false` e a autenticação por plugin está desabilitada, ou o endpoint está configurado como apenas API key. | | **Multi-tenant (SaaS / BYOC Multi-Tenant)** | Header `Authorization` com um token Bearer | Qualquer deploy com `MULTI_TENANT_ENABLED=true`. A autenticação por plugin é obrigatória; o JWT é emitido pelo [Access Manager](/pt/platform/access-manager) e carrega a claim `tenantId`. | Os passos seguintes usam o formato de API key single-tenant 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 (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 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} # Single-tenant: List rules curl -H "X-API-Key: your-secure-api-key" \ http://localhost:4020/v1/rules ``` ```bash theme={null} # Multi-tenant: List rules curl -H "Authorization: Bearer $JWT" \ https://tracer.sandbox.lerian.net/v1/rules ``` Mantenha as API Keys e os JWTs seguros. Nunca os exponha em código client-side ou em repositórios públicos. A autenticação por API key vem **desabilitada por padrão** (`API_KEY_ENABLED=false`). O `.env.example` fornecido a mantém desligada, para que o desenvolvimento local funcione sem configuração. Um deploy 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 *** 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 do calendário, às 00:00 UTC | | `WEEKLY` | Valor máximo por semana | Uma nova contagem começa a cada semana ISO, na segunda-feira às 00:00 UTC | | `MONTHLY` | Valor máximo por mês | Uma nova contagem começa no dia 1º do mês, às 00:00 UTC | | `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 janelas de tempo e períodos personalizados, veja o [Guia de limites de gastos](./spending-limits.mdx). ### 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 * **Tipo de transação**: aplica-se apenas a CARD, WIRE, PIX ou CRYPTO ### 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", "transactionType": "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 permanentemente. 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](./spending-limits.mdx). ### Monitore o uso Toda resposta de `POST /v1/validations` traz `limitUsageDetails`, com uma entrada por limite verificado pelo Tracer. Cada entrada traz o teto, o valor tentado e o consumo projetado para o período atual desse teto. Essa projeção inclui esta transação. O endpoint `GET /v1/limits/{id}/usage` informa um total acumulado entre os contadores do limite, para uma revisão do consumo geral. Para as opções detalhadas de configuração, veja 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, ativo, timestamp) * Informações da conta * Opcional: segmento, portfólio, comerciante e metadados 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", "transactionType": "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" } }' ``` 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`. `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. **Por que o Tracer retorna uma decisão em vez de bloquear diretamente.** O Tracer funciona como uma camada de decisão, não como 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](/pt/reference/products/tracer/validate-transaction). *** ## 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": [ { "transactionType": "CARD" } ] }' ``` 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" ``` 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](./rule-engine.mdx). *** ## 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 * [ ] 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 e validou sua primeira transação. A partir daqui, você pode explorar recursos mais avançados: * **[Guia de integração](./integration-guide.mdx)** - aprenda a 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 * **[Histórico de validação e compliance](./audit-compliance.mdx)** - 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](/pt/reference/products/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, os schemas de requisição/resposta e os códigos de erro, veja a [Referência da API](/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 | O Tracer retorna decisões como recomendações. Seu sistema deve implementar a ação apropriada para cada decisão.