Skip to main content
GET
/
rules
Listar Regras
curl --request GET \
  --url http://api.gu1.ai/rules \
  --header 'Authorization: Bearer <token>'
{
  "rules": [
    {}
  ],
  "total": "<string>",
  "page": 123,
  "pageSize": 123,
  "totalPages": 123
}

​
Visão Geral

Recupera una lista paginada de reglas con soporte para filtrado por estado, categoría, tipo de entidad, etiquetas y búsqueda. Útil para mostrar bibliotecas de reglas, dashboards e interfaces de administración.

​
Endpoint

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

​
Autenticação

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

​
Parâmetros de Consulta

​
page
number
default:"1"
Número de página para paginación
​
pageSize
number
default:"20"
Número de reglas por página (máx: 100)
​
status
string
Filtrar por estado: draft, active, shadow, archived, inactive
​
category
string
Filtrar por categoría: kyc, kyb, aml, fraud, compliance, custom
​
enabled
boolean
Filtrar por estado habilitado: true o false
​
targetEntityType
string
Filtrar por tipo de entidad: person, company, transaction
​
riskMatrixId
string
Filtrar por UUID de matriz de riesgo
​
tags
string
Filtrar por etiquetas (separadas por comas): high-risk,pep,sanctions
​
search
string
Buscar en nombre y descripción de regla
​
sortBy
string
default:"updatedAt"
Campo de ordenamiento: name, priority, createdAt, updatedAt, score
​
sortOrder
string
default:"desc"
Orden de clasificación: asc o desc

​
Respuesta

​
rules
array
Array de objetos de regla
​
total
string
Número total de reglas que coinciden con los filtros
​
page
number
Número de página actual
​
pageSize
number
Número de elementos por página
​
totalPages
number
Número total de páginas

​
Exemplos de Requisições

​
Listar Todas las Reglas Activas

curl -X GET "http://api.gu1.ai/rules?status=active&enabled=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Buscar Reglas

curl -X GET "http://api.gu1.ai/rules?search=sanctions&category=aml" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Filtrar por Tipo de Entidad y Matriz de Riesgo

curl -X GET "http://api.gu1.ai/rules?targetEntityType=company&riskMatrixId=d257247b-af7b-402a-ad8f-eac209e2990e&pageSize=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Ordenar por Prioridad

curl -X GET "http://api.gu1.ai/rules?sortBy=priority&sortOrder=desc&status=active" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Filtrar por Etiquetas

curl -X GET "http://api.gu1.ai/rules?tags=high-risk,pep" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Exemplo de Resposta

{
  "rules": [
    {
      "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,
      "targetEntityTypes": ["company"],
      "evaluationMode": "sync",
      "riskMatrixId": "d257247b-af7b-402a-ad8f-eac209e2990e",
      "version": 1,
      "tags": [],
      "createdBy": "f35c10cb-9b67-4cda-9aea-f36567375dba",
      "createdAt": "2024-12-22T14:10:28.131Z",
      "updatedAt": "2024-12-22T14:44:29.627Z",
      "stats": {
        "failures": 0,
        "successes": 7,
        "executions": 7
      }
    },
    {
      "id": "a5a29ed9-1e98-4a57-8e89-3aa819d5da0a",
      "organizationId": "71e8f908-e032-4fcb-b0ce-ad0cd0ffb236",
      "name": "Terrorism Sanctions Check",
      "description": "Detect entities with terrorism-related sanctions",
      "category": "aml",
      "status": "active",
      "enabled": true,
      "priority": 100,
      "score": 95,
      "targetEntityTypes": ["person", "company"],
      "evaluationMode": "sync",
      "riskMatrixId": "b6d543cb-1006-4bbb-8777-c43859d51c8a",
      "version": 1,
      "tags": ["sanctions", "terrorism", "critical"],
      "createdBy": "f35c10cb-9b67-4cda-9aea-f36567375dba",
      "createdAt": "2024-12-21T17:09:00.746Z",
      "updatedAt": "2024-12-22T14:41:32.821Z",
      "stats": {
        "failures": 12,
        "successes": 7,
        "executions": 19
      }
    }
  ],
  "total": "2",
  "page": 1,
  "pageSize": 20,
  "totalPages": 1
}

​
Ejemplo de Paginación

async function getAllRules() {
  const allRules = [];
  let page = 1;
  const pageSize = 100;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `http://api.gu1.ai/rules?page=${page}&pageSize=${pageSize}`,
      {
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY'
        }
      }
    );

    const data = await response.json();
    allRules.push(...data.rules);

    hasMore = page < data.totalPages;
    page++;
  }

  return allRules;
}

// Uso
const rules = await getAllRules();
console.log(`Recuperadas ${rules.length} reglas en total`);

​
Casos de Uso

​
Construir Dashboard de Reglas

