Skip to main content

​
Visão Geral

Este guia cobre o fluxo completo para monitoramento de transações, desde a criação até a análise automática de risco e geração de alertas. As transações são avaliadas contra regras específicas de transação para detectar padrões suspeitos, valores incomuns, jurisdições de alto risco e outros sinais de alerta.

​
Diagrama do Fluxo

​
Passo 1: Criar Transação

As transações são criadas via API de transações com conversão automática de moeda e execução opcional de regras. Endpoint: POST /transactions Requisição: 
{
  "externalId": "TXN-2024-00001",
  "type": "TRANSFER",
  "status": "PENDING",
  "amount": 50000,
  "currency": "EUR",
  "paymentMethod": "bank_transfer",
  "originEntityId": "sender-entity-uuid",
  "originName": "John Doe",
  "originCountry": "FR",
  "destinationEntityId": "receiver-entity-uuid",
  "destinationName": "Acme Corporation",
  "destinationCountry": "US",
  "description": "Business payment for services",
  "category": "B2B",
  "transactedAt": "2025-12-24T10:30:00Z",
  "executeRules": true,
  "metadata": {
    "ip": "192.168.1.1",
    "userAgent": "Mozilla/5.0...",
    "sessionId": "sess_abc123"
  }
}
Descrição dos Campos:
CampoTipoObrigatórioDescrição
externalIdstringSimSeu identificador único para esta transação
typeenumSimTipo de transação: PAYMENT, TRANSFER, WITHDRAWAL, DEPOSIT, REFUND, CHARGEBACK, REVERSAL, FEE, ADJUSTMENT, OTHER
statusenumNãoStatus da transação (padrão: PENDING)
amountnumberSimValor da transação na moeda original
currencystringSimCódigo de moeda ISO 4217 (ex.: USD, EUR, GBP)
paymentMethodenumNãoMétodo de pagamento utilizado
originEntityIduuidNãoID da entidade remetente (se a entidade existir no sistema)
originExternalIdstringNãoIdentificador externo do remetente
originNamestringNãoNome do remetente
originCountrystringNãoPaís do remetente (ISO 3166-1 alpha-2)
destinationEntityIduuidNãoID da entidade destinatária (se a entidade existir no sistema)
destinationExternalIdstringNãoIdentificador externo do destinatário
destinationNamestringNãoNome do destinatário
destinationCountrystringNãoPaís do destinatário (ISO 3166-1 alpha-2)
descriptionstringNãoDescrição da transação
categorystringNãoCategoria da transação
transactedAtdatetimeNãoQuando a transação ocorreu (padrão: agora)
executeRulesbooleanNãoExecutar regras automaticamente (padrão: true)
metadataobjectNãoMetadados personalizados adicionais
O que acontece automaticamente:
  1. Conversão de Moeda:
    • Se a moeda não for USD, converte o valor para USD usando taxas de câmbio em tempo real
    • Armazena: amountInUsd, exchangeRate, rateSource, rateTimestamp
    • Em caso de falha na conversão, a transação ainda é criada (sem o valor em USD)
  2. Criação da Transação:
    • Registro da transação criado no banco de dados
    • ID único gerado
    • Vincula às entidades de origem/destino se fornecidas
  3. Análise Automática de Risco (se executeRules: true):
    • Executa regras específicas de transação
    • Calcula pontuação de risco
    • Cria alertas para regras correspondentes
    • Atualiza status da transação se necessário
