Guia de integração

Este guia explica como integrar sistemas externos com o Tracer, incluindo os requisitos de payload, fluxo de integração e melhores práticas para alcançar desempenho ideal.

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

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.

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.

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:

API Key está configurada e segura
Timeout do cliente está definido para 100ms
Lógica de retry está implementada para erros 5xx
Comportamento de fallback está definido
Todos os campos obrigatórios estão preenchidos
Timestamps usam formato RFC3339 com timezone
Códigos de moeda estão em maiúsculas ISO 4217
Tratamento de decisão está implementado (ALLOW/DENY/REVIEW)
IDs de validação estão sendo logados para correlação na trilha de auditoria

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(),
        "timestamp": 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

​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

​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

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