Guia de integração

Integrar o Tracer significa decidir em que 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 de acordo com ALLOW / DENY / REVIEW e segue em frente. O Tracer nunca chama de volta a sua stack. Não há webhooks nem callbacks, e a integração termina com a resposta. O que muda na sua operação: a decisão deixa de ser lógica em processo e passa a ser uma chamada externa. A chamada é síncrona (requisição/resposta, sem webhooks), então ela fica no caminho crítico da transação. Bem feita, ela adiciona menos de 80ms p99 e te dá um ponto único para política e histórico de validação. Malfeita (sem timeout, sem estratégia de nova tentativa, sem fallback), ela se torna um ponto único de falha. Trade-off para ser honesto: você está adicionando um salto 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ê deve pensar em timeouts, novas tentativas e o que fazer se o Tracer estiver inacessível. A maior parte deste guia é sobre isso.

Para quem é este guia? Engenheiros de integração que escrevem a requisição do seu sistema para o Tracer, e arquitetos que decidem em que ponto do fluxo a chamada fica. Analistas de risco e fraude que escrevem regras podem pular direto para o guia do motor de regras. O compliance pode ler o guia de auditoria e compliance em vez disso.

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 orçamento de latência. O Tracer fica fora do seu ledger: ele nunca chama o Midaz. Sua aplicação orquestra os dois. Ela chama o Tracer para validar e envia a transação para o Midaz apenas se a decisão for ALLOW. O Tracer avalia suas políticas e limites configurados em relação ao contexto que você envia, não aos saldos das contas. O ledger continua sendo a fonte da verdade para o que uma conta possui.

O Midaz também pode direcionar o Tracer por meio de um seam opcional por ledger. Ele continua sendo unidirecional, Ledger → Tracer. O restante deste guia cobre o padrão HTTP orquestrado pela aplicação. O contrato do seam aparece abaixo.

Visão geral da integração

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

Integração de requisição-resposta em que um sistema de autorização chama o Tracer para uma decisão de validação e apenas envia a transação ao Midaz quando a decisão é ALLOW — Figura 1. Visão geral da integração com o Tracer

Princípio-chave: o Tracer não busca dados externos durante a validação. Seu sistema deve fornecer todo o contexto necessário para a avaliação das regras.

Seam de reserva do Midaz Ledger

Este seam opcional pertence ao Ledger HTTP v2, não ao Tracer HTTP v2. O Ledger HTTP v1 nunca o invoca. A API HTTP pública do Tracer continua sendo apenas v1, incluindo suas operações de reserva em /v1. O serviço gRPC lerian.midaz.reservation.v1.ReservationService é um transporte interno de serviço para serviço, não uma API v2 pública. Defina TRACER_BASE_URL para injetar o seam. Quando ela não está definida, o Ledger não faz nenhuma chamada de reserva. O Ledger chama o cliente injetado apenas quando o tracer.mode por ledger é advisory ou enforce. Um modo não definido ou off ainda ignora as reservas mesmo quando você define TRACER_BASE_URL. Um skip por chamada respeitado também contorna o seam. O gRPC é o transporte padrão: configure TRACER_GRPC_PORT no Tracer e aponte TRACER_BASE_URL para esse listener gRPC. Com TRACER_TRANSPORT=rest, aponte-o para o listener HTTP do Tracer em vez disso. Os dois transportes usam o mesmo serviço de reserva e as mesmas cinco transições:

Transição	Ação do Ledger
`Reserve`	Retém capacidade de limite antes que a transação seja commitada. As novas tentativas são idempotentes na granularidade `(transactionId, limitId, scopeKey, periodKey)`.
`ConfirmByTransaction`	Commita todas as retenções de uma transação; uma nova tentativa após o estado terminal não tem efeito e pode retornar `flipped=0`.
`ReleaseByTransaction`	Retorna todas as retenções de uma transação; uma nova tentativa após o estado terminal não tem efeito e pode retornar `flipped=0`.
`Confirm`	Commita uma retenção; uma nova tentativa em uma reserva terminal não tem efeito.
`Release`	Retorna uma retenção; uma nova tentativa em uma reserva terminal não tem efeito.

Para chamadas multi-tenant, o REST encaminha o tenant no header X-Tenant-Id, e o gRPC o encaminha como metadados x-tenant-id. Nenhum dos dois transportes o coloca na mensagem de reserva. O listener apenas pode confiar nesse valor via mTLS direto ou atrás de um sidecar service-mesh verificado. Com TRACER_TLS_MODE=mtls, cada lado apresenta e verifica certificados. Os modos de TLS mesh e vazio exigem um sidecar que exija mTLS. Sem um, a conexão entre o processo e o listener é em texto simples, e um chamador não confiável pode falsificar o tenant. O Tracer habilita seu listener gRPC apenas quando você define TRACER_GRPC_PORT. A semântica de falha é explícita. Uma negação de reserva é uma resposta bem-sucedida, não um erro de transporte. O modo advisory registra o resultado e segue em frente. O modo enforce rejeita a transação antes de qualquer movimentação de saldo, independentemente de failPosture. A configuração failPosture se aplica a qualquer erro de chamada de reserva: closed rejeita e open segue em frente sem uma reserva. Falhas de confirmação e liberação são operações de nível de aviso, não bloqueantes. O reaper de TTL do Tracer reconcilia uma transição terminal perdida.

Padrão Payload-Complete

O Tracer usa o Padrão Payload-Complete. Cada requisição deve carregar todo o contexto necessário para a validação. Esse design garante:

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

Suas responsabilidades

Como o sistema que integra, 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 a avaliação de regras e limites. O Tracer não pode buscar dados ausentes
Tratar a decisão (ALLOW, DENY ou REVIEW) de forma adequada no seu workflow
Implementar a lógica de novas tentativas se o Tracer estiver temporariamente indisponível
Gerenciar workflows de revisão quando o Tracer retorna REVIEW. O Tracer não inclui gestão de casos

O Tracer valida o que você envia. Se o seu payload não tiver contexto (por exemplo, status da conta, associação ao segmento), as regras que dependem desses dados não podem ser avaliadas corretamente. Sempre garanta que os payloads estejam completos antes do envio.

Responsabilidades do Tracer

O Tracer é responsável por:

Avaliar regras em relação ao contexto fornecido
Verificar limites em relação ao uso atual
Armazenar o histórico de validação para investigação e geração de relatórios
Retornar a decisão com informações detalhadas

Fluxo de integração

Siga estas etapas para integrar seu sistema com o Tracer.

Etapa 1: Preparar o contexto da transação

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

Etapas para preparar o contexto da transação e chamar o Tracer, desde reunir dados nos seus sistemas até agir sobre a decisão retornada — Figura 2. Preparando o contexto da transação

Etapa 2: Chamar 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, ativo, timestamp)
Informações da conta (obrigatório)
Opcional: segmento, portfólio, comerciante e personalizados

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

Etapa 3: Tratar 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`	Coloque na fila para revisão manual no seu sistema de revisão

A resposta inclui o validationId para correlação com o histórico de validação, detalhes sobre quais regras corresponderam e informações sobre o uso atual dos limites.

Usando metadados

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

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

Idempotência de requisição

As 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 em vez 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. Recomenda-se que seu cliente trate os dois códigos de status como sucesso. Por que isso importa: timeouts de rede e novas tentativas podem causar requisições duplicadas. Sem idempotência, uma requisição repetida pode contar em dobro contra os limites ou criar registros de validação duplicados. O requestId garante semântica de processamento exatamente uma vez. Contrato de idempotência:

Mesmo requestId → Mesma resposta (garantido)
requestId diferente → Processamento independente (mesmo que os dados da transação sejam idênticos)

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

Autenticação

O Tracer aceita dois modos de autenticação. Você pode usá-los de forma independente ou em conjunto.

Autenticação por chave de API

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

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

Autenticação via plugin (Access Manager)

Para deploys enterprise, o Tracer pode delegar a autenticação ao Lerian Access Manager. Isso permite autenticação centralizada em todos os serviços da Lerian.

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

Prioridade de autenticação

Quando você habilita os dois modos, o Tracer usa esta prioridade:

Se PLUGIN_AUTH_ENABLED=true e o endpoint não tiver a flag de apenas chave de API → autenticação via plugin
Se API_KEY_ENABLED=true ou o endpoint carregar a flag de apenas chave de API → autenticação por chave de API

Os endpoints de infraestrutura (health checks, sondagem de versão, especificação OpenAPI) contornam a autenticação e não fazem parte da superfície pública da API /v1/* documentada nesta referência.

Você pode configurar o endpoint /v1/validations para autenticação apenas por chave de API via API_KEY_ENABLED_ONLY_VALIDATION=true. Isso é útil em cenários de alta taxa de transferência em que a autenticação via plugin adiciona latência inaceitável. Essa flag é incompatível com o modo multi-tenant (MULTI_TENANT_ENABLED=true). O serviço falha ao iniciar com o código de erro 0458.

Autenticação multi-tenant

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

A autenticação via plugin é obrigatória. O serviço falha ao iniciar com o código de erro 0457 se PLUGIN_AUTH_ENABLED=false.
Cada requisição para /v1/* deve carregar um token bearer JWT emitido pelo Access Manager: Authorization: Bearer <jwt>.
tenantId vem da claim do JWT, não de um header, path, body, metadados ou escopo de regra. Não existe um header X-Tenant-ID. O identificador do tenant não tem efeito em nenhum outro lugar além da claim do token.
Cada tenant opera no seu próprio banco de dados PostgreSQL. O serviço de plataforma multi-tenancy resolve a conexão específica do tenant no momento da requisição.
Endpoints públicos (/health, /readyz, /metrics, /version) continuam sem autenticação também no modo multi-tenant. O requisito de token bearer se aplica apenas a /v1/*.

Se o JWT estiver ausente, malformado ou expirado, a requisição retorna HTTP 401 com "code": "Unauthenticated". Chaves de API ausentes retornam o mesmo código, sem um código TRC separado. Um caso é diferente. Um token que é analisado, mas não carrega a claim sub, retorna HTTP 401 e o código de erro 0474 de imediato. A claim sub é o que o escritor de auditoria usa para atribuir a ação a um principal. O Tracer falha de forma explícita em vez de registrar a mudança contra um ator de sistema genérico. Garanta que seus tokens do Access Manager sempre a carreguem. Se o deploy multi-tenant atingir seu limite de tenants por instância, as requisições para tenants frios retornam HTTP 503 com o código de erro 0466 e um header Retry-After. Recomenda-se que o cliente aplique backoff e tente novamente. O limite se reajusta automaticamente à medida que o pool LRU remove os tenants frios. Consulte Multi-tenancy para o modelo de tenant em toda a plataforma.

Considerações de desempenho

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

Orçamento de timeout

O Tracer visa uma resposta em menos de 80ms (p99). Configure o timeout do seu cliente de acordo:

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

Estratégia de novas tentativas

Implemente a lógica de novas tentativas para falhas transitórias:

On 5xx error or timeout:
  - Wait 10ms
  - Retry once
  - If still failing, apply fallback policy

Não tente novamente em erros 4xx. Eles indicam requisições inválidas que vão falhar de novo. Para novas tentativas em 5xx/timeout, reutilize o mesmo requestId para aproveitar a idempotência.

Comportamento de fallback

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

Estratégia	Quando usar
Fail-open	Permite a transação se o Tracer estiver fora do ar (prioriza disponibilidade)
Fail-closed	Nega a transação se o Tracer estiver fora do ar (prioriza segurança)
Queue for review	Coloca a transação na fila para revisão manual

Sua escolha depende da sua tolerância a risco e dos requisitos do negócio.

Armadilhas comuns de integração:

“Minha nova tentativa criou uma validação duplicada.” Reutilize o mesmo requestId entre as novas tentativas. O Tracer deduplica por esse campo. A segunda chamada retorna o resultado em cache (HTTP 200) sem criar outra validação. Se você gerar um UUID novo a cada nova tentativa, você anula a idempotência.
“Meu cliente sofre timeout depois de 30 segundos, mas o Tracer continua processando.” O Tracer respeita seus próprios prazos (meta de ~80ms p99). Se o seu cliente desiste da chamada, o Tracer ainda gasta esse trabalho em uma resposta. Configure o timeout do cliente de forma agressiva (100ms) e confie no caminho de nova tentativa.
“O Tracer rejeita minha validação com o código de erro 0421 (timestamp muito antigo) em transações legítimas.” A tolerância padrão é de 24 horas. Verifique o relógio do seu servidor e o transactionTimestamp que você está enviando. Se você processa em lote com atraso, defina o timestamp para o momento real da transação, não o momento em que você está chamando o Tracer.
“Transações de teste aparecem no histórico de validação de produção.” O Tracer registra cada validação, inclusive as de ambientes de teste/staging que chamam a mesma instância do Tracer. Use metadata.environment (ou similar) para marcar e filtrar tráfego de teste se você compartilhar o Tracer entre ambientes.

Atualidade dos dados

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

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

Dados desatualizados levam a decisões incorretas. Se você suspendeu uma conta, mas seu cache mostra ela como ativa, o Tracer vai permitir transações que deveria negar. Sua camada de enriquecimento é a fonte da verdade para o Tracer.

Formato de data e hora

Todos os campos de datetime devem usar o formato RFC3339 com fuso horário obrigatório: Formatos válidos:

2026-01-30T10:30:00Z           (UTC)
2026-01-30T10:30:00-03:00      (São Paulo timezone)
2026-01-30T00:00:00+00:00      (UTC explicit)

Formatos inválidos:

2026-01-30                     (date only - rejected)
2026-01-30T10:30:00            (missing timezone - rejected)

Checklist de integração

Antes de ir para produção, verifique:

Exemplo de integração (pseudocódigo)

def validate_transaction(transaction):
    # Step 1: Enrich payload
    payload = {
        "requestId": generate_uuid(),
        "transactionType": transaction.type,
        "amount": transaction.amount,
        "asset": transaction.asset.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
    }

    # Step 2: Call 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()

    # Step 3: Handle decision
    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 o contexto que você fornece
Limites de gastos - Configure limites que se aplicam aos escopos das suas transações
Histórico de validação e compliance - Consulte o histórico de validação e use-o nos seus processos de compliance

Visão geral

Guias

Console

Operações

Guia de integração

Visão geral da integração

Seam de reserva do Midaz Ledger

Padrão Payload-Complete

Suas responsabilidades

Responsabilidades do Tracer

Fluxo de integração

Etapa 1: Preparar o contexto da transação

Etapa 2: Chamar a API do Tracer

Etapa 3: Tratar a resposta

Usando metadados

Idempotência de requisição

Autenticação

Autenticação por chave de API

Autenticação via plugin (Access Manager)

Prioridade de autenticação

Autenticação multi-tenant

Considerações de desempenho

Orçamento de timeout

Estratégia de novas tentativas

Comportamento de fallback

Atualidade dos dados

Formato de data e hora

Checklist de integração

Exemplo de integração (pseudocódigo)

Próximos passos

​Visão geral da integração

​Seam de reserva do Midaz Ledger

​Padrão Payload-Complete

​Suas responsabilidades

​Responsabilidades do Tracer

​Fluxo de integração

​Etapa 1: Preparar o contexto da transação

​Etapa 2: Chamar a API do Tracer

​Etapa 3: Tratar a resposta

​Usando metadados

​Idempotência de requisição

​Autenticação

​Autenticação por chave de API

​Autenticação via plugin (Access Manager)

​Prioridade de autenticação

​Autenticação multi-tenant

​Considerações de desempenho

​Orçamento de timeout

​Estratégia de novas tentativas

​Comportamento de fallback

​Atualidade dos dados

​Formato de data e hora

​Checklist de integração

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

​Próximos passos

Visão geral da integração

Seam de reserva do Midaz Ledger

Padrão Payload-Complete

Suas responsabilidades

Responsabilidades do Tracer

Fluxo de integração

Etapa 1: Preparar o contexto da transação

Etapa 2: Chamar a API do Tracer

Etapa 3: Tratar a resposta

Usando metadados

Idempotência de requisição

Autenticação

Autenticação por chave de API

Autenticação via plugin (Access Manager)

Prioridade de autenticação

Autenticação multi-tenant

Considerações de desempenho

Orçamento de timeout

Estratégia de novas tentativas

Comportamento de fallback

Atualidade dos dados

Formato de data e hora

Checklist de integração

Exemplo de integração (pseudocódigo)

Próximos passos