Criar Regra

Visão Geral

Cria uma nova regra para detecção automatizada de riscos, monitoramento de conformidade e prevenção de fraudes. As regras podem avaliar entidades (pessoas, empresas), transações, relacionamentos e padrões de rede usando lógica de condições flexível e ações automatizadas.

Endpoint

POST http://api.gu1.ai/rules

Autenticação

Requer uma chave API válida no cabeçalho de Authorization:

Authorization: Bearer YOUR_API_KEY

Corpo da Requisição

name

string

required

Nome descritivo para a regra

description

string

required

Descrição detalhada do que a regra detecta

Estrutura de Condições

As regras usam uma estrutura de condições aninhadas com operadores lógicos:

{
  "operator": "AND" | "OR" | "NOT" | "XOR",
  "conditions": [
    {
      "id": "cond-unique-id",
      "type": "simple",
      "field": "enrichmentData.normalized.taxId",
      "operator": "eq",
      "value": "12.345.678/0001-90",
      "filters": [],
      "countryMetadata": {
        "countryCode": "BR",
        "confidence": 100,
        "manuallySet": true,
        "autoDetected": false,
        "reason": "Selected from BR enrichment fields"
      }
    }
  ]
}

Campos de Condições

operator: Operador lógico conectando condições (AND, OR, NOT, XOR)
conditions: Array de objetos de condição (podem ser aninhados para lógica complexa)
id: Identificador único para a condição
type: Tipo de condição (simple, complex, array, object)
field: Caminho do campo a avaliar (ex., taxId, entityData.company.revenue, enrichmentData.normalized.sanctions.$.type)
operator: Operador de comparação (veja Operadores abaixo)
value: Valor para comparar
filters: Array de filtros para campos de array/objeto
countryMetadata: Metadados específicos do país para a condição

Operadores

Operadores de Comparação

eq - Igual
neq - Não igual
gt - Maior que
gte - Maior ou igual
lt - Menor que
lte - Menor ou igual

Operadores de String

contains - Contém substring
notContains - Não contém substring
startsWith - Começa com
endsWith - Termina com
regex - Corresponde à expressão regular

Operadores de Array

in - Valor está no array
notIn - Valor não está no array
hasAny - Tem algum dos valores
hasAll - Tem todos os valores

Operadores de Lista

inList - Valor existe em uma lista de dados
notInList - Valor não existe em uma lista de dados

Operadores de Existência

exists - Campo existe
notExists - Campo não existe
isEmpty - Campo está vazio/nulo
isNotEmpty - Campo não está vazio/nulo

Operadores Booleanos

isTrue - Campo booleano é verdadeiro
isFalse - Campo booleano é falso

Sintaxe de Campos de Array

Para campos dentro de arrays, use o símbolo $:

{
  "field": "enrichmentData.normalized.sanctions.$.type",
  "operator": "in",
  "value": "terrorism",
  "filters": []
}

Isso avalia se QUALQUER item no array sanctions tem type igual a "terrorism".

Filtros

Você pode pré-filtrar itens do array antes da avaliação:

{
  "field": "enrichmentData.normalized.legalProceedings.$.amount",
  "operator": "gt",
  "value": 100000,
  "filters": [
    {
      "field": "status",
      "operator": "eq",
      "value": "active"
    }
  ]
}

Isso avalia se QUALQUER processo legal ativo tem um valor maior que 100.000.

Ações

As regras suportam múltiplos tipos de ações:

Criar Alerta

{
  "type": "createAlert",
  "createAlert": {
    "type": "FRAUD" | "COMPLIANCE" | "AML" | "KYC" | "OTHER",
    "title": "High Risk Transaction Detected",
    "description": "Transaction exceeds threshold",
    "severity": "LOW" | "MEDIUM" | "HIGH" | "CRITICAL",
    "recipients": ["user@example.com"]
  },
  "tags": ["high-value", "cross-border"]
}

Atualizar Status da Entidade

{
  "type": "updateEntityStatus",
  "updateEntityStatus": {
    "status": "blocked",
    "reason": "Failed sanctions check"
  }
}

Enviar Notificação

{
  "type": "sendNotification",
  "sendNotification": {
    "channel": "email" | "sms" | "webhook",
    "recipients": ["compliance@company.com"],
    "message": "Urgent: High risk entity detected"
  }
}

Criar Caso

{
  "type": "createCase",
  "createCase": {
    "title": "PEP Investigation Required",
    "description": "Entity flagged as politically exposed person",
    "assignee": "user-uuid"
  }
}

Exemplos de Requisições

Regra KYC Simples - Verificar Tax ID