async function buildRuleDashboard() {
  // Obtener reglas activas agrupadas por categoría
  const categories = ['kyc', 'kyb', 'aml', 'fraud', 'compliance'];
  const dashboard = {};

  for (const category of categories) {
    const response = await fetch(
      `http://api.gu1.ai/rules?category=${category}&status=active`,
      {
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY'
        }
      }
    );

    const data = await response.json();
    dashboard[category] = {
      total: parseInt(data.total),
      rules: data.rules.map(r => ({
        id: r.id,
        name: r.name,
        enabled: r.enabled,
        priority: r.priority,
        score: r.score,
        executions: r.stats.executions,
        successRate: (r.stats.successes / r.stats.executions * 100).toFixed(1) + '%'
      }))
    };
  }

  return dashboard;
}

​
Monitorear Reglas de Alta Prioridad

def monitor_high_priority_rules():
    """Monitorear reglas con prioridad >= 90"""
    response = requests.get(
        'http://api.gu1.ai/rules',
        headers={
            'Authorization': 'Bearer YOUR_API_KEY'
        },
        params={
            'sortBy': 'priority',
            'sortOrder': 'desc',
            'pageSize': 100
        }
    )

    data = response.json()
    high_priority = [r for r in data['rules'] if r['priority'] >= 90]

    print(f"Encontradas {len(high_priority)} reglas de alta prioridad:\n")

    for rule in high_priority:
        status_icon = '✅' if rule['enabled'] else '❌'
        print(f"{status_icon} [{rule['priority']}] {rule['name']}")
        print(f"   Categoría: {rule['category']}")
        print(f"   Ejecuciones: {rule['stats']['executions']}")
        print(f"   Tasa de Éxito: {rule['stats']['successes'] / max(rule['stats']['executions'], 1) * 100:.1f}%")
        print()

    return high_priority

​
Buscar Reglas por Matriz de Riesgo

async function getRulesByMatrix(riskMatrixId) {
  const response = await fetch(
    `http://api.gu1.ai/rules?riskMatrixId=${riskMatrixId}&pageSize=100`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const data = await response.json();

  return {
    matrixId: riskMatrixId,
    totalRules: parseInt(data.total),
    active: data.rules.filter(r => r.enabled).length,
    inactive: data.rules.filter(r => !r.enabled).length,
    byCategory: data.rules.reduce((acc, rule) => {
      acc[rule.category] = (acc[rule.category] || 0) + 1;
      return acc;
    }, {}),
    rules: data.rules
  };
}

​
Buscar y Filtrar

def search_rules(search_term, filters=None):
    """Búsqueda avanzada de reglas con múltiples filtros"""
    params = {
        'search': search_term,
        'pageSize': 50
    }

    if filters:
        params.update(filters)

    response = requests.get(
        'http://api.gu1.ai/rules',
        headers={
            'Authorization': 'Bearer YOUR_API_KEY'
        },
        params=params
    )

    data = response.json()

    print(f"Búsqueda: '{search_term}'")
    if filters:
        print(f"Filtros: {filters}")
    print(f"Resultados: {data['total']} reglas encontradas\n")

    for rule in data['rules']:
        print(f"- {rule['name']}")
        print(f"  Categoría: {rule['category']} | Estado: {rule['status']}")
        print(f"  Puntaje: {rule['score']} | Prioridad: {rule['priority']}")
        print()

    return data['rules']

# Ejemplo de uso
search_rules('pep', {
    'category': 'aml',
    'status': 'active',
    'enabled': True
})

​
Exportar Reglas para Respaldo

async function exportAllRules() {
  const response = await fetch(
    'http://api.gu1.ai/rules?pageSize=100',
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const data = await response.json();

  // Crear objeto de respaldo
  const backup = {
    exportDate: new Date().toISOString(),
    totalRules: parseInt(data.total),
    rules: data.rules.map(rule => ({
      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.scope,
      tags: rule.tags
    }))
  };

  // Guardar a archivo (Node.js)
  const fs = require('fs');
  fs.writeFileSync(
    `rules-backup-${Date.now()}.json`,
    JSON.stringify(backup, null, 2)
  );

  console.log(`Exportadas ${backup.totalRules} reglas`);

  return backup;
}

​
Melhores Práticas

  1. Usar Paginación: Siempre paginar al recuperar conjuntos grandes de reglas
  2. Filtrar Eficientemente: Combinar filtros para reducir resultados (categoría + estado + habilitado)
  3. Cachear Resultados: Cachear listas de reglas accedidas frecuentemente
  4. Ordenar Estratégicamente: Ordenar por prioridad para orden de ejecución, por updatedAt para cambios recientes
  5. Monitorear Rendimiento: Rastrear reglas con altas tasas de fallo usando stats
  6. Usar Etiquetas: Aprovechar etiquetas para organización y filtrado personalizado

​
Notas de Rendimiento

  • Tamaño de página predeterminado: 20 reglas
  • Tamaño máximo de página: 100 reglas
  • Tiempo de respuesta promedio: 50-150ms
  • Índices de búsqueda: nombre, descripción
  • Índices de filtro: status, category, enabled, targetEntityType, riskMatrixId

​
Veja Também