Skip to main content
GET
http://api.gu1.ai
/
rules
/
{id}
Obter Regra
curl --request GET \
  --url http://api.gu1.ai/rules/{id} \
  --header 'Authorization: Bearer <token>'
{
  "id": "<string>",
  "organizationId": "<string>",
  "name": "<string>",
  "description": "<string>",
  "category": "<string>",
  "status": "<string>",
  "enabled": true,
  "priority": 123,
  "score": 123,
  "conditions": {},
  "conditionCode": "<string>",
  "actions": [
    {}
  ],
  "scope": {},
  "targetEntityTypes": [
    {}
  ],
  "evaluationMode": "<string>",
  "riskMatrixId": "<string>",
  "version": 123,
  "previousVersionId": "<string>",
  "tags": [
    {}
  ],
  "stats": {},
  "createdBy": "<string>",
  "createdAt": "<string>",
  "updatedBy": "<string>",
  "updatedAt": "<string>"
}

Visão Geral

Recupera informações completas sobre uma regra específica, incluindo suas condições, ações, estatísticas de execução e histórico de versões.

Endpoint

GET http://api.gu1.ai/rules/{id}

Autenticação

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

Parâmetros de Rota

id
string
required
UUID da regra a recuperar

Resposta

id
string
UUID da regra
organizationId
string
ID da sua organização
name
string
Nome da regra
description
string
Descrição da regra
category
string
Categoria da regra (kyc, kyb, aml, fraud, compliance, custom)
status
string
Status atual (draft, active, shadow, archived, inactive)
enabled
boolean
Se a regra está habilitada
priority
number
Prioridade da regra (1-100)
score
number
Pontuação de risco atribuída quando a regra corresponde
conditions
object
Estrutura de condições completa com lógica aninhada
conditionCode
string
Representação em string JSON das condições (para armazenamento)
actions
array
Array de ações a executar quando a regra corresponde
scope
object
Configuração de escopo da regra (países, tipos de entidade, janelas temporais)
targetEntityTypes
array
Array de tipos de entidade aos quais a regra se aplica
evaluationMode
string
Modo de avaliação (sync ou async)
riskMatrixId
string
UUID da matriz de risco associada (se houver)
version
number
Número da versão atual
previousVersionId
string
UUID da versão anterior (se houver)
tags
array
Array de tags para organização
stats
object
Estatísticas de execução (execuções, sucessos, falhas)
createdBy
string
ID do usuário que criou a regra
createdAt
string
Timestamp ISO de criação
updatedBy
string
ID do usuário que atualizou a regra por último
updatedAt
string
Timestamp ISO da última atualização

Exemplos de Requisições

curl -X GET http://api.gu1.ai/rules/e2cdd639-52cc-4749-9b16-927bfa5dfaea \
  -H "Authorization: Bearer YOUR_API_KEY"

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": [
      {
        "id": "cond-1766412627987-0",
        "type": "simple",
        "field": "enrichmentData.normalized.taxId",
        "value": "33.592.510/0001-54",
        "filters": [],
        "operator": "eq",
        "countryMetadata": {
          "reason": "Selected from BR enrichment fields",
          "confidence": 100,
          "countryCode": "BR",
          "manuallySet": true,
          "autoDetected": false
        }
      }
    ]
  },
  "conditionCode": "{\"operator\":\"AND\",\"conditions\":[{\"field\":\"enrichmentData.normalized.taxId\",\"operator\":\"eq\",\"value\":\"33.592.510/0001-54\",\"countryMetadata\":{\"countryCode\":\"BR\",\"autoDetected\":false,\"manuallySet\":true,\"confidence\":100,\"reason\":\"Selected from BR enrichment fields\"},\"filters\":[],\"id\":\"cond-1766412627987-0\",\"type\":\"simple\"}]}",
  "actions": [
    {
      "tags": ["blocklist", "high-priority"],
      "type": "createAlert",
      "createAlert": {
        "type": "COMPLIANCE",
        "title": "Blocklisted Company Detected",
        "severity": "CRITICAL",
        "recipients": ["compliance@company.com"],
        "description": "Company CNPJ found in blocklist"
      }
    },
    {
      "tags": [],
      "type": "updateEntityStatus",
      "updateEntityStatus": {
        "status": "blocked",
        "reason": "CNPJ in blocklist"
      }
    }
  ],
  "scope": {
    "type": "entity",
    "countries": ["BR"],
    "entityTypes": ["company"],
    "temporalWindow": {
      "days": 30,
      "hours": 24
    }
  },
  "targetEntityTypes": ["company"],
  "evaluationMode": "sync",
  "riskMatrixId": "d257247b-af7b-402a-ad8f-eac209e2990e",
  "version": 1,
  "previousVersionId": null,
  "abTest": null,
  "schedule": null,
  "tags": [],
  "createdBy": "f35c10cb-9b67-4cda-9aea-f36567375dba",
  "createdAt": "2024-12-22T14:10:28.131Z",
  "updatedBy": "f35c10cb-9b67-4cda-9aea-f36567375dba",
  "updatedAt": "2024-12-22T14:44:29.627Z",
  "stats": {
    "failures": 0,
    "successes": 7,
    "executions": 7
  }
}