curl -X POST http://api.gu1.ai/rules \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CNPJ Blocklist Check",
    "description": "Block companies with specific CNPJ",
    "category": "kyb",
    "targetEntityTypes": ["company"],
    "enabled": true,
    "priority": 100,
    "score": 85,
    "conditions": {
      "operator": "AND",
      "conditions": [
        {
          "id": "cond-1",
          "type": "simple",
          "field": "enrichmentData.normalized.taxId",
          "operator": "eq",
          "value": "33.592.510/0001-54",
          "filters": [],
          "countryMetadata": {
            "countryCode": "BR",
            "confidence": 100,
            "manuallySet": true,
            "autoDetected": false,
            "reason": "Selected from BR enrichment fields"
          }
        }
      ]
    },
    "actions": [
      {
        "type": "createAlert",
        "createAlert": {
          "type": "COMPLIANCE",
          "title": "Blocklisted Company Detected",
          "description": "Company CNPJ found in blocklist",
          "severity": "CRITICAL",
          "recipients": ["compliance@company.com"]
        },
        "tags": ["blocklist", "high-priority"]
      },
      {
        "type": "updateEntityStatus",
        "updateEntityStatus": {
          "status": "blocked",
          "reason": "CNPJ in blocklist"
        }
      }
    ],
    "scope": {
      "type": "entity",
      "countries": ["BR"],
      "entityTypes": ["company"]
    },
    "status": "active",
    "evaluationMode": "sync"
  }'

Regra Complexa - Verificação de Sanções com Múltiplas Condições

curl -X POST http://api.gu1.ai/rules \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Terrorism Sanctions Check",
    "description": "Detect entities with terrorism-related sanctions",
    "category": "aml",
    "targetEntityTypes": ["person", "company"],
    "enabled": true,
    "priority": 100,
    "score": 95,
    "conditions": {
      "operator": "OR",
      "conditions": [
        {
          "id": "cond-1",
          "type": "simple",
          "field": "enrichmentData.normalized.sanctions.$.type",
          "operator": "in",
          "value": "terrorism",
          "filters": [],
          "countryMetadata": {
            "countryCode": "GLOBAL",
            "confidence": 100,
            "manuallySet": true,
            "autoDetected": false,
            "reason": "Global sanctions field"
          }
        },
        {
          "id": "cond-2",
          "type": "simple",
          "field": "enrichmentData.normalized.sanctioned",
          "operator": "isTrue",
          "value": true,
          "filters": []
        }
      ]
    },
    "actions": [
      {
        "type": "createAlert",
        "createAlert": {
          "type": "AML",
          "title": "Sanctions Match - Immediate Review Required",
          "description": "Entity matched terrorism sanctions list",
          "severity": "CRITICAL",
          "recipients": ["aml-team@company.com"]
        },
        "tags": ["sanctions", "terrorism", "critical"]
      },
      {
        "type": "updateEntityStatus",
        "updateEntityStatus": {
          "status": "blocked",
          "reason": "Terrorism sanctions match"
        }
      },
      {
        "type": "createCase",
        "createCase": {
          "title": "Sanctions Investigation Required",
          "description": "Entity flagged for terrorism-related sanctions",
          "assignee": "compliance-lead-uuid"
        }
      }
    ],
    "scope": {
      "type": "entity",
      "entityTypes": ["person", "company"]
    },
    "status": "active",
    "evaluationMode": "sync",
    "tags": ["sanctions", "aml", "critical"]
  }'

Regra de Monitoramento de Transações

curl -X POST http://api.gu1.ai/rules \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High Value Transaction Alert",
    "description": "Alert on transactions over $50,000 USD",
    "category": "fraud",
    "targetEntityTypes": ["transaction"],
    "enabled": true,
    "priority": 80,
    "score": 70,
    "conditions": {
      "operator": "AND",
      "conditions": [
        {
          "id": "cond-1",
          "type": "simple",
          "field": "amountInUsd",
          "operator": "gt",
          "value": 50000,
          "filters": []
        },
        {
          "id": "cond-2",
          "type": "simple",
          "field": "status",
          "operator": "eq",
          "value": "PENDING",
          "filters": []
        }
      ]
    },
    "actions": [
      {
        "type": "createAlert",
        "createAlert": {
          "type": "FRAUD",
          "title": "High Value Transaction Detected",
          "description": "Transaction exceeds $50,000 threshold",
          "severity": "HIGH",
          "recipients": ["fraud-team@company.com"]
        },
        "tags": ["high-value", "pending-review"]
      }
    ],
    "scope": {
      "type": "transaction"
    },
    "status": "active",
    "evaluationMode": "sync"
  }'

Resposta

string

UUID da regra criada

name

string

