Configuração de Regras

Introdução

O motor de regras do gu1 permite criar lógica personalizada para analisar transações em tempo real. As regras podem ser síncronas (afetam a decisão da transação) ou assíncronas (apenas monitoramento).

Regras Síncronas vs Assíncronas

Regras Síncronas (SYNC)

Executam durante a chamada da API e afetam a decisão da transação Quando usar:

Bloquear transações fraudulentas
Impor limites de transação
Exigir autenticação adicional
Requisitos regulatórios

Características:

Avaliadas antes da resposta
Podem mudar o estado da transação
Meta de desempenho: < 100ms
Limitadas a operações leves

Exemplo:

Limite diário excedido → REJEITAR transação

Regras Assíncronas (ASYNC)

Executam em paralelo sem afetar a transação Quando usar:

Monitoramento de padrões
Análise comportamental
Agregações complexas
Análise histórica

Características:

Não bloqueiam a resposta da API
Podem realizar consultas pesadas
Geram apenas alertas
Alimentam o Dashboard de Inteligência

Exemplo:

Usuário tem 15 transações hoje → Gerar alerta MÉDIO

Estrutura da Regra

{
  "name": "Nome da Regra",
  "category": "fraud|aml|compliance|risk",
  "priority": 100,
  "enabled": true,
  "evaluationMode": "sync|async",
  "targetEntityTypes": ["transaction"],
  "conditions": {
    "operator": "AND|OR",
    "conditions": [...]
  },
  "actions": [...]
}

Campos de Configuração

Campos Básicos

Campo	Tipo	Descrição
`name`	string	Nome da regra (único)
`category`	string	Categoria: fraud, aml, compliance, risk
`priority`	number	Prioridade de execução (1-1000, maior = primeiro)
`enabled`	boolean	Habilitar/desabilitar regra
`evaluationMode`	string	”sync” ou “async”
`targetEntityTypes`	array	Tipos de entidade para avaliar ([“transaction”])

Condições

As regras usam um sistema flexível de condições:

{
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "amount",
        "operator": "GREATER_THAN",
        "value": 10000
      },
      {
        "field": "currency",
        "operator": "IN",
        "value": ["USD", "EUR", "GBP"]
      }
    ]
  }
}

Operadores de Condição

Operador	Descrição	Exemplo
`EQUALS`	Igualdade exata	`"type" EQUALS "PAYMENT"`
`NOT_EQUALS`	Não igual	`"status" NOT_EQUALS "blocked"`
`GREATER_THAN`	Maior que	`"amount" > 1000`
`GREATER_THAN_OR_EQUAL`	Maior ou igual	`"amount" >= 1000`
`LESS_THAN`	Menor que	`"amount" < 100`
`LESS_THAN_OR_EQUAL`	Menor ou igual	`"amount" <= 100`
`IN`	Na lista	`"country" IN ["US", "CA"]`
`NOT_IN`	Não na lista	`"country" NOT_IN ["KP", "IR"]`
`CONTAINS`	String contém	`"description" CONTAINS "test"`
`NOT_CONTAINS`	String não contém	`"email" NOT_CONTAINS "@temp"`
`STARTS_WITH`	String começa com	`"accountId" STARTS_WITH "4532"`
`ENDS_WITH`	String termina com	`"domain" ENDS_WITH ".ru"`
`REGEX`	Correspondência regex	`"email" REGEX "^[a-z]+@"`
`EXISTS`	Campo existe	`"metadata.userId" EXISTS`
`NOT_EXISTS`	Campo não existe	`"referralCode" NOT_EXISTS`

Campos de Transação Disponíveis

// Campos Principais
transaction.externalId
transaction.type          // PAYMENT, TRANSFER, WITHDRAWAL, etc.
transaction.amount
transaction.currency
transaction.timestamp

// Referências de Entidades
transaction.originEntityId
transaction.destinationEntityId

// Detalhes de Pagamento
transaction.origin.paymentMethod
transaction.origin.accountType
transaction.destination.paymentMethod

