Guia de integração

Integrar o Tracer significa decidir em qual ponto do seu fluxo de autorização fazer a chamada de validação, quais dados enviar e como tratar as três decisões possíveis. O padrão é curto: seu sistema coleta o contexto completo da transação, chama POST /v1/validations, age sobre ALLOW / DENY / REVIEW e segue em frente. O Tracer nunca volta a chamar a sua stack — não há webhooks ou callbacks; a integração termina com a resposta. O que muda na sua operação: a decisão sai de lógica in-process e vai pra uma chamada externa. A chamada é síncrona (request/response, sem webhooks), então fica no caminho crítico da transação. Bem feita, adiciona menos de 80ms p99 e te dá um ponto único de política e auditoria. Mal feita — sem timeout, sem retry, sem fallback — vira um ponto único de falha. O trade-off honesto: você está adicionando um hop de rede. A boa notícia é que o contrato é simples: idempotente por requestId, sem callbacks, resposta determinística de três estados. A má notícia é que você precisa pensar em timeouts, retries e o que fazer se o Tracer estiver inalcançável — a maior parte deste guia é sobre isso.

Para quem é este guia? Engenheiros de integração escrevendo a requisição do seu sistema para o Tracer e arquitetos decidindo onde a chamada entra no fluxo. Analistas de risco/fraude que escrevem regras podem pular pro Guia do motor de regras; compliance pode ler o Guia de auditoria e conformidade.

Este guia cobre os requisitos de payload, o fluxo de integração e práticas que mantêm a chamada de validação dentro do seu budget de latência.

Visão geral da integração

O Tracer foi projetado para ser chamado por sistemas de autorização (gateways de pagamento, orquestradores de workflow ou processadores de transações) que precisam de decisões de validação em tempo real. A integração segue um padrão simples de requisição-resposta:

Princípio fundamental: O Tracer não busca dados externos durante a validação. Seu sistema é responsável por fornecer todo o contexto necessário para a avaliação das regras.

Padrão Payload-Complete

O Tracer usa o Padrão Payload-Complete, o que significa que todo o contexto necessário para a validação deve ser incluído na requisição. Este design garante:

Benefício	Descrição
Latência previsível	Sem chamadas externas durante a validação; tempo de resposta abaixo de 80ms
Simplicidade	Uma única requisição contém tudo necessário para a decisão
Confiabilidade	Sem dependência de serviços externos durante a validação
Flexibilidade	Seu sistema controla a atualização dos dados e a lógica de enriquecimento

Suas responsabilidades

Como sistema integrador, você é responsável por:

Enriquecer o payload com dados de conta, segmento, portfólio e comerciante antes de chamar o Tracer
Fornecer contexto preciso para avaliação de regras e limites—o Tracer não consegue buscar dados faltantes
Tratar a decisão (ALLOW, DENY ou REVIEW) adequadamente no seu fluxo de trabalho
Implementar lógica de retry se o Tracer estiver temporariamente indisponível
Gerenciar fluxos de revisão quando o Tracer retornar REVIEW—o Tracer não inclui gestão de casos

O Tracer valida o que você envia. Se o seu payload estiver faltando contexto (ex.: status da conta, associação ao segmento), regras que dependem desses dados não conseguem avaliar corretamente. Sempre garanta que os payloads estejam completos antes do envio.

Responsabilidades do Tracer

O Tracer é responsável por:

Avaliar regras contra o contexto fornecido
Verificar limites contra o uso atual
Registrar trilha de auditoria para conformidade
Retornar decisão com informações detalhadas

Fluxo de integração

Siga estes passos para integrar seu sistema com o Tracer.

Passo 1: Prepare o contexto da transação

Antes de chamar o Tracer, reúna todos os dados relevantes dos seus sistemas:

Passo 2: Chame a API do Tracer

Envie uma requisição POST para /v1/validations com o contexto completo da transação incluindo:

Detalhes da transação (tipo, subTipo, valor, moeda, timestamp)
Informações da conta (obrigatório)
Opcional: segmento, portfólio, comerciante e personalizada