Nome da regra

description

string

Descrição da regra

organizationId

string

ID da sua organização

status

string

Status atual da regra

enabled

boolean

Se a regra está habilitada

version

number

Número da versão da regra

createdAt

string

Timestamp ISO de criação

createdBy

string

ID do usuário que criou a regra

Exemplo de Resposta

{
  "id": "e2cdd639-52cc-4749-9b16-927bfa5dfaea",
  "organizationId": "71e8f908-e032-4fcb-b0ce-ad0cd0ffb236",
  "name": "CNPJ Blocklist Check",
  "description": "Block companies with specific CNPJ",
  "category": "kyb",
  "status": "active",
  "enabled": true,
  "priority": 100,
  "score": 85,
  "conditions": {
    "operator": "AND",
    "conditions": [...]
  },
  "actions": [
    {
      "type": "createAlert",
      "createAlert": {...},
      "tags": ["blocklist", "high-priority"]
    }
  ],
  "scope": {
    "type": "entity",
    "countries": ["BR"],
    "entityTypes": ["company"]
  },
  "targetEntityTypes": ["company"],
  "evaluationMode": "sync",
  "version": 1,
  "previousVersionId": null,
  "tags": [],
  "createdBy": "f35c10cb-9b67-4cda-9aea-f36567375dba",
  "createdAt": "2024-12-23T10:00:00.000Z",
  "updatedAt": "2024-12-23T10:00:00.000Z",
  "stats": {
    "executions": 0,
    "successes": 0,
    "failures": 0
  }
}

Respostas de Erro

400 Bad Request - Condição Inválida

{
  "error": "Validation failed",
  "details": {
    "field": "conditions",
    "message": "Invalid operator 'xyz'"
  }
}

400 Bad Request - Campos Obrigatórios Faltando

{
  "error": "Validation failed",
  "details": {
    "missingFields": ["name", "targetEntityTypes", "conditions"]
  }
}

401 Unauthorized

{
  "error": "Invalid or missing API key"
}

Melhores Práticas

Comece com Modo Shadow: Use status: "shadow" para testar regras sem afetar produção
Use Nomes Descritivos: Torne os nomes das regras claros e pesquisáveis
Defina Prioridades Apropriadas: Regras de maior prioridade executam primeiro (escala 1-100)
Marque suas Regras: Use tags para organização e filtragem
Regras Específicas por País: Use scope.countries para conformidade geo-específica
Teste Completamente: Teste regras com dados de exemplo antes de habilitar
Monitore o Desempenho: Use modo sync para regras críticas em tempo real, async para processamento em lote
Pontue Estrategicamente: Alinhe pontuações com os limites da sua matriz de risco

Veja Também

Referência de Campos de Condições - Lista completa de campos de condição disponíveis por tipo de entidade e país
Executar Regra - Testar regras contra entidades específicas
Listar Regras - Consultar e filtrar regras
Atualizar Regra - Modificar regras existentes

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

​Visão Geral

​Endpoint

​Autenticação

​Corpo da Requisição

​Estrutura de Condições

​Campos de Condições

​Operadores

​Operadores de Comparação

​Operadores de String

​Operadores de Array

​Operadores de Lista

​Operadores de Existência

​Operadores Booleanos

​Sintaxe de Campos de Array

​Filtros

​Ações

​Criar Alerta

​Atualizar Status da Entidade

​Enviar Notificação

​Criar Caso

​Exemplos de Requisições

​Regra KYC Simples - Verificar Tax ID

​Regra Complexa - Verificação de Sanções com Múltiplas Condições

​Regra de Monitoramento de Transações

​Resposta

​Exemplo de Resposta

​Respostas de Erro

​400 Bad Request - Condição Inválida

​400 Bad Request - Campos Obrigatórios Faltando

​401 Unauthorized

​Melhores Práticas

​Veja Também

Visão Geral

Endpoint

Autenticação

Corpo da Requisição

Estrutura de Condições

Campos de Condições

Operadores

Operadores de Comparação

Operadores de String

Operadores de Array

Operadores de Lista

Operadores de Existência

Operadores Booleanos

Sintaxe de Campos de Array

Filtros

Ações

Criar Alerta

Atualizar Status da Entidade

Enviar Notificação

Criar Caso

Exemplos de Requisições

Regra KYC Simples - Verificar Tax ID

Regra Complexa - Verificação de Sanções com Múltiplas Condições

Regra de Monitoramento de Transações

Resposta

Exemplo de Resposta

Respostas de Erro

400 Bad Request - Condição Inválida

400 Bad Request - Campos Obrigatórios Faltando

401 Unauthorized

Melhores Práticas

Veja Também