Primeiros passos com o Tracer

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 ifs espalhados por vários serviços. Mudanças em regras sobem por API no mesmo dia, não na próxima release. O histórico de validações oferece um único lugar para investigar por que uma transação recebeu sua 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 para políticas e histórico de decisões — 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. Se já tem rodando e precisa da mecânica da API, vá direto para o Início rápido da API do Tracer.

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.

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
Histórico de validações: Decisões armazenadas para investigação e relatórios
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 — Figura 1. Como funciona o Tracer

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:

Contexto de Validação - Orquestra requisições, coordena avaliações e armazena o histórico de validações
Contexto de Regras - Gerencia definições de regras e avaliação de expressões
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 17 (o primário compartilhado do Midaz, iniciado pelo compose de infraestrutura da plataforma, não pelo do 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 `tracer` no primário PostgreSQL compartilhado do Midaz; ele não traz uma instância dedicada.

Portas

Portas padrão utilizadas pelos serviços do Tracer:

Serviço	Porta	Descrição
Tracer API	4020	API REST principal
PostgreSQL	5701	Primário PostgreSQL compartilhado do Midaz, como exposto pelo exemplo de infraestrutura distribuído (`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 Compose próprio do Tracer declara apenas dois serviços: a aplicação e um executor de migrações de uso único. O PostgreSQL não é um deles — ele vem do Compose de infraestrutura compartilhada da plataforma e precisa estar saudável primeiro. O contêiner da aplicação sobe somente depois que o executor de migrações aplicou o schema e encerrou com sucesso, então o serviço sempre inicia contra um banco já migrado.

No Midaz v4, o Tracer é source-available sob ELv2 no repositório e na release do Midaz. Mesmo assim, ele é implantado como serviço próprio; comece em components/tracer para desenvolvê-lo localmente.

Navegue até o diretório do projeto Tracer para iniciar os serviços:

cd components/tracer

# Configure o ambiente
cp .env.example .env

# Inicie todos os serviços (sobe primeiro a infraestrutura
# compartilhada, depois o executor de migrações e então o Tracer)
make up

Opção B: Execução local

Para desenvolvimento, você pode executar o Tracer localmente:

# 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 autenticação por API key e por plugin. A autenticação por plugin tem prioridade quando ambas estão habilitadas, exceto em endpoints configurados como somente API key.

Implantação e configuração de autenticação	Header de auth	Quando usar
Single-tenant, plugin habilitado	Header `Authorization` com token Bearer	`MULTI_TENANT_ENABLED=false` e `PLUGIN_AUTH_ENABLED=true`, exceto quando o endpoint está configurado como somente API key.
Single-tenant, API key	Header `X-API-Key`	`MULTI_TENANT_ENABLED=false` e plugin desabilitado, ou quando o endpoint está configurado como somente API key.
Multi-tenant (SaaS / BYOC Multi-Tenant)	Header `Authorization` com token Bearer	Qualquer implantação com `MULTI_TENANT_ENABLED=true`. O plugin é obrigatório; o JWT é emitido pelo Access Manager e carrega a claim `tenantId`.

Os passos restantes usam a forma single-tenant com API key porque a maior parte das configurações locais roda assim. Se a autenticação por plugin se aplicar à 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:

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

Bearer JWT (multi-tenant)

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

# Single-tenant: lista as regras
curl -H "X-API-Key: your-secure-api-key" \
  http://localhost:4020/v1/rules

# 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	Contagem por 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 1° do mês às 00:00 UTC
`CUSTOM`	Valor máximo para um intervalo de datas personalizado	Uma única contagem para todo o intervalo
`PER_TRANSACTION`	Valor máximo por transação individual	Nenhuma contagem é mantida

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.

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

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",
    "asset": "BRL",
    "scopes": [
      {
        "segmentId": "550e8400-e29b-41d4-a716-446655440000",
        "transactionType": "CARD"
      }
    ]
  }'

Ativar 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

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.

Monitore o uso

Toda resposta de POST /v1/validations carrega limitUsageDetails, com uma entrada por limite que o Tracer verificou: o teto, o valor tentado e o consumo projetado do período atual daquele teto se a transação for permitida. GET /v1/limits/{id}/usage informa um total acumulado entre os contadores do limite, para revisar o consumo geral. Para opções de configuração detalhadas, consulte 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 (tipo, valor, código de ativo, timestamp)
Informações da conta
Opcional: segmento, portfólio, comerciante e personalizada

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, e por isso o exemplo o gera: 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.

requestId é a chave de idempotência. Envie um UUID novo em cada tentativa — se você repetir um, o Tracer devolve a decisão que já registrou para essa chave, então uma regra que você ativou no meio não vai parecer surtir efeito.

O Tracer avalia as regras e limites que se aplicam à transação, 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.

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:

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

O Tracer preserva maiúsculas, minúsculas e espaços internos do nome, removendo apenas os espaços no início e no fim antes de salvar. Pegue o ruleId da resposta e use-o na chamada de ativação abaixo.

Ativar uma regra

curl -X POST http://localhost:4020/v1/rules/{id}/activate \
  -H "X-API-Key: your-secure-api-key"

A ativação passa a valer imediatamente na instância que atendeu a chamada, então em um setup de instância única a regra começa a ser avaliada na sua próxima validação. Quando você roda várias instâncias atrás de um balanceador, as outras pegam a mudança na próxima sincronização de regras (RULE_SYNC_POLL_INTERVAL_SECONDS, padrão 10); a desativação se propaga da mesma forma.

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.

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_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 HTTP de OpenTelemetry embutido no Tracer.

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 - Aprenda como 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ções e conformidade - Consulte o histórico de validações e use-o nos seus processos de conformidade

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 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, schemas de request/response e códigos de erro, consulte a referência da API.

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.

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: Configure o ambiente

Opção A: Docker Compose (recomendado)

Opção B: Execução local

Variáveis de ambiente essenciais

Passo 2: Autentique na API

API Key (single-tenant)

Bearer JWT (multi-tenant)

Exemplo com cURL

Passo 3: Configure um limite de gastos

Tipos de limite

Escopos

Criar um limite

Ativar 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

Ativar uma regra

Ciclo de vida da regra

Observabilidade

Métricas principais

Verificação

Lista de verificação

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: Configure o ambiente

​Opção A: Docker Compose (recomendado)

​Opção B: Execução local

​Variáveis de ambiente essenciais

​Passo 2: Autentique na API

​API Key (single-tenant)

​Bearer JWT (multi-tenant)

​Exemplo com cURL

​Passo 3: Configure um limite de gastos

​Tipos de limite

​Escopos

​Criar um limite

​Ativar 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

​Ativar uma regra

​Ciclo de vida da regra

​Observabilidade

​Métricas principais

​Verificação

​Lista de verificação

​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: Configure o ambiente

Opção A: Docker Compose (recomendado)

Opção B: Execução local

Variáveis de ambiente essenciais

Passo 2: Autentique na API

API Key (single-tenant)

Bearer JWT (multi-tenant)

Exemplo com cURL

Passo 3: Configure um limite de gastos

Tipos de limite

Escopos

Criar um limite

Ativar 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

Ativar uma regra

Ciclo de vida da regra

Observabilidade

Métricas principais

Verificação

Lista de verificação

Próximos passos

Referência rápida

O que seu sistema deve fazer com cada decisão