> ## 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. # Configuração de Regras > Guia completo para criar e configurar regras de monitoramento de transações — no produto de monitoramento de transações gu1 para fraude e AML. ## 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 ```json theme={null} { "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: ```json theme={null} { "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 ```javascript theme={null} // 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 ```json theme={null} { "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) ```json theme={null} { "type": "set_decision", "config": { "decision": "APPROVE|REJECT|HOLD|REVIEW_REQUIRED|ADDITIONAL_AUTH_REQUIRED", "reason": "Motivo da decisão" } } ``` #### 3. Criar Investigação ```json theme={null} { "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) ```json theme={null} { "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) ```json theme={null} { "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) ```json theme={null} { "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) ```json theme={null} { "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) ```json theme={null} { "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) ```json theme={null} { "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 ```json theme={null} { "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 ```json theme={null} { "field": "description", "operator": "REGEX", "value": "^(test|demo|fake).*" } ``` ### Agregações Baseadas em Tempo ```json theme={null} { "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: ```json theme={null} { "name": "Regra de Teste", "enabled": true, "testMode": true, ... } ``` ### Teste A/B Crie regras variantes para comparar eficácia: ```json theme={null} { "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 Regras de fraude prontas para produção Regras de conformidade AML Regras de risco de comerciantes Documentação completa da API Criar listas e itens para `in_custom_list` e operadores relacionados