Respostas de Erro

404 Not Found

{
  "error": "Rule not found",
  "id": "e2cdd639-52cc-4749-9b16-927bfa5dfaea"
}

401 Unauthorized

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

403 Forbidden

{
  "error": "Access denied",
  "message": "You don't have permission to view this rule"
}

Casos de Uso

Exibir Detalhes da Regra na UI

async function loadRuleDetails(ruleId) {
  const response = await fetch(
    `http://api.gu1.ai/rules/${ruleId}`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const rule = await response.json();

  return {
    id: rule.id,
    name: rule.name,
    description: rule.description,
    status: rule.status,
    enabled: rule.enabled,
    priority: rule.priority,
    score: rule.score,
    category: rule.category,
    lastUpdated: new Date(rule.updatedAt),
    performance: {
      executions: rule.stats.executions,
      successRate: (rule.stats.successes / rule.stats.executions * 100).toFixed(1) + '%',
      failureRate: (rule.stats.failures / rule.stats.executions * 100).toFixed(1) + '%'
    },
    conditions: rule.conditions,
    actions: rule.actions.map(a => ({
      type: a.type,
      details: a[a.type]
    }))
  };
}

Monitorar Desempenho da Regra

def monitor_rule_performance(rule_id):
    """Monitorar estatísticas de execução da regra"""
    response = requests.get(
        f'http://api.gu1.ai/rules/{rule_id}',
        headers={
            'Authorization': 'Bearer YOUR_API_KEY'
        }
    )

    rule = response.json()
    stats = rule['stats']

    total = stats['executions']
    if total == 0:
        print(f"Regra '{rule['name']}' ainda não foi executada")
        return

    success_rate = (stats['successes'] / total) * 100
    failure_rate = (stats['failures'] / total) * 100

    print(f"Regra: {rule['name']}")
    print(f"Status: {rule['status']}")
    print(f"Habilitada: {rule['enabled']}")
    print(f"\nDesempenho:")
    print(f"  Total de Execuções: {total}")
    print(f"  Taxa de Sucesso: {success_rate:.1f}%")
    print(f"  Taxa de Falha: {failure_rate:.1f}%")
    print(f"\nÚltima Atualização: {rule['updatedAt']}")

    # Alertar se taxa de falha for alta
    if failure_rate > 10:
        print(f"\nAVISO: Taxa de falha alta detectada!")

    return rule

Clonar Configuração da Regra

async function cloneRule(sourceRuleId, newName) {
  // Obter a regra de origem
  const response = await fetch(
    `http://api.gu1.ai/rules/${sourceRuleId}`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const sourceRule = await response.json();

  // Criar nova regra com nome modificado
  const newRule = {
    name: newName,
    description: `Clonada de: ${sourceRule.name}`,
    category: sourceRule.category,
    targetEntityTypes: sourceRule.targetEntityTypes,
    conditions: sourceRule.conditions,
    actions: sourceRule.actions,
    enabled: false, // Iniciar desabilitada
    priority: sourceRule.priority,
    score: sourceRule.score,
    status: 'draft', // Iniciar como rascunho
    evaluationMode: sourceRule.evaluationMode,
    scope: sourceRule.scope,
    tags: [...sourceRule.tags, 'cloned']
  };

  // Criar a regra clonada
  const createResponse = await fetch(
    'http://api.gu1.ai/rules',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(newRule)
    }
  );

  const clonedRule = await createResponse.json();
  console.log('Regra clonada com sucesso:', clonedRule.id);

  return clonedRule;
}

Exportar Configuração da Regra

import json

def export_rule_config(rule_id, output_file):
    """Exportar configuração da regra para arquivo JSON"""
    response = requests.get(
        f'http://api.gu1.ai/rules/{rule_id}',
        headers={
            'Authorization': 'Bearer YOUR_API_KEY'
        }
    )

    rule = response.json()

    # Remover campos de runtime
    export_data = {
        'name': rule['name'],
        'description': rule['description'],
        'category': rule['category'],
        'targetEntityTypes': rule['targetEntityTypes'],
        'conditions': rule['conditions'],
        'actions': rule['actions'],
        'priority': rule['priority'],
        'score': rule['score'],
        'evaluationMode': rule['evaluationMode'],
        'scope': rule.get('scope'),
        'tags': rule.get('tags', [])
    }

    # Escrever no arquivo
    with open(output_file, 'w') as f:
        json.dump(export_data, f, indent=2)

    print(f"Configuração da regra exportada para {output_file}")
    return export_data

Melhores Práticas

  1. Cache de Dados da Regra: Fazer cache de regras acessadas frequentemente para reduzir chamadas API
  2. Monitorar Estatísticas: Revisar regularmente o objeto stats para insights de desempenho
  3. Rastrear Versões: Usar version e previousVersionId para trilhas de auditoria
  4. Verificar Status: Sempre verificar enabled e status antes da execução
  5. Usar Tags: Aproveitar tags para organização e filtragem

Veja Também