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. Auditoria deixa de ser “vou montar logs de N sistemas e cruzar timestamps” para virar “este é o registro imutável de por que esta transação recebeu esta 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 de política, auditoria e analytics — 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 pro 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
completa: Registros de validação imutáveis para conformidade SOX/GLBA
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

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, registra trilha de auditoria
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.25.7+ (para desenvolvimento local)
PostgreSQL 16+ (incluído no Docker Compose)
API Key para autenticação

Dependências de infraestrutura

O Tracer requer os seguintes componentes:

Componente	Versão	Finalidade
PostgreSQL	16+	Persistência de dados e trilha de auditoria

Portas

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

Serviço	Porta	Descrição
Tracer API	4020	API REST principal
PostgreSQL	5432	Banco de dados

Passo 1: Configure o ambiente

Você pode executar o Tracer com Docker Compose ou localmente para desenvolvimento.

Opção A: Docker Compose (recomendado)

Esta é a forma mais rápida de começar. O PostgreSQL inicia automaticamente com o serviço.

O Tracer está disponível para clientes licenciados; seu repositório é mantido internamente. Os passos a seguir presumem que você já tem acesso aos arquivos do projeto Tracer necessários.

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

cd tracer

# Configure o ambiente
cp .env.example .env

# Inicie todos os serviços
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 dois modos de autenticação. Qual você usa depende da topologia de implantação:

Implantação	Header de auth	Quando usar
Single-tenant	`X-API-Key: <api-key>`	Desenvolvimento local, BYOC single-customer, ou qualquer implantação com `MULTI_TENANT_ENABLED=false` (padrão).
Multi-tenant (SaaS / BYOC Multi-Tenant)	`Authorization: Bearer <jwt>`	Qualquer implantação com `MULTI_TENANT_ENABLED=true`. O JWT é emitido pelo Access Manager e carrega a claim `tenantId`.

Os passos restantes deste guia usam a forma single-tenant (API Key) porque a maior parte das configurações locais de desenvolvimento roda assim. Se seu ambiente for multi-tenant, 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.lerian.io/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	Comportamento de reset
`DAILY`	Valor máximo por dia	Reseta à meia-noite UTC
`WEEKLY`	Valor máximo por semana	Reseta toda segunda-feira à meia-noite UTC
`MONTHLY`	Valor máximo por mês	Reseta no 1° do mês
`CUSTOM`	Valor máximo para um intervalo de datas personalizado	Reseta ao final do período personalizado
`PER_TRANSACTION`	Valor máximo por transação individual	Não requer rastreamento

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",
    "currency": "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

Consulte GET /v1/limits/{id}/usage para verificar o consumo atual. O indicador nearLimit fica true quando a utilização é estritamente maior que 80% (utilizationPercent > 80), dando aos operadores um aviso antes que o limite seja excedido. 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, moeda, timestamp)
Informações da conta
Opcional: segmento, portfólio, comerciante e personalizada

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",
    "currency": "BRL",
    "transactionTimestamp": "2026-02-20T12:00:00Z",
    "account": {
      "id": "550e8400-e29b-41d4-a716-446655440100"
    },
    "merchant": {
      "id": "550e8400-e29b-41d4-a716-446655440103",
      "category": "5411",
      "name": "Test Merchant"
    },
    "metadata": {
      "channel": "mobile"
    }
  }'

O transactionTimestamp deve ser recente: timestamps no futuro são rejeitados com TRC-0226 (tolerância de 1 minuto de dessincronização de relógio), e timestamps com mais de 24 horas são rejeitados com TRC-0228.

O Tracer avalia todas as regras e limites ativos, 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 pra analytics. Ao retornar a decisão, o Tracer encaixa em qualquer fluxo de autorização sem ser dono da UX voltada pro 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"
      }
    ]
  }'

Ativar uma regra

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

Regras ativas são servidas a partir de um cache em memória que atualiza a cada RULE_SYNC_POLL_INTERVAL_SECONDS (padrão 10). Regras recém-ativadas podem levar até ~10 segundos para começar a ser avaliadas, e desativações entram em vigor no próximo sync. Planeje os testes de integração de acordo.

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_audit_persist_failures_total - Falhas de persistência de registro de auditoria (risco de conformidade)
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 OpenTelemetry Fiber.

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
Auditoria e conformidade - Consulte o histórico de validações e entenda a trilha de auditoria

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.

​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