Fluxo Completo de Monitoramento de Transações

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:

Campo	Tipo	Obrigatório	Descrição
externalId	string	Sim	Seu identificador único para esta transação
type	enum	Sim	Tipo de transação: PAYMENT, TRANSFER, WITHDRAWAL, DEPOSIT, REFUND, CHARGEBACK, REVERSAL, FEE, ADJUSTMENT, OTHER
status	enum	Não	Status da transação (padrão: PENDING)
amount	number	Sim	Valor da transação na moeda original
currency	string	Sim	Código de moeda ISO 4217 (ex.: USD, EUR, GBP)
paymentMethod	enum	Não	Método de pagamento utilizado
originEntityId	uuid	Não	ID da entidade remetente (se a entidade existir no sistema)
originExternalId	string	Não	Identificador externo do remetente
originName	string	Não	Nome do remetente
originCountry	string	Não	País do remetente (ISO 3166-1 alpha-2)
destinationEntityId	uuid	Não	ID da entidade destinatária (se a entidade existir no sistema)
destinationExternalId	string	Não	Identificador externo do destinatário
destinationName	string	Não	Nome do destinatário
destinationCountry	string	Não	País do destinatário (ISO 3166-1 alpha-2)
description	string	Não	Descrição da transação
category	string	Não	Categoria da transação
transactedAt	datetime	Não	Quando a transação ocorreu (padrão: agora)
executeRules	boolean	Não	Executar regras automaticamente (padrão: true)
metadata	object	Não	Metadados personalizados adicionais

O que acontece automaticamente:

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)
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
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"
  },
  "rulesExecutionSummary": {
    "rulesHit": [
      {
        "name": "Large Transaction Amount",
        "description": "Flags transfers above threshold",
        "score": 30,
        "priority": 10,
        "category": "transaction-monitoring",
        "status": "active",
        "conditions": [{ "field": "amount", "operator": "gte", "value": "50000" }],
        "actions": [{ "type": "add_risk_score", "value": 30 }]
      },
      {
        "name": "High-Risk Jurisdiction Transfer",
        "description": "Cross-border high-risk corridor",
        "score": 38,
        "priority": 20,
        "category": "transaction-monitoring",
        "status": "active",
        "conditions": [],
        "actions": [
          { "type": "add_risk_score", "value": 38 },
          { "type": "create_alert", "result": { "alertId": "alert-uuid" } }
        ]
      }
    ],
    "rulesNoHit": [],
    "actionsExecuted": {
      "alerts": [{ "ruleId": "rule-uuid-2", "severity": "critical" }]
    },
    "totalScore": 68,
    "matchedRulesCount": 2,
    "executionTimeMs": 850,
    "trigger": "created",
    "riskMatrixName": "Default Transaction Matrix"
  }
}

Passo 2: Conversão de Moeda

Como Funciona a Conversão de Moeda

Conversão Automática: Se currency !== 'USD', o sistema converte automaticamente para USD
Provedor: Usa o serviço ms-providers (configurado via MS_PROVIDERS_URL)
Cache: Taxas de câmbio armazenadas em cache por 1 minuto (TTL)
Resiliência: Padrão circuit breaker com fallback para cache desatualizado
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:

Carregamento de Contexto:
- Carrega dados da transação
- Carrega entidades vinculadas (origem/destino) com dados de enriquecimento
- Prepara contexto de execução
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'
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
Atualização de Pontuação:
- Atualiza riskScore da transação
- Define flagged: true se pontuação > 50
- Armazena array riskFactors com razões
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:

Criação de Alertas: Regras com ação create_alert criam alertas individuais
Atraso de 5 Segundos: O sistema aguarda para coletar todos os alertas relacionados
Consolidação: Alertas relacionados consolidados em uma única investigação
Criação de Investigação: Investigação criada com:
- Prioridade baseada na severidade mais alta do alerta
- Status: “open”
- Todos os alertas relacionados vinculados
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

Sempre Habilite Regras Automáticas: Configure executeRules: true (padrão) para detectar transações suspeitas imediatamente.
Use a API em Lote para Volume: Para importações em massa ou cenários de alto volume, use /transactions/batch para melhor desempenho.
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
Mapeamento de ID Externo: Sempre defina um externalId único para correlação com seus sistemas.
Tratamento de Moeda: O sistema lida com conversão de moeda automaticamente. Certifique-se de que MS_PROVIDERS_URL está configurado corretamente.
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
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
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

{
  "rulesExecutionSummary": null,
  "warnings": [
    "Rules engine timeout after 30000ms"
  ]
}

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.

​Visão Geral

​Diagrama do Fluxo

​Passo 1: Criar Transação

​Passo 2: Conversão de Moeda

​Como Funciona a Conversão de Moeda

​Tratamento de Falha na Conversão

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

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

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

​Estrutura do Contexto da Transação

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

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

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

​Listar Transações com Filtros

​Obter Detalhes da Transação

​Visualizar Alertas da Transação

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

​Melhores Práticas

​Padrões Avançados

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

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

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

​Tratamento de Erros

​Falhas na Conversão de Moeda

​Falhas na Execução de Regras

​Falhas Parciais em Lote

​Próximos Passos