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

# Como Criar Regras de Compliance e Risco

> Tutorial completo sobre o motor de regras do gu1: constructor visual, código personalizado e integração com IA — no painel gu1 com orientação passo a passo.

## Tutorial Interativo

<Info>
  **Em breve**: Vídeo interativo com Clueso estará disponível aqui. Por enquanto, siga o guia passo a passo abaixo.
</Info>

## Visão Geral

O **motor de regras** do gu1 permite criar avaliações automáticas de risco e compliance para entidades (pessoas, empresas, transações). Você pode:

* Criar regras sem código usando o **constructor visual**
* Escrever lógica personalizada em **JavaScript**
* Usar **análise de IA** para avaliações complexas
* Combinar múltiplas condições com operadores lógicos
* Definir ações automáticas (criar alertas, enviar webhooks, etc.)

<Tip>
  **Recomendação**: Comece com o constructor visual para regras simples e evolua para código quando precisar de lógica mais sofisticada.
</Tip>

## Passos Resumidos

<Steps>
  <Step title="Acesse o Gerenciador de Regras">
    Navegue até **Rules** no menu lateral esquerdo do dashboard gu1.
  </Step>

  <Step title="Clique em 'Create Rule'">
    No topo direito, clique no botão **+ Create Rule** (azul).
  </Step>

  <Step title="Configure Informações Básicas">
    * **Nome**: Escolha um nome descritivo (ex: "PEP Screening - Alto Risco")
    * **Descrição**: Explique o que a regra faz
    * **Tipo de entidade**: Selecione Person, Company ou Transaction
    * **Categoria**: Escolha AML, KYC, Fraud, Credit, etc.
  </Step>

  <Step title="Defina Condições">
    Use o constructor visual ou escreva código JavaScript para definir quando a regra deve ser executada.
  </Step>

  <Step title="Configure Ações">
    Defina o que acontece quando a regra é ativada:

    * Criar alerta
    * Atualizar score de risco
    * Enviar webhook
    * Executar integração externa
  </Step>

  <Step title="Teste a Regra">
    Use o **Rule Tester** para validar com entidades de exemplo antes de publicar.
  </Step>

  <Step title="Publique">
    Quando estiver satisfeito, clique em **Publish** para ativar a regra.
  </Step>
</Steps>

## Constructor Visual vs. Código

<Tabs>
  <Tab title="Constructor Visual">
    ### Quando Usar

    * Regras simples baseadas em propriedades da entidade
    * Comparações diretas (igual, maior que, contém, etc.)
    * Múltiplas condições com AND/OR
    * Não requer conhecimento de programação

    ### Exemplo: PEP Screening

    ```
    SE
      person.isPEP = true
      E
      person.pep.level EM ["National", "International"]
      E
      person.country EM ["Venezuela", "Syria", "Iran"]
    ENTÃO
      Criar alerta de ALTA prioridade
    ```

    ### Como Funciona

    1. Clique em **+ Add Condition**
    2. Selecione o **campo** (ex: `person.isPEP`)
    3. Escolha o **operador** (ex: `equals`, `greaterThan`, `in`)
    4. Defina o **valor** de comparação
    5. Adicione mais condições se necessário
    6. Configure o operador lógico entre condições (AND/OR)
  </Tab>

  <Tab title="Código JavaScript">
    ### Quando Usar

    * Lógica complexa com cálculos
    * Loops e iterações
    * Validações customizadas
    * Integrações com APIs externas
    * Manipulação de arrays e objetos aninhados

    ### Exemplo: Score de Risco Creditício

    ```javascript theme={null}
    // Acesso completo à entidade
    const { person, documents, transactions } = entity;

    // Cálculo customizado
    let score = 0;

    // Idade
    if (person.age < 25) score += 10;
    else if (person.age > 65) score += 5;

    // Renda
    const income = person.income || 0;
    if (income < 2000) score += 20;
    else if (income < 5000) score += 10;

    // Histórico de transações
    const suspiciousCount = transactions.filter(t =>
      t.amount > 10000 && t.country !== person.country
    ).length;

    score += suspiciousCount * 5;

    // Documentos ausentes
    const requiredDocs = ['id', 'proof_of_address', 'income_statement'];
    const missingDocs = requiredDocs.filter(doc =>
      !documents.some(d => d.type === doc)
    );

    score += missingDocs.length * 15;

    // Retornar decisão
    return {
      shouldTrigger: score > 50,
      metadata: {
        riskScore: score,
        missingDocs,
        suspiciousTransactions: suspiciousCount
      }
    };
    ```

    ### API Disponível

    * `entity` - Objeto completo da entidade
    * `context` - Informações contextuais (organizationId, userId, etc.)
    * `fetch()` - Para chamadas HTTP externas
    * `console.log()` - Para debugging (visível nos logs)
  </Tab>

  <Tab title="Análise de IA">
    ### Quando Usar

    * Análise de texto não estruturado
    * Detecção de padrões complexos
    * Avaliação de notícias e mídia adversa
    * Análise de sentimento
    * Contextualização de dados

    ### Exemplo: Análise de Notícias Adversas

    ```javascript theme={null}
    // Usar o serviço de IA do gu1
    const aiAnalysis = await analyzeEntity(entity, {
      prompt: `
        Analise as notícias sobre esta pessoa:
        ${entity.person.news.map(n => n.title).join('\n')}

        Identifique:
        1. Envolvimento em crimes financeiros
        2. Processos judiciais ativos
        3. Associações com organizações criminosas
        4. Reputação geral

        Retorne um score de 0-100 (100 = alto risco)
      `,
      language: 'pt'
    });

    return {
      shouldTrigger: aiAnalysis.score > 70,
      metadata: {
        aiScore: aiAnalysis.score,
        findings: aiAnalysis.findings,
        reasoning: aiAnalysis.reasoning
      }
    };
    ```

    <Warning>
      **Custo**: Análises de IA consomem tokens e têm custo adicional. Use com moderação ou configure limites de execução.
    </Warning>
  </Tab>
</Tabs>

## Tipos de Condições

<CardGroup cols={2}>
  <Card title="Propriedades" icon="database">
    **Campos da entidade**

    * `person.age >= 18`
    * `company.revenue < 1000000`
    * `transaction.amount > 10000`
    * `person.country in ["BR", "AR", "UY"]`
  </Card>

  <Card title="Documentos" icon="file-check">
    **Validação de docs**

    * Documento ausente
    * Documento expirado
    * Documento rejeitado
    * Tipo de documento específico
  </Card>

  <Card title="Relacionamentos" icon="diagram-project">
    **Grafos de entidades**

    * Pessoa é sócio de empresa
    * Empresa tem relação com PEP
    * Transação entre entidades relacionadas
    * Profundidade de relacionamento
  </Card>

  <Card title="Histórico" icon="clock-rotate-left">
    **Eventos passados**

    * Alertas prévios
    * Investigações fechadas
    * Mudanças de dados
    * Padrões temporais
  </Card>

  <Card title="Listas Externas" icon="list-check">
    **Screening**

    * Sanctions lists (OFAC, UN, EU)
    * PEP databases
    * Watchlists personalizadas
    * Listas de bloqueio internas
  </Card>

  <Card title="Integrações" icon="plug">
    **APIs externas**

    * ComplyAdvantage
    * Bureau de crédito
    * Validadores de documentos
    * Provedores de dados
  </Card>
</CardGroup>

## Ações Disponíveis

Quando uma regra é ativada, você pode executar múltiplas ações:

<AccordionGroup>
  <Accordion title="Criar Alerta" icon="bell">
    **Configuração**:

    * **Prioridade**: Low, Medium, High, Critical
    * **Tipo**: AML, Fraud, Compliance, Credit
    * **Mensagem**: Texto descritivo ou template
    * **Atribuir a**: Time ou usuário específico
    * **Tags**: Para categorização adicional

    **Exemplo**:

    ```json theme={null}
    {
      "type": "create_alert",
      "config": {
        "priority": "high",
        "alertType": "aml",
        "message": "PEP de alto risco detectado: {{person.name}}",
        "assignTo": "compliance-team",
        "tags": ["pep", "high-risk", "latam"]
      }
    }
    ```
  </Accordion>

  <Accordion title="Atualizar Score de Risco" icon="gauge-high">
    **Configuração**:

    * **Score**: Valor numérico (0-100)
    * **Categoria**: AML, Credit, Fraud, etc.
    * **Justificativa**: Explicação para auditoria

    **Exemplo**:

    ```json theme={null}
    {
      "type": "update_risk_score",
      "config": {
        "score": 85,
        "category": "aml",
        "reason": "Múltiplos fatores de risco identificados"
      }
    }
    ```
  </Accordion>

  <Accordion title="Enviar Webhook" icon="webhook">
    **Configuração**:

    * **URL**: Endpoint HTTP do seu sistema
    * **Método**: POST, PUT, PATCH
    * **Headers**: Autenticação e metadata
    * **Payload**: Dados da entidade e resultado da regra

    **Exemplo**:

    ```json theme={null}
    {
      "type": "webhook",
      "config": {
        "url": "https://yourapi.com/webhooks/gueno",
        "method": "POST",
        "headers": {
          "Authorization": "Bearer {{api_key}}",
          "Content-Type": "application/json"
        },
        "payload": {
          "entityId": "{{entity.id}}",
          "ruleId": "{{rule.id}}",
          "result": "{{result}}"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Executar Integração" icon="arrows-turn-to-dots">
    **Integrações disponíveis**:

    * **ComplyAdvantage**: Screening adicional
    * **Validadores de documento**: OCR e verificação
    * **Bureau de crédito**: Consulta de score
    * **BACEN/Receita Federal**: Dados públicos

    **Exemplo**:

    ```json theme={null}
    {
      "type": "integration",
      "config": {
        "provider": "complyadvantage",
        "action": "screening",
        "params": {
          "entityType": "person",
          "searchDepth": "deep"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Notificar Time" icon="envelope">
    **Configuração**:

    * **Canal**: Email, Slack, Teams, SMS
    * **Destinatários**: Times ou usuários específicos
    * **Template**: Mensagem personalizada

    **Exemplo**:

    ```json theme={null}
    {
      "type": "notification",
      "config": {
        "channel": "slack",
        "recipients": ["#compliance-alerts"],
        "template": "pep-alert",
        "data": {
          "entityName": "{{person.name}}",
          "riskScore": "{{result.riskScore}}"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Criar Investigação" icon="magnifying-glass">
    **Configuração**:

    * **Prioridade**: Low, Medium, High, Critical
    * **Tipo**: Due Diligence, Enhanced DD, Adverse Media
    * **Atribuir a**: Analista ou time
    * **Consolidar alertas**: Agrupar alertas relacionados

    **Exemplo**:

    ```json theme={null}
    {
      "type": "create_investigation",
      "config": {
        "priority": "high",
        "investigationType": "enhanced_dd",
        "assignTo": "senior-analyst-team",
        "consolidateAlerts": true
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Testando Regras

<Warning>
  **Importante**: Sempre teste regras antes de publicar para evitar falsos positivos e impacto em produção.
</Warning>

### Rule Tester

O **Rule Tester** permite validar regras com entidades reais:

<Steps>
  <Step title="Abra o Tester">
    Na página da regra, clique em **Test Rule** no canto superior direito.
  </Step>

  <Step title="Selecione Entidades">
    Escolha entidades existentes ou crie dados de teste (mock).
  </Step>

  <Step title="Execute">
    Clique em **Run Test** para ver os resultados.
  </Step>

  <Step title="Analise Output">
    Verifique:

    * Regra foi ativada corretamente?
    * Ações foram executadas?
    * Metadata está correto?
    * Logs estão claros?
  </Step>
</Steps>

### Dados de Teste (Mock)

Crie entidades sintéticas para testar casos extremos:

```json theme={null}
{
  "type": "person",
  "data": {
    "name": "João Silva",
    "age": 42,
    "country": "BR",
    "isPEP": true,
    "pep": {
      "level": "National",
      "position": "Senador Federal"
    },
    "income": 15000,
    "documents": [
      { "type": "cpf", "number": "123.456.789-00", "status": "valid" },
      { "type": "proof_of_address", "status": "pending" }
    ]
  }
}
```

## Boas Práticas

<CardGroup cols={2}>
  <Card title="Nomeação Clara" icon="tag">
    Use nomes descritivos que expliquem o propósito da regra:

    * ✅ "PEP Nacional - Criar Alerta Alto Risco"
    * ❌ "Regra 123"
  </Card>

  <Card title="Documentação" icon="book">
    Sempre preencha a descrição explicando:

    * Por que a regra existe
    * Quando ela é ativada
    * O que ela faz
  </Card>

  <Card title="Versionamento" icon="code-branch">
    Ao editar regras em produção:

    * Crie uma nova versão
    * Teste em staging primeiro
    * Documente mudanças
  </Card>

  <Card title="Monitoramento" icon="chart-line">
    Acompanhe métricas:

    * Taxa de ativação
    * Falsos positivos
    * Tempo de execução
    * Custo (para regras com IA)
  </Card>
</CardGroup>

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Gerenciar Alertas" icon="bell" href="/pt/tutoriais/gerenciar-alertas">
    Aprenda a revisar e resolver alertas gerados pelas regras
  </Card>

  <Card title="Configurar Webhooks" icon="webhook" href="/pt/webhooks/configuration">
    Integre alertas com seus sistemas existentes
  </Card>

  <Card title="Referência de API" icon="code" href="/pt/api-reference/rules/create">
    Crie e gerencie regras via API
  </Card>

  <Card title="Casos de Uso KYB" icon="building" href="/pt/use-cases/kyb/overview">
    Exemplos de regras para análise de empresas
  </Card>
</CardGroup>

## Precisa de Ajuda?

* **Documentação**: Navegue por nossas guias completas
* **Email**: [support@gueno.com](mailto:support@gueno.com)
* **Dashboard**: Acesse sua conta em [app.gu1.ai](https://app.gu1.ai)

***

**Última atualização**: Janeiro 2025