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

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:

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

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

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

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

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

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

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.

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.

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

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": [
      {
        "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

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

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

Opção A: Docker Compose (recomendado)

Opção B: execução local

Variáveis de ambiente essenciais

Passo 2: autentique-se na API

API Key (single-tenant)

Bearer JWT (multi-tenant)

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

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

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

​Variáveis de ambiente essenciais

​Passo 2: autentique-se na API

​API Key (single-tenant)

​Bearer JWT (multi-tenant)

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

Opção A: Docker Compose (recomendado)

Opção B: execução local

Variáveis de ambiente essenciais

Passo 2: autentique-se na API

API Key (single-tenant)

Bearer JWT (multi-tenant)

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