// Dados do Dispositivo
transaction.originDeviceData.ipAddress
transaction.originDeviceData.platform
transaction.originDeviceData.location.country
transaction.originDeviceData.location.city

// MCC e Descrição
transaction.mccCode
transaction.description

// Tags e Metadados
transaction.tags
transaction.metadata.*     // Qualquer campo personalizado

// Campos Computados (disponíveis nas regras)
amountInUsd               // Valor convertido a USD
metadata.userTransactionCount30d
metadata.merchantChargebackRate
metadata.deviceFirstSeen
metadata.ipRiskScore

Ações

As regras podem disparar múltiplas ações:

1. Gerar Alerta

{
  "type": "generate_alert",
  "config": {
    "severity": "low|medium|high|critical",
    "type": "custom_alert_type",
    "message": "Descrição do alerta com {{variables}}"
  }
}

2. Definir Decisão (apenas SYNC)

{
  "type": "set_decision",
  "config": {
    "decision": "APPROVE|REJECT|HOLD|REVIEW_REQUIRED|ADDITIONAL_AUTH_REQUIRED",
    "reason": "Motivo da decisão"
  }
}

3. Criar Investigação

{
  "type": "create_investigation",
  "config": {
    "priority": "low|medium|high|critical",
    "assignToTeam": "team_id",
    "assignToUser": "user_id",
    "requiresSAR": true
  }
}

Exemplos de Regras

1. Limite Diário de Transação (SYNC)

{
  "name": "Limite Diário - R$ 10.000",
  "category": "compliance",
  "priority": 950,
  "enabled": true,
  "evaluationMode": "sync",
  "targetEntityTypes": ["transaction"],
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "metadata.userTransactionSum24h",
        "operator": "GREATER_THAN",
        "value": 10000
      },
      {
        "field": "amount",
        "operator": "GREATER_THAN",
        "value": 0
      }
    ]
  },
  "actions": [
    {
      "type": "generate_alert",
      "config": {
        "severity": "high",
        "type": "daily_limit_exceeded",
        "message": "Usuário {{originEntityId}} excedeu limite diário de R$ 10.000"
      }
    },
    {
      "type": "set_decision",
      "config": {
        "decision": "HOLD",
        "reason": "Limite diário de transação excedido"
      }
    }
  ]
}

2. Alerta de Velocidade de Transações (ASYNC)

{
  "name": "Alta Velocidade de Transações",
  "category": "fraud",
  "priority": 800,
  "enabled": true,
  "evaluationMode": "async",
  "targetEntityTypes": ["transaction"],
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "metadata.userTransactionCount1h",
        "operator": "GREATER_THAN",
        "value": 10
      },
      {
        "field": "metadata.userAverageTransactionsPerHour",
        "operator": "LESS_THAN",
        "value": 3
      }
    ]
  },
  "actions": [
    {
      "type": "generate_alert",
      "config": {
        "severity": "medium",
        "type": "velocity_anomaly",
        "message": "Usuário tem {{metadata.userTransactionCount1h}} transações na última hora (média: {{metadata.userAverageTransactionsPerHour}})"
      }
    }
  ]
}

3. Bloqueio de País de Alto Risco (SYNC)

{
  "name": "Bloquear Países de Alto Risco",
  "category": "fraud",
  "priority": 1000,
  "enabled": true,
  "evaluationMode": "sync",
  "targetEntityTypes": ["transaction"],
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "originDeviceData.location.country",
        "operator": "IN",
        "value": ["KP", "IR", "SY"]
      },
      {
        "field": "amount",
        "operator": "GREATER_THAN",
        "value": 100
      }
    ]
  },
  "actions": [
    {
      "type": "generate_alert",
      "config": {
        "severity": "critical",
        "type": "high_risk_country",
        "message": "Transação de país de alto risco: {{originDeviceData.location.country}}"
      }
    },
    {
      "type": "set_decision",
      "config": {
        "decision": "REJECT",
        "reason": "Transação de país sancionado"
      }
    }
  ]
}

