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: você adiciona um salto de rede. O contrato é simples: idempotente por requestId, sem callbacks, resposta determinística de três estados. 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

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. O Ledger HTTP v1 nunca o invoca. A API HTTP pública do Tracer é apenas v1 e não tem operações de reserva. O Ledger chama o serviço gRPC lerian.midaz.reservation.v1.ReservationService. Esse serviço é um transporte interno de serviço para serviço, não uma API pública. O Tracer sempre inicia esse listener gRPC, na porta 4021 por padrão. Para usar outra porta, defina TRACER_GRPC_PORT com um endereço de escuta no formato :4021. No Ledger, defina TRACER_BASE_URL com o endereço do listener no formato host:port. Quando TRACER_BASE_URL não está definida, o Ledger não faz nenhuma chamada de reserva. O Ledger chama o Tracer apenas quando o tracer.mode por ledger é advisory ou enforce. Um modo não definido ou off ignora as reservas mesmo quando você define TRACER_BASE_URL. Um skip por chamada respeitado também contorna o seam. O seam tem cinco transições:

Transição	Ação do Ledger
`Reserve`	Retém capacidade de limite antes que a transação seja commitada.
`ConfirmByTransaction`	Commita todas as retenções de uma transação.
`ReleaseByTransaction`	Retorna todas as retenções de uma transação.
`ConfirmById`	Commita uma retenção.
`ReleaseById`	Retorna uma retenção.

Ordem de deploy

Faça o deploy do Tracer antes do deploy do Ledger do mesmo release do Midaz. Um Tracer anterior ao v4.3.0 aceita apenas os esquemas CARD, WIRE, PIX e CRYPTO. Ele recusa uma reserva com qualquer outro esquema. No modo enforce, o Ledger então rejeita a transação com 0532. Um Tracer anterior ao v4.3.0 também não consegue ler uma validação armazenada com qualquer outro esquema. Isso inclui um pod que o rollout ainda não alcançou. Depois que o Tracer armazenar uma validação assim, não volte o Tracer para uma versão anterior ao v4.3.0. Enquanto um Ledger do v4.2.0 ou posterior estiver em execução, não volte o Tracer para uma versão anterior ao v4.2.0. Um Tracer anterior descarta o tipo de conta, os metadados e o indicador de estorno de cada requisição de reserva.

Regras em uma reserva

Em cada Reserve, o Tracer avalia primeiro as suas regras ativas, com o mesmo avaliador de POST /v1/validations. Depois, ele reserva capacidade de limite. Em uma reserva, o padrão sem correspondência não se aplica. Quando nenhuma regra corresponde, a reserva segue para a verificação de limites. Uma reserva de estorno ignora as regras e ainda reserva capacidade de limite. A requisição de reserva leva o valor, o ativo, o esquema de pagamento da transação, o timestamp da transação e os valores escalares de metadados, como strings. Ela também leva o ID e o tipo da primeira conta de origem e os IDs do segmento e do portfólio dessa conta. Ela não leva merchant nem o nome do segmento ou do portfólio. Uma reserva de estorno leva o esquema da transação original. Limites e regras com escopo por segmento, portfólio ou esquema se aplicam à reserva. Uma reserva sem esquema corresponde apenas a escopos que não indicam esquema.

Resultados no Ledger

Uma negação de reserva é uma resposta bem-sucedida, não um erro de transporte. O modo advisory nunca bloqueia a transação. O modo enforce rejeita a transação antes de qualquer movimentação de saldo:

Resultado do Tracer	Erro do Ledger no modo `enforce`
Um limite de gastos é excedido	`0177`
Uma regra correspondente retorna DENY	`0535`
Uma regra correspondente retorna REVIEW, ou uma regra não pode ser avaliada	`0531`
O Tracer recusa a requisição de reserva	`0532`, para cada `failPosture`
O Tracer está indisponível	`0178` quando `failPosture` é `closed`. Com `open`, a transação segue sem uma reserva.

Com a postura aberta, o Ledger também prossegue sem verificações de regras ou de limites quando o Tracer recusa as credenciais do Ledger. O Ledger também pode retornar 0536 para uma reserva. A lista de erros do Midaz descreve cada código. Falhas de confirmação e liberação não bloqueiam a transação.

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
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 (esquema de pagamento, 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. 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.

Validação apenas por regras

POST /v1/validations/rules-only recebe a mesma requisição de POST /v1/validations e retorna a mesma resposta e os mesmos erros. O Tracer decide apenas pelas suas regras e não verifica nem conta nenhum limite de gastos. Use essa rota para avaliar um crédito recebido sem consumir um limite. As duas rotas compartilham um único espaço de requestId. Um requestId já usado em qualquer uma das rotas retorna a decisão registrada para ele, então nunca reutilize um requestId entre as duas rotas. O Tracer armazena uma validação apenas por regras como qualquer outra. Ela aparece em GET /v1/validations e nos números do dashboard. Apenas o snapshot da requisição no seu evento de auditoria a identifica, com rulesOnly: true.

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 autenticação por chave de API, e não a autenticação via plugin, em `POST /v1/validations` e `POST /v1/validations/rules-only` (padrão: `false`)

Autenticação via plugin (Access Manager)

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 POST /v1/validations e POST /v1/validations/rules-only para autenticação apenas por chave de API via API_KEY_ENABLED_ONLY_VALIDATION=true. Essas rotas então conferem a chave de API apenas quando API_KEY_ENABLED=true. Isso é útil em cenários de alta taxa de transferência em que a autenticação via plugin adiciona latência inaceitável.

Autenticação na Lerian Cloud

Na Lerian Cloud, a autenticação funciona assim:

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.

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 serviço estiver temporariamente no limite de capacidade para o seu tenant, as requisições retornam HTTP 503 com o código de erro 0466 e um header Retry-After. Aplique backoff e tente novamente.

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 também registra validações 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(),
        "scheme": transaction.scheme,
        "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

Ordem de deploy

Regras em uma reserva

Resultados no 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

Validação apenas por regras

Autenticação

Autenticação por chave de API

Autenticação via plugin (Access Manager)

Prioridade de autenticação

Autenticação na Lerian Cloud

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

​Ordem de deploy

​Regras em uma reserva

​Resultados no 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

​Validação apenas por regras

​Autenticação

​Autenticação por chave de API

​Autenticação via plugin (Access Manager)

​Prioridade de autenticação

​Autenticação na Lerian Cloud

​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

Ordem de deploy

Regras em uma reserva

Resultados no 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

Validação apenas por regras

Autenticação

Autenticação por chave de API

Autenticação via plugin (Access Manager)

Prioridade de autenticação

Autenticação na Lerian Cloud

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