Para a estrutura completa do payload e detalhes de campos, consulte a Referência da API.

Passo 3: Trate a resposta

Processe a decisão retornada pelo Tracer:

Decisão	Ação
`ALLOW`	Prossiga com a transação
`DENY`	Rejeite a transação; mostre o motivo ao usuário se apropriado
`REVIEW`	Enfileire para revisão manual no seu sistema de revisão

A resposta inclui o validationId para correlação da trilha de auditoria, detalhes sobre quais regras corresponderam e informações do uso atual do limite.

Usando metadata

Metadata permite passar campos personalizados que suas regras podem avaliar. Use para contexto como canal, informações do dispositivo, nível do cliente ou qualquer atributo específico do negócio.

As chaves de metadata devem ser alfanuméricas com underscores apenas, máximo de 64 caracteres. Máximo de 50 entradas por requisição.

Idempotência de requisições

Requisições de validação são idempotentes com base no campo requestId. Se você enviar o mesmo requestId duas vezes, o Tracer retorna o resultado em cache da primeira requisição ao invés de reprocessar.

Código de resposta	Significado
`201 Created`	Nova validação processada
`200 OK`	Requisição duplicada detectada; resultado em cache retornado

O corpo da resposta é idêntico em ambos os casos. Seu cliente deve tratar ambos os códigos de status como sucesso. Por que importa: Timeouts de rede e retentativas podem causar requisições duplicadas. Sem idempotência, uma requisição retentada poderia contabilizar duplicadamente contra limites ou criar registros de auditoria duplicados. O requestId garante semântica de processamento exactly-once. Contrato de idempotência:

Mesmo requestId → Mesma resposta (garantido)
requestId diferente → Processamento independente (mesmo com dados de transação idênticos)

Sempre gere um requestId único (UUID) para cada nova transação. Reutilizar um requestId de uma transação anterior retornará o resultado antigo, não processará a nova transação.

Autenticação

O Tracer suporta dois modos de autenticação que podem ser usados independentemente ou combinados.

Autenticação por API key

A opção mais simples. Envie sua API key no header X-API-Key em cada requisição.

Variável de ambiente	Descrição
`API_KEY_ENABLED`	Habilitar autenticação por API key (padrão: `false`)
`API_KEY`	O valor da chave secreta
`API_KEY_ENABLED_ONLY_VALIDATION`	Usar API key apenas para o endpoint `/v1/validations` (padrão: `false`)

Autenticação por plugin (Access Manager)

Para implantações enterprise, o Tracer pode delegar autenticação ao Lerian Access Manager. Isso habilita autenticação centralizada em todos os serviços Lerian.

Variável de ambiente	Descrição
`PLUGIN_AUTH_ENABLED`	Habilitar autenticação por plugin (padrão: `false`)
`PLUGIN_AUTH_ADDRESS`	URL do serviço de autenticação (padrão: `http://localhost:4000`)

Prioridade de autenticação

Quando ambos os modos estão habilitados, o Tracer usa esta prioridade:

Se PLUGIN_AUTH_ENABLED=true e o endpoint não está marcado para API-key-only → Autenticação por plugin
Se API_KEY_ENABLED=true ou o endpoint está marcado para API-key-only → Autenticação por API key