4. Detecção de Padrão de Estruturação (ASYNC)

{
  "name": "Possível Estruturação - Limite R$ 10 mil",
  "category": "aml",
  "priority": 900,
  "enabled": true,
  "evaluationMode": "async",
  "targetEntityTypes": ["transaction"],
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "amountInUsd",
        "operator": "GREATER_THAN",
        "value": 9000
      },
      {
        "field": "amountInUsd",
        "operator": "LESS_THAN",
        "value": 10000
      },
      {
        "field": "metadata.userTransactionsSameAmountRange7d",
        "operator": "GREATER_THAN_OR_EQUAL",
        "value": 3
      }
    ]
  },
  "actions": [
    {
      "type": "generate_alert",
      "config": {
        "severity": "high",
        "type": "possible_structuring",
        "message": "Usuário tem {{metadata.userTransactionsSameAmountRange7d}} transações próximas ao limite de R$ 10 mil nos últimos 7 dias"
      }
    },
    {
      "type": "create_investigation",
      "config": {
        "priority": "high",
        "assignToTeam": "aml_compliance",
        "requiresSAR": true
      }
    }
  ]
}

5. Novo Cartão com Valor Alto (SYNC)

{
  "name": "Novo Cartão - Alerta de Valor Alto",
  "category": "fraud",
  "priority": 850,
  "enabled": true,
  "evaluationMode": "sync",
  "targetEntityTypes": ["transaction"],
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "origin.paymentMethod",
        "operator": "EQUALS",
        "value": "CARD"
      },
      {
        "field": "metadata.cardFirstSeen",
        "operator": "LESS_THAN",
        "value": "{{timestamp - 3600}}"
      },
      {
        "field": "amount",
        "operator": "GREATER_THAN",
        "value": 500
      }
    ]
  },
  "actions": [
    {
      "type": "generate_alert",
      "config": {
        "severity": "high",
        "type": "new_card_high_amount",
        "message": "Primeira transação com novo cartão por R$ {{amount}}"
      }
    },
    {
      "type": "set_decision",
      "config": {
        "decision": "ADDITIONAL_AUTH_REQUIRED",
        "reason": "Transação de alto valor com novo cartão - requer 3DS"
      }
    }
  ]
}

6. Padrão de Horário Incomum (ASYNC)

{
  "name": "Transação Fora do Horário Normal",
  "category": "fraud",
  "priority": 700,
  "enabled": true,
  "evaluationMode": "async",
  "targetEntityTypes": ["transaction"],
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "metadata.transactionHour",
        "operator": "IN",
        "value": [0, 1, 2, 3, 4, 5]
      },
      {
        "field": "metadata.userNormalHours",
        "operator": "NOT_CONTAINS",
        "value": "{{metadata.transactionHour}}"
      },
      {
        "field": "amount",
        "operator": "GREATER_THAN",
        "value": 1000
      }
    ]
  },
  "actions": [
    {
      "type": "generate_alert",
      "config": {
        "severity": "medium",
        "type": "unusual_time",
        "message": "Transação às {{metadata.transactionHour}}:00 - fora do horário normal do usuário"
      }
    }
  ]
}

Condições Avançadas

Condições Aninhadas

{
  "conditions": {
    "operator": "OR",
    "conditions": [
      {
        "operator": "AND",
        "conditions": [
          {"field": "amount", "operator": "GREATER_THAN", "value": 5000},
          {"field": "type", "operator": "EQUALS", "value": "WITHDRAWAL"}
        ]
      },
      {
        "operator": "AND",
        "conditions": [
          {"field": "amount", "operator": "GREATER_THAN", "value": 10000},
          {"field": "type", "operator": "EQUALS", "value": "TRANSFER"}
        ]
      }
    ]
  }
}

Padrões Regex

