> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Guia de integração > Como integrar seu sistema de autorização com o Tracer para validação de transações em tempo real. export const GMetadata = ({children}) => {children} ; 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 para 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 para o [Guia do motor de regras](./rule-engine.mdx); compliance pode ler o [Guia de auditoria e conformidade](./audit-compliance.mdx). 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. O Tracer fica **fora** do seu ledger: nunca conecta no Midaz. A sua aplicação orquestra os dois — ela chama o Tracer para validar, e só submete a transação ao Midaz se a decisão for `ALLOW`. O Tracer avalia as suas **políticas e limites** configurados contra o contexto que você envia, não os saldos das contas — o ledger continua sendo a fonte de verdade do que uma conta possui. ## 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: Integração de requisição-resposta em que um sistema de autorização chama o Tracer para obter uma decisão de validação e só envia a transação ao Midaz quando a decisão é ALLOW **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: 1. **Enriquecer o payload** com dados de conta, segmento, portfólio e comerciante antes de chamar o Tracer 2. **Fornecer contexto preciso** para avaliação de regras e limites—o Tracer não consegue buscar dados faltantes 3. **Tratar a decisão** (ALLOW, DENY ou REVIEW) adequadamente no seu fluxo de trabalho 4. **Implementar lógica de retry** se o Tracer estiver temporariamente indisponível 5. **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: 1. **Avaliar regras** contra o contexto fornecido 2. **Verificar limites** contra o uso atual 3. **Registrar trilha de auditoria** para conformidade 4. **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: Etapas para preparar o contexto da transação e chamar o Tracer, desde reunir os dados dos seus sistemas até agir conforme a decisão retornada ### 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](/pt/reference/tracer/validate-transaction). ### 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](/pt/platform/access-manager/auth-plugin). 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: 1. Se `PLUGIN_AUTH_ENABLED=true` e o endpoint não está marcado para API-key-only → Autenticação por plugin 2. 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 o código de erro `0458`. ### 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 o código de erro `0457` se `PLUGIN_AUTH_ENABLED=false`. * **Toda requisição `/v1/*` deve carregar um JWT bearer token** emitido pelo [Access Manager](/pt/platform/access-manager/access-manager): `Authorization: Bearer `. * **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 serviço da plataforma de multi-tenancy 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 o código de erro `0466` 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](/pt/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 o código de erro `0421` (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 para o momento real da transação, não para o 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) para 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: * [ ] API Key está configurada e segura * [ ] Cada requisição inclui um requestId único (UUID) * [ ] Cliente trata respostas 201 e 200 como sucesso * [ ] 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) *** ```python theme={null} 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](./rule-engine.mdx)** - Crie regras que avaliam contra o contexto que você fornece * **[Limites de gastos](./spending-limits.mdx)** - Configure limites que se aplicam aos escopos das suas transações * **[Auditoria e conformidade](./audit-compliance.mdx)** - Consulte o histórico de validações e a trilha de auditoria