Endpoints de infraestrutura (health checks, sonda de versão, spec OpenAPI) ignoram autenticação e não fazem parte da superfície pública /v1/* documentada nesta referência.

O endpoint /v1/validations pode ser configurado para autenticação apenas por API key via API_KEY_ENABLED_ONLY_VALIDATION=true. Isso é útil em cenários de alta vazão onde a autenticação por plugin adiciona latência inaceitável. Essa flag é incompatível com o modo multi-tenant (MULTI_TENANT_ENABLED=true) — o serviço não inicia, falhando com TRC-0327.

Autenticação multi-tenant

Quando MULTI_TENANT_ENABLED=true, o Tracer roda em modo multi-tenant e o modelo de autenticação muda:

Plugin auth é obrigatório. O serviço falha ao iniciar com TRC-0326 se PLUGIN_AUTH_ENABLED=false.
Toda requisição /v1/* deve carregar um JWT bearer token emitido pelo Access Manager: Authorization: Bearer <jwt>.
O tenantId é resolvido a partir da claim do JWT, não de um header, path, body, metadata ou escopo de regra. Não existe header X-Tenant-ID — passar o identificador do tenant em qualquer outro lugar que não seja a claim do token é não suportado e ignorado.
Cada tenant opera em seu próprio banco PostgreSQL. A conexão específica do tenant é resolvida pelo Tenant Manager da plataforma no momento da requisição.
Endpoints públicos (/health, /readyz, /version, /swagger/*) seguem sem autenticação em modo multi-tenant — a exigência de bearer token aplica-se apenas a /v1/*.

Se o JWT estiver ausente, malformado ou expirado, a requisição retorna HTTP 401 com "code": "Unauthenticated" (o mesmo código usado para API key ausente; nenhum código TRC separado é emitido). Se a implantação multi-tenant atingir seu cap por instância de tenants ativos, requisições para tenants frios retornam HTTP 503 com TRC-0335 e um header Retry-After. O cliente deve fazer backoff e tentar novamente; o cap reseta automaticamente conforme o pool LRU eviciona tenants frios. Consulte Multi-tenancy para o modelo de tenants da plataforma.

Considerações de desempenho

Otimize sua integração para baixa latência e alta confiabilidade.

Limite de tempo

O Tracer foi projetado para responder em menos de 80ms (p99). Configure o timeout do seu cliente adequadamente:

Configuração	Valor recomendado
Timeout do cliente	100ms
Timeout de conexão	50ms
Timeout de leitura	100ms

Estratégia de retry

Implemente lógica de retry para falhas transitórias:

Em erro 5xx ou timeout:
  - Aguarde 10ms
  - Tente novamente uma vez
  - Se ainda falhar, aplique política de fallback

Não faça retry em erros 4xx - estes indicam requisições inválidas que falharão novamente. Ao fazer retry de erros 5xx ou timeouts, reutilize o mesmo requestId para garantir idempotência e evitar processamento duplicado.

Comportamento de fallback

Decida o que acontece quando o Tracer está indisponível:

Estratégia	Quando usar
Fail-open	Permita a transação se o Tracer estiver fora (priorize disponibilidade)
Fail-closed	Negue a transação se o Tracer estiver fora (priorize segurança)
Enfileirar para revisão	Enfileire a transação para revisão manual

Sua escolha depende da sua tolerância a riscos e requisitos de negócio.

Tropeços comuns na integração:

“Minha retentativa criou uma validação duplicada na trilha de auditoria.” Reuse o mesmo requestId em todas as retentativas. O Tracer deduplica por esse campo — a segunda chamada retorna o resultado em cache (HTTP 200) sem criar um evento duplicado. Se você gera um UUID novo a cada retry, perde a idempotência.
“Meu cliente tem timeout de 30 segundos mas o Tracer continua processando.” O Tracer respeita seus próprios deadlines (alvo ~80ms p99). Se seu cliente desiste da chamada, o trabalho do Tracer já vai ser jogado fora ao retornar a resposta. Configure o timeout do cliente agressivamente (100ms) e confie no caminho de retry.
“Minha validação está sendo rejeitada com TRC-0228 (timestamp muito antigo) em transações legítimas.” A tolerância padrão é 24 horas. Confira o relógio do servidor e o transactionTimestamp que você está enviando — se você processa em lote com atraso, precisa setar o timestamp pro momento real da transação, não pro momento da chamada ao Tracer.
“Transações de teste aparecem na auditoria de produção.” Todas as validações são registradas, inclusive de ambientes de teste/staging que chamam a mesma instância do Tracer. Use metadata.environment (ou similar) pra tagear e filtrar tráfego de teste se você compartilha Tracer entre ambientes.

Atualização dos dados

Como você controla o enriquecimento do payload, a atualização dos dados é sua responsabilidade. O Tracer confia nos dados que você fornece e não consegue detectar informações desatualizadas.

Tipo de dado	Recomendação de atualização	Risco se desatualizado
Status da conta	Tempo real ou quase tempo real	Transações em contas suspensas podem ser permitidas
Associação ao segmento	Pode ser cacheado (muda com pouca frequência)	Limites ou regras erradas podem ser aplicadas
Atribuição de portfólio	Pode ser cacheado (muda com pouca frequência)	Correspondência de escopo incorreta
Dados do comerciante	Pode ser cacheado com atualização periódica	Regras de risco podem não disparar corretamente

Dados desatualizados levam a decisões incorretas. Se uma conta foi suspensa mas seu cache mostra como ativa, o Tracer permitirá transações que deveriam ser negadas. Sua camada de enriquecimento é a fonte de verdade para o Tracer.

Formato de data e hora

Todos os campos datetime devem usar formato RFC3339 com timezone obrigatório: Formatos válidos:

2026-01-30T10:30:00Z           (UTC)
2026-01-30T10:30:00-03:00      (fuso horário de São Paulo)
2026-01-30T00:00:00+00:00      (UTC explícito)

Formatos inválidos:

2026-01-30                     (apenas data - rejeitado)
2026-01-30T10:30:00            (faltando timezone - rejeitado)

Lista de verificação da integração

Antes de ir para produção, verifique:

Exemplo de integração (pseudocódigo)

def validate_transaction(transaction):
    # Passo 1: Enriquecer payload
    payload = {
        "requestId": generate_uuid(),
        "transactionType": transaction.type,
        "amount": transaction.amount,
        "currency": transaction.currency.upper(),
        "transactionTimestamp": now_rfc3339(),
        "account": get_account_context(transaction.account_id),
        "segment": get_segment_context(transaction.segment_id),
        "merchant": get_merchant_context(transaction.merchant_id),
        "metadata": transaction.custom_fields
    }

    # Passo 2: Chamar Tracer
    try:
        response = http_post(
            url="https://tracer.example.com/v1/validations",
            headers={"X-API-Key": API_KEY},
            json=payload,
            timeout_ms=100
        )
    except Timeout:
        return apply_fallback_policy()
    except ServerError:
        return retry_once_or_fallback()

    # Passo 3: Tratar decisão
    if response.decision == "ALLOW":
        return proceed_with_transaction()
    elif response.decision == "DENY":
        return reject_transaction(response.reason)
    elif response.decision == "REVIEW":
        return queue_for_manual_review(response.validationId)

Próximos passos

Motor de regras - Crie regras que avaliam contra o contexto que você fornece
Limites de gastos - Configure limites que se aplicam aos escopos das suas transações
Auditoria e conformidade - Consulte o histórico de validações e a trilha de auditoria

Documentation Index

​Visão geral da integração

​Padrão Payload-Complete

​Suas responsabilidades

​Responsabilidades do Tracer

​Fluxo de integração

​Passo 1: Prepare o contexto da transação

​Passo 2: Chame a API do Tracer

​Passo 3: Trate a resposta

​Usando metadata

​Idempotência de requisições

​Autenticação

​Autenticação por API key

​Autenticação por plugin (Access Manager)

​Prioridade de autenticação

​Autenticação multi-tenant

​Considerações de desempenho

​Limite de tempo

​Estratégia de retry

​Comportamento de fallback

​Atualização dos dados

​Formato de data e hora

​Lista de verificação da integração

​Exemplo de integração (pseudocódigo)

​Próximos passos

Visão geral da integração

Padrão Payload-Complete

Suas responsabilidades

Responsabilidades do Tracer

Fluxo de integração

Passo 1: Prepare o contexto da transação

Passo 2: Chame a API do Tracer

Passo 3: Trate a resposta

Usando metadata

Idempotência de requisições

Autenticação

Autenticação por API key

Autenticação por plugin (Access Manager)

Prioridade de autenticação

Autenticação multi-tenant

Considerações de desempenho

Limite de tempo

Estratégia de retry

Comportamento de fallback

Atualização dos dados

Formato de data e hora

Lista de verificação da integração

Exemplo de integração (pseudocódigo)

Próximos passos