{
  "field": "description",
  "operator": "REGEX",
  "value": "^(test|demo|fake).*"
}

Agregações Baseadas em Tempo

{
  "field": "metadata.userTransactionCount",
  "operator": "GREATER_THAN",
  "value": 5,
  "timeWindow": "1h"
}

Melhores Práticas

✅ FAÇA

Use o modo de avaliação apropriado
- SYNC para decisões que devem bloquear
- ASYNC para monitoramento e análise
Defina prioridades corretas
- Bloqueios críticos: 900-1000
- Verificações padrão: 500-899
- Monitoramento: 100-499
Inclua mensagens significativas
- Use variáveis de template: {{field}}
- Forneça contexto para analistas
- Inclua métricas relevantes
Teste minuciosamente
- Comece com modo ASYNC
- Monitore taxa de falsos positivos
- Ajuste limites com base em dados
Use campos de metadados
- Dados agregados para padrões
- Rastreie comportamento histórico
- Calcule pontuações de risco

❌ NÃO FAÇA

Não use consultas pesadas em regras SYNC
- Mantenha regras SYNC rápidas (< 100ms)
- Mova lógica complexa para ASYNC
Não bloqueie excessivamente
- Comece com HOLD ao invés de REJECT
- Permita revisão manual
- Monitore impacto no cliente
Não crie regras sobrepostas
- Uma regra deve tratar um padrão
- Use prioridades corretamente
- Evite verificações redundantes
Não ignore falsos positivos
- Rastreie e analise
- Ajuste limites
- Use aprendizado de máquina quando disponível

Testando Regras

Modo de Teste

Habilite o modo de teste para avaliar regras sem afetar transações:

{
  "name": "Regra de Teste",
  "enabled": true,
  "testMode": true,
  ...
}

Teste A/B

Crie regras variantes para comparar eficácia:

{
  "name": "Verificação de Fraude - Variante A",
  "variant": "A",
  "percentage": 50,
  ...
}

Métricas de Monitoramento

Rastreie para cada regra:

Contagem de execuções: Quantas vezes a regra executa
Taxa de correspondência: % de vezes que condições foram atendidas
Taxa de falsos positivos: Sinalizados incorretamente
Taxa de verdadeiros positivos: Sinalizados corretamente
Tempo médio de execução: Desempenho

Próximos Passos

Detecção de Fraudes

Regras de fraude prontas para produção

Monitoramento AML

Regras de conformidade AML

Monitoramento de Comerciantes

Regras de risco de comerciantes

Referência da API

Documentação completa da API

Começando

Casos de Uso

Webhooks

Pessoa

Empresa

Dispositivos

Eventos

Conheça Seu Cliente (KYC)

Transações

Métodos de Pagamento

Regras

Matriz de Risco

Alertas

Investigações

Ingestão de Dados

Enriquecimento

Integrações

Tutoriais Interativos

​Introdução

​Regras Síncronas vs Assíncronas

​Regras Síncronas (SYNC)

​Regras Assíncronas (ASYNC)

​Estrutura da Regra

​Campos de Configuração

​Campos Básicos

​Condições

​Operadores de Condição

​Campos de Transação Disponíveis

​Ações

​1. Gerar Alerta

​2. Definir Decisão (apenas SYNC)

​3. Criar Investigação

​Exemplos de Regras

​1. Limite Diário de Transação (SYNC)

​2. Alerta de Velocidade de Transações (ASYNC)

​3. Bloqueio de País de Alto Risco (SYNC)

​4. Detecção de Padrão de Estruturação (ASYNC)

​5. Novo Cartão com Valor Alto (SYNC)

​6. Padrão de Horário Incomum (ASYNC)

​Condições Avançadas

​Condições Aninhadas

​Padrões Regex

​Agregações Baseadas em Tempo

​Melhores Práticas

​✅ FAÇA

​❌ NÃO FAÇA

​Testando Regras

​Modo de Teste

​Teste A/B

​Métricas de Monitoramento

​Próximos Passos