Skip to main content

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.

​
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

CampoTipoDescrição
namestringNome da regra (único)
categorystringCategoria: fraud, aml, compliance, risk
prioritynumberPrioridade de execução (1-1000, maior = primeiro)
enabledbooleanHabilitar/desabilitar regra
evaluationModestring”sync” ou “async”
targetEntityTypesarrayTipos 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

OperadorDescriçãoExemplo
EQUALSIgualdade exata"type" EQUALS "PAYMENT"
NOT_EQUALSNão igual"status" NOT_EQUALS "blocked"
GREATER_THANMaior que"amount" > 1000
GREATER_THAN_OR_EQUALMaior ou igual"amount" >= 1000
LESS_THANMenor que"amount" < 100
LESS_THAN_OR_EQUALMenor ou igual"amount" <= 100
INNa lista"country" IN ["US", "CA"]
NOT_INNão na lista"country" NOT_IN ["KP", "IR"]
CONTAINSString contém"description" CONTAINS "test"
NOT_CONTAINSString não contém"email" NOT_CONTAINS "@temp"
STARTS_WITHString começa com"accountId" STARTS_WITH "4532"
ENDS_WITHString termina com"domain" ENDS_WITH ".ru"
REGEXCorrespondência regex"email" REGEX "^[a-z]+@"
EXISTSCampo existe"metadata.userId" EXISTS
NOT_EXISTSCampo 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

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

​
❌ NÃO FAÇA

  1. Não use consultas pesadas em regras SYNC
    • Mantenha regras SYNC rápidas (< 100ms)
    • Mova lógica complexa para ASYNC
  2. Não bloqueie excessivamente
    • Comece com HOLD ao invés de REJECT
    • Permita revisão manual
    • Monitore impacto no cliente
  3. Não crie regras sobrepostas
    • Uma regra deve tratar um padrão
    • Use prioridades corretamente
    • Evite verificações redundantes
  4. 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