> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Fluxo Completo de Monitoramento de Transações

> Guia completo para criar, analisar e monitorar transações com pontuação de risco automática — no produto de monitoramento de transações gu1 para fraude e AML.

## 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

```mermaid theme={null}
graph TD
    A[Criar Transação] --> B[POST /transactions]
    B --> C{Conversão de Moeda Necessária?}

    C -->|Sim| D[Converter para USD]
    C -->|Não| E[Transação Criada]

    D --> F{Conversão Bem-sucedida?}
    F -->|Sim| G[Armazenar Valor em USD]
    F -->|Não| H[Armazenar Sem USD]

    G --> E
    H --> E

    E --> I{executeRules = true?}
    I -->|Sim| J[Análise Automática de Risco]
    I -->|Não| K[Retornar Transação]

    J --> L[Carregar Contexto da Transação]
    L --> M[Selecionar Regras de Transação]
    M --> N[Executar Motor de Regras]

    N --> O[Calcular Pontuação de Risco]
    O --> P{Pontuação > Limite?}

    P -->|Sim| Q[Sinalizar Transação]
    P -->|Não| R[Aprovar Transação]

    Q --> S[Criar Alertas]
    R --> T[Atualizar Pontuação de Risco]

    S --> U[Consolidar Alertas]
    T --> V[Retornar Resultado]

    U --> W[Criar Investigação]
    W --> X[Enviar Notificações]
    X --> V
```

## 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**:

```json theme={null}
{
  "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**:

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)**:

```json theme={null}
{
  "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

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**:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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**

```json theme={null}
{
  "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**

```json theme={null}
{
  "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**

```json theme={null}
{
  "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**

```json theme={null}
{
  "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:

```json theme={null}
{
  "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**:

```json theme={null}
{
  "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**:

```json theme={null}
{
  "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**:

```json theme={null}
{
  "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**:

```json theme={null}
{
  "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**:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

* [Configurar Regras de Transação](/pt/use-cases/transaction-monitoring/rules-configuration)
* [Configurar Regras de Velocidade](/pt/use-cases/transaction-monitoring/fraud-detection)
* [Fluxo de Trabalho de Investigação de Alertas](/pt/workflows/overview)
* [Painel de Análise de Transações](/pt/use-cases/transaction-monitoring/overview)