Resposta (com análise de risco): 
{
  "transaction": {
    "id": "txn-uuid",
    "organizationId": "org-uuid",
    "externalId": "TXN-2024-00001",
    "type": "TRANSFER",
    "status": "PENDING",
    "amount": "50000.00",
    "currency": "EUR",
    "amountInUsd": "54500.00",
    "exchangeRate": "1.09",
    "rateSource": "fixer.io",
    "rateTimestamp": "2025-12-24T10:30:00Z",
    "convertedAt": "2025-12-24T10:30:01Z",
    "originEntityId": "sender-entity-uuid",
    "originName": "John Doe",
    "originCountry": "FR",
    "destinationEntityId": "receiver-entity-uuid",
    "destinationName": "Acme Corporation",
    "destinationCountry": "US",
    "riskScore": "68.00",
    "flagged": true,
    "riskFactors": [
      "Large transaction amount detected",
      "Cross-border transaction to high-risk jurisdiction"
    ],
    "transactedAt": "2025-12-24T10:30:00Z",
    "createdAt": "2025-12-24T10:30:02Z"
  },
  "rulesResult": {
    "success": true,
    "executed": true,
    "result": {
      "entityId": "txn-uuid",
      "entityType": "transaction",
      "riskScore": 68,
      "overallConfidence": 0.95,
      "totalRules": 8,
      "successfulRules": 3,
      "rulesExecuted": [
        {
          "ruleId": "rule-uuid-1",
          "ruleName": "Large Transaction Amount",
          "executed": true,
          "conditionsMet": true,
          "confidence": 0.98,
          "actionsExecuted": [
            {
              "type": "add_risk_score",
              "value": 30
            }
          ]
        },
        {
          "ruleId": "rule-uuid-2",
          "ruleName": "High-Risk Jurisdiction Transfer",
          "executed": true,
          "conditionsMet": true,
          "confidence": 0.92,
          "actionsExecuted": [
            {
              "type": "add_risk_score",
              "value": 38
            },
            {
              "type": "create_alert",
              "result": {
                "alertId": "alert-uuid"
              }
            }
          ]
        }
      ],
      "flags": [
        {
          "type": "LARGE_AMOUNT",
          "severity": "warning",
          "reason": "Transaction amount exceeds $50,000 threshold",
          "confidence": 0.98
        },
        {
          "type": "HIGH_RISK_JURISDICTION",
          "severity": "critical",
          "reason": "Transfer to high-risk jurisdiction",
          "confidence": 0.92
        }
      ]
    },
    "rulesTriggered": 3,
    "executionTimeMs": 850
  }
}

​
Passo 2: Conversão de Moeda

​
Como Funciona a Conversão de Moeda

  1. Conversão Automática: Se currency !== 'USD', o sistema converte automaticamente para USD
  2. Provedor: Usa o serviço ms-providers (configurado via MS_PROVIDERS_URL)
  3. Cache: Taxas de câmbio armazenadas em cache por 1 minuto (TTL)
  4. Resiliência: Padrão circuit breaker com fallback para cache desatualizado
  5. Degradação Elegante: Se a conversão falhar, a transação ainda é criada (sem valor em USD)
Metadados da Conversão: 
{
  "amountInUsd": "54500.00",
  "exchangeRate": "1.09",
  "rateSource": "fixer.io",
  "rateTimestamp": "2025-12-24T10:30:00Z",
  "convertedAt": "2025-12-24T10:30:01Z"
}
Transações em USD:
  • Se currency: 'USD', nenhuma conversão é necessária
  • amountInUsd = amount
  • exchangeRate = 1
  • rateSource = 'no-conversion'

​
Tratamento de Falha na Conversão

Se o serviço de moedas estiver indisponível: 
{
  "transaction": {
    "amount": "50000.00",
    "currency": "EUR",
    "amountInUsd": null,
    "exchangeRate": null,
    "rateSource": null
  }
}
A transação é criada com sucesso, mas o valor em USD não está disponível. Regras que dependem de valores em USD usarão o valor original.

​
Passo 3: Análise de Risco da Transação

​
Como Funciona a Análise de Risco da Transação

O RulesExecutionService avalia transações usando regras específicas de transação:
  1. Carregamento de Contexto:
    • Carrega dados da transação
    • Carrega entidades vinculadas (origem/destino) com dados de enriquecimento
    • Prepara contexto de execução
  2. Seleção de Regras:
    • Filtra regras por targetEntityTypes: ['transaction']
    • Filtra por gatilho: 'created' (para automático) ou 'manual_evaluation'
    • Filtra por status: enabled: true e status: 'active'
  3. Execução de Regras:
    • Avalia condições das regras contra o contexto da transação
    • Executa ações para regras correspondentes (adicionar pontuação, criar alertas, atualizar status)
    • Acumula pontuação de risco
  4. Atualização de Pontuação:
    • Atualiza riskScore da transação
    • Define flagged: true se pontuação > 50
    • Armazena array riskFactors com razões
  5. Criação de Alertas:
    • Regras com ação create_alert geram alertas
    • Alertas vinculados à transação
    • Alertas consolidados em investigações após atraso de 5 segundos

​
Exemplos de Regras Específicas de Transação

Regra 1: Valor de Transação Grande 
{
  "name": "Large Transaction Amount",
  "targetEntityTypes": ["transaction"],
  "triggers": ["created"],
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "amountInUsd",
        "operator": "greater_than",
        "value": 50000
      }
    ]
  },
  "actions": [
    {
      "type": "add_risk_score",
      "value": 30
    }
  ]
}
Regra 2: Transferência para Jurisdição de Alto Risco 
{
  "name": "High-Risk Jurisdiction Transfer",
  "targetEntityTypes": ["transaction"],
  "triggers": ["created"],
  "conditions": {
    "operator": "OR",
    "conditions": [
      {
        "field": "originCountry",
        "operator": "in_list",
        "value": ["AF", "IR", "KP", "SY"]
      },
      {
        "field": "destinationCountry",
        "operator": "in_list",
        "value": ["AF", "IR", "KP", "SY"]
      }
    ]
  },
  "actions": [
    {
      "type": "add_risk_score",
      "value": 50
    },
    {
      "type": "create_alert",
      "severity": "critical",
      "description": "Transaction involves high-risk jurisdiction"
    }
  ]
}
Regra 3: Velocidade Rápida de Transações 
{
  "name": "Rapid Transaction Velocity",
  "targetEntityTypes": ["transaction"],
  "triggers": ["created"],
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "originEntityId",
        "operator": "historical_count",
        "timeWindow": "1h",
        "comparison": "greater_than",
        "value": 10
      }
    ]
  },
  "actions": [
    {
      "type": "add_risk_score",
      "value": 40
    },
    {
      "type": "create_alert",
      "severity": "warning",
      "description": "Unusual transaction velocity detected"
    }
  ]
}
Regra 4: Transação com Entidade Sancionada 
{
  "name": "Sanctioned Entity Transaction",
  "targetEntityTypes": ["transaction"],
  "triggers": ["created"],
  "conditions": {
    "operator": "OR",
    "conditions": [
      {
        "field": "originEntity.enrichment.sanctionsMatch",
        "operator": "equals",
        "value": true
      },
      {
        "field": "destinationEntity.enrichment.sanctionsMatch",
        "operator": "equals",
        "value": true
      }
    ]
  },
  "actions": [
    {
      "type": "add_risk_score",
      "value": 100
    },
    {
      "type": "update_status",
      "status": "blocked"
    },
    {
      "type": "create_alert",
      "severity": "critical",
      "description": "Transaction involves sanctioned entity"
    }
  ]
}

​
Estrutura do Contexto da Transação

O motor de regras recebe este contexto: 
{
  "transaction": {
    "id": "txn-uuid",
    "type": "TRANSFER",
    "amount": 50000,
    "currency": "EUR",
    "amountInUsd": 54500,
    "originEntityId": "sender-uuid",
    "originName": "John Doe",
    "originCountry": "FR",
    "destinationEntityId": "receiver-uuid",
    "destinationName": "Acme Corp",
    "destinationCountry": "US",
    "transactedAt": "2025-12-24T10:30:00Z"
  },
  "originEntity": {
    "id": "sender-uuid",
    "type": "person",
    "name": "John Doe",
    "enrichmentData": {
      "isPep": false,
      "sanctionsMatch": false,
      "riskScore": 25
    }
  },
  "destinationEntity": {
    "id": "receiver-uuid",
    "type": "company",
    "name": "Acme Corp",
    "enrichmentData": {
      "sanctionsMatch": false,
      "riskScore": 42
    }
  }
}

​
Passo 4: Criação em Lote de Transações

Para cenários de alto volume, use o endpoint em lote para criar múltiplas transações de forma eficiente. Endpoint: POST /transactions/batch Requisição: 
{
  "transactions": [
    {
      "externalId": "TXN-001",
      "type": "PAYMENT",
      "amount": 1000,
      "currency": "USD",
      "originName": "Customer A",
      "destinationName": "Merchant X"
    },
    {
      "externalId": "TXN-002",
      "type": "PAYMENT",
      "amount": 2500,
      "currency": "EUR",
      "originName": "Customer B",
      "destinationName": "Merchant X"
    }
  ],
  "executeRules": true,
  "skipDuplicates": true
}
Funcionalidades:
  • Inserção em massa para melhor desempenho
  • Conversão de moeda otimizada (armazena em cache taxas para a mesma moeda)
  • Detecção automática de duplicatas (por externalId)
  • Execução opcional de regras em todas as transações
  • Máximo de 1000 transações por lote
  • Tempo limite de 2 minutos
Resposta: 
{
  "summary": {
    "total": 2,
    "created": 2,
    "duplicates": 0,
    "failed": 0,
    "flagged": 0,
    "totalCost": 150
  },
  "transactions": [
    {
      "id": "txn-uuid-1",
      "externalId": "TXN-001",
      "riskScore": "15.00",
      "flagged": false
    },
    {
      "id": "txn-uuid-2",
      "externalId": "TXN-002",
      "riskScore": "22.00",
      "flagged": false
    }
  ],
  "executionTimeMs": 3200
}

​
Passo 5: Análise Manual de Transação

Se você criou uma transação com executeRules: false, pode acionar manualmente a análise de risco posteriormente. Endpoint: POST /entities/:transactionId/analyze Requisição: 
{
  "entityType": "transaction",
  "enrichIfNeeded": false
}
Casos de Uso:
  • Reanalisar transação após enriquecimento de entidade
  • Analisar transação após atualizações de regras
  • Repontuação periódica de transações pendentes
Resposta: Mesma estrutura do resultado de análise de risco automática

​
Passo 6: Consultas e Monitoramento de Transações

​
Listar Transações com Filtros

Endpoint: GET /transactions Parâmetros de Consulta: 
GET /transactions?flagged=true&minAmount=10000&sortBy=risk_score&sortOrder=desc&limit=50
Filtros Disponíveis:
  • flagged: Filtrar por status sinalizado (true, false, all)
  • minAmount / maxAmount: Filtro de faixa de valor (na moeda original)
  • currency: Filtrar por moeda
  • type: Filtrar por tipo de transação
  • status: Filtrar por status da transação
  • entityId: Filtrar por entidade de origem ou destino
  • startDate / endDate: Filtro de faixa de datas
  • search: Busca de texto livre (externalId, description, names)
  • sortBy: Campo de ordenação (transacted_at, amount, risk_score, created_at)
  • sortOrder: Direção da ordenação (asc, desc)
Resposta: 
{
  "transactions": [
    {
      "id": "txn-uuid",
      "externalId": "TXN-2024-00001",
      "type": "TRANSFER",
      "amount": "50000.00",
      "currency": "EUR",
      "amountInUsd": "54500.00",
      "riskScore": "68.00",
      "flagged": true,
      "originName": "John Doe",
      "destinationName": "Acme Corp",
      "transactedAt": "2025-12-24T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 50,
    "offset": 0
  }
}

​
Obter Detalhes da Transação

Endpoint: GET /transactions/:transactionId Resposta: Objeto completo da transação com detalhes de análise de risco

​
Visualizar Alertas da Transação

Endpoint: GET /alerts?transactionId=:transactionId Resposta: Todos os alertas gerados para a transação

​
Passo 7: Consolidação de Alertas e Investigações

Após a análise de risco, os alertas são automaticamente consolidados em investigações:
  1. Criação de Alertas: Regras com ação create_alert criam alertas individuais
  2. Atraso de 5 Segundos: O sistema aguarda para coletar todos os alertas relacionados
  3. Consolidação: Alertas relacionados consolidados em uma única investigação
  4. Criação de Investigação: Investigação criada com:
    • Prioridade baseada na severidade mais alta do alerta
    • Status: “open”
    • Todos os alertas relacionados vinculados
  5. Notificações: Analistas notificados da nova investigação
Estrutura da Investigação: 
{
  "id": "investigation-uuid",
  "organizationId": "org-uuid",
  "title": "High-Risk Transaction: TXN-2024-00001",
  "priority": "critical",
  "status": "open",
  "relatedTransactions": ["txn-uuid"],
  "relatedEntities": ["sender-uuid", "receiver-uuid"],
  "alerts": [
    {
      "id": "alert-uuid-1",
      "severity": "critical",
      "type": "HIGH_RISK_JURISDICTION",
      "description": "Transaction involves high-risk jurisdiction"
    },
    {
      "id": "alert-uuid-2",
      "severity": "warning",
      "type": "LARGE_AMOUNT",
      "description": "Transaction amount exceeds threshold"
    }
  ],
  "createdAt": "2025-12-24T10:30:07Z"
}

​
Melhores Práticas

  1. Sempre Habilite Regras Automáticas: Configure executeRules: true (padrão) para detectar transações suspeitas imediatamente.
  2. Use a API em Lote para Volume: Para importações em massa ou cenários de alto volume, use /transactions/batch para melhor desempenho.
  3. Vincule Entidades: Sempre forneça originEntityId e destinationEntityId quando disponível. Isso permite:
    • Dados de enriquecimento de entidade na avaliação de regras
    • Melhor agregação de risco
    • Padrões de transação em nível de entidade
  4. Mapeamento de ID Externo: Sempre defina um externalId único para correlação com seus sistemas.
  5. Tratamento de Moeda: O sistema lida com conversão de moeda automaticamente. Certifique-se de que MS_PROVIDERS_URL está configurado corretamente.
  6. Configuração de Regras: Configure regras de transação para seu apetite de risco:
    • Limites de valores apropriados para seu negócio
    • Jurisdições de alto risco baseadas em seus requisitos de conformidade
    • Regras de velocidade baseadas em padrões normais de transação
  7. Gerenciamento de Status: Use o campo status da transação para rastrear o ciclo de vida:
    • PENDING → APPROVED/REJECTED/CANCELLED
    • Atualize o status com base em revisão manual ou validação externa
  8. Monitoramento: Configure painéis para monitorar:
    • Taxa de transações sinalizadas
    • Pontuações de risco médias
    • Volume de alertas por tipo
    • Tempo de resolução de investigações

​
Padrões Avançados

​
Padrão 1: Risco da Entidade Afeta Risco da Transação

Configure regras que consideram o risco da entidade: 
{
  "name": "High-Risk Entity Transaction",
  "conditions": {
    "operator": "OR",
    "conditions": [
      {
        "field": "originEntity.riskScore",
        "operator": "greater_than",
        "value": 70
      },
      {
        "field": "destinationEntity.riskScore",
        "operator": "greater_than",
        "value": 70
      }
    ]
  },
  "actions": [
    {
      "type": "add_risk_score",
      "value": 35
    }
  ]
}

​
Padrão 2: Detecção de Velocidade e Padrões

Use consultas históricas em regras: 
{
  "name": "Unusual Transaction Pattern",
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "originEntityId",
        "operator": "historical_sum",
        "aggregateField": "amountInUsd",
        "timeWindow": "24h",
        "comparison": "greater_than",
        "value": 100000
      }
    ]
  }
}

​
Padrão 3: Triagem de Sanções na Transação

{
  "name": "Transaction Sanctions Check",
  "conditions": {
    "operator": "OR",
    "conditions": [
      {
        "field": "originEntity.enrichment.sanctionsMatch",
        "operator": "equals",
        "value": true
      },
      {
        "field": "destinationEntity.enrichment.sanctionsMatch",
        "operator": "equals",
        "value": true
      }
    ]
  },
  "actions": [
    {
      "type": "update_status",
      "status": "blocked"
    },
    {
      "type": "add_risk_score",
      "value": 100
    }
  ]
}

​
Tratamento de Erros

​
Falhas na Conversão de Moeda

{
  "transaction": {
    "amountInUsd": null,
    "exchangeRate": null
  },
  "warnings": [
    "Currency conversion failed: fixer.io service unavailable"
  ]
}
Transação criada com sucesso, regras usam o valor original.

​
Falhas na Execução de Regras

{
  "rulesResult": {
    "success": false,
    "error": "Rules engine timeout after 30000ms",
    "executed": false
  }
}
Transação criada, mas risco não calculado. Acione a análise manualmente posteriormente.

​
Falhas Parciais em Lote

{
  "summary": {
    "total": 100,
    "created": 95,
    "failed": 5
  },
  "failures": [
    {
      "externalId": "TXN-042",
      "error": "Validation failed: invalid currency code"
    }
  ]
}
Transações bem-sucedidas criadas, falhas relatadas separadamente.

​
Próximos Passos