Primeiros passos com o Tracer

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.

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. 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.

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.

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 — 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:

Contexto de Validação - Orquestra requisições, coordena a avaliação e armazena o histórico de validação
Contexto de Regras - Gerencia definições de regras e a avaliação de expressões
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

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

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.

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 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:

GET /v1/rules
X-API-Key: your-secure-api-key

Bearer JWT

Inclua o JWT emitido pelo Access Manager no header Authorization:

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

# API key: List rules
curl -H "X-API-Key: your-secure-api-key" \
  http://localhost:4020/v1/rules

# Bearer JWT: 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). 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.

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

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

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.

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.

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 personalizados

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"
    }
  }'

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 é 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.

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:

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"
      }
    ]
  }'

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

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.

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 - aprenda a integrar seu sistema de autorização com o Tracer
Motor de regras - escreva regras de validação em CEL e gerencie seu ciclo de vida
Limites de gastos - configure e gerencie limites de gastos por escopo e período
Histórico de validação e compliance - 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 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.
Gerenciar limites: /v1/limits (CRUD + ciclo de vida + /usage). Veja o Guia de limites de gastos.

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.

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.

Visão geral

Guias

Console

Operações

Primeiros passos com o Tracer

Por que usar o Tracer

O que é o Tracer

Como funciona

Contextos principais

Pré-requisitos

Dependências de infraestrutura

Portas

Passo 1: execute o Tracer

Aplique o schema

Inicie o Tracer

Variáveis de ambiente essenciais

Passo 2: autentique-se na API

API Key

Bearer JWT

Exemplo de cURL

Passo 3: configure um limite de gastos

Tipos de limite

Escopos

Crie um limite

Ative um limite

Ciclo de vida do limite

Monitore o uso

Passo 4: valide sua primeira transação

Envie uma transação para validação

Passo 5: crie uma regra de validação

Ative uma regra

Ciclo de vida da regra

Observabilidade

Principais métricas

Verificação

Checklist

Próximos passos

Referência rápida

O que seu sistema deve fazer com cada decisão

​Por que usar o Tracer

​O que é o Tracer

​Como funciona

​Contextos principais

​Pré-requisitos

​Dependências de infraestrutura

​Portas

​Passo 1: execute o Tracer

​Aplique o schema

​Inicie o Tracer

​Variáveis de ambiente essenciais

​Passo 2: autentique-se na API

​API Key

​Bearer JWT

​Exemplo de cURL

​Passo 3: configure um limite de gastos

​Tipos de limite

​Escopos

​Crie um limite

​Ative um limite

​Ciclo de vida do limite

​Monitore o uso

​Passo 4: valide sua primeira transação

​Envie uma transação para validação

​Passo 5: crie uma regra de validação

​Ative uma regra

​Ciclo de vida da regra

​Observabilidade

​Principais métricas

​Verificação

​Checklist

​Próximos passos

​Referência rápida

​O que seu sistema deve fazer com cada decisão

Por que usar o Tracer

O que é o Tracer

Como funciona

Contextos principais

Pré-requisitos

Dependências de infraestrutura

Portas

Passo 1: execute o Tracer

Aplique o schema

Inicie o Tracer

Variáveis de ambiente essenciais

Passo 2: autentique-se na API

API Key

Bearer JWT

Exemplo de cURL

Passo 3: configure um limite de gastos

Tipos de limite

Escopos

Crie um limite

Ative um limite

Ciclo de vida do limite

Monitore o uso

Passo 4: valide sua primeira transação

Envie uma transação para validação

Passo 5: crie uma regra de validação

Ative uma regra

Ciclo de vida da regra

Observabilidade

Principais métricas

Verificação

Checklist

Próximos passos

Referência rápida

O que seu sistema deve fazer com cada decisão