Primeiros passos com o 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.

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
Trilha de auditoria 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.5+ (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	8080	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.

Clone o repositório e inicie os serviços:

# Clone o repositório
git clone https://github.com/lerianstudio/tracer.git
cd tracer

# Configure o ambiente
cp .env.example .env

# Inicie todos os serviços
make up

Verifique a saúde do serviço:

# Verifique a saúde do Tracer
curl http://localhost:8080/health

# Verifique a prontidão (conexão com banco de dados)
curl http://localhost:8080/ready

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="8080"
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	`8080`
`LOG_LEVEL`	Nível de log	`INFO`, `DEBUG`, `ERROR`

Passo 2: Autentique na API

O Tracer usa autenticação por API Key para todas as requisições.

Autenticação por API Key

Inclua a API Key no header X-API-Key:

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

Exemplo com cURL

# Verifique a saúde da API (sem autenticação necessária)
curl http://localhost:8080/health

# Liste as regras (autenticado)
curl -H "X-API-Key: your-secure-api-key" \
  http://localhost:8080/v1/rules

As API Keys devem ser mantidas em segurança. Nunca exponha sua API Key em código do lado do cliente ou repositórios públicos.

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
`MONTHLY`	Valor máximo por mês	Reseta no 1° do mês
`PER_TRANSACTION`	Valor máximo por transação individual	Não requer rastreamento

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

Ciclo de vida do limite

Limites seguem o mesmo ciclo de vida das regras: DRAFT → ACTIVE → INACTIVE. Ative um limite para começar a aplicação.

Monitore o uso

Consulte GET /v1/limits/{limitId}/usage para verificar o consumo atual. O indicador nearLimit é ativado em 80% de utilização para gestão proativa. 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 metadata personalizada

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. 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, você pode criar uma regra com:

Expressão: amount > 1000000 (valores acima de R$ 10.000)
Ação: DENY
Escopo: Aplicar apenas a transações CARD

Ciclo de vida da regra

Regras são criadas com status DRAFT. Para iniciar a avaliação, ative a regra usando POST /v1/rules/{ruleId}/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.

Endpoints de saúde

Endpoint	Descrição
`GET /health`	Verificação de vivacidade (aplicação em execução)
`GET /ready`	Verificação de prontidão (banco de dados disponível)

Métricas principais

O Tracer expõe métricas compatíveis com Prometheus:

tracer_validations_total{decision} - Total de validações por decisão
tracer_validation_duration_seconds - Histograma de latência de validação
tracer_rule_evaluations_total - Total de avaliações de regras
tracer_limit_checks_total{result} - Verificações de limite por resultado
tracer_auth_failures_total{reason} - Falhas de autenticação por motivo
tracer_active_rules - Número de regras ativas

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

Teste de conectividade

# Verifique a saúde da API (vivacidade)
curl http://localhost:8080/health

# Verifique a prontidão (conexão com banco de dados)
curl http://localhost:8080/ready

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 - Crie regras de validação sofisticadas com expressões CEL
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

Endpoints e conceitos-chave para consulta rápida.

Endpoints principais

Operação	Método	Endpoint
Verificação de saúde	GET	`/health`
Verificação de prontidão	GET	`/ready`
Validar transação	POST	`/v1/validations`
Obter validação	GET	`/v1/validations/{validationId}`
Listar validações	GET	`/v1/validations`
Criar limite	POST	`/v1/limits`
Obter limite	GET	`/v1/limits/{limitId}`
Atualizar limite	PATCH	`/v1/limits/{limitId}`
Obter uso do limite	GET	`/v1/limits/{limitId}/usage`
Criar regra	POST	`/v1/rules`
Obter regra	GET	`/v1/rules/{ruleId}`
Atualizar regra	PATCH	`/v1/rules/{ruleId}`
Ativar regra	POST	`/v1/rules/{ruleId}/activate`
Desativar regra	POST	`/v1/rules/{ruleId}/deactivate`
Excluir regra	DELETE	`/v1/rules/{ruleId}`

Tipos de transação

Tipo	Descrição	Exemplos de subType
`CARD`	Transações baseadas em cartão	`debit`, `credit`, `prepaid`
`WIRE`	Transferências bancárias	`domestic`, `international`, `ach`
`PIX`	Pagamento instantâneo brasileiro	`instant`, `scheduled`
`CRYPTO`	Criptomoeda	`bitcoin`, `ethereum`, `stablecoin`

Tipos de decisão

Decisão	Descrição	Seu sistema deve
`ALLOW`	Tracer recomenda aprovação	Prosseguir com a transação
`DENY`	Tracer recomenda negação	Bloquear a transação e informar o usuário
`REVIEW`	Tracer recomenda 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

​Autenticação por API Key

​Exemplo com cURL

​Passo 3: Configure um limite de gastos

​Tipos de limite

​Escopos

​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

​Ciclo de vida da regra

​Observabilidade

​Endpoints de saúde

​Métricas principais

​Verificação

​Lista de verificação

​Teste de conectividade

​Próximos passos

​Referência rápida

​Endpoints principais

​Tipos de transação

​Tipos de 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

Autenticação por API Key

Exemplo com cURL

Passo 3: Configure um limite de gastos

Tipos de limite

Escopos

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

Ciclo de vida da regra

Observabilidade

Endpoints de saúde

Métricas principais

Verificação

Lista de verificação

Teste de conectividade

Próximos passos

Referência rápida

Endpoints principais

Tipos de transação

Tipos de decisão