Skip to main content
GET
http://api.gu1.ai
/
rules
/
{id}
Obtener Regla
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>"
}

Descripción General

Recupera información completa sobre una regla específica, incluyendo sus condiciones, acciones, estadísticas de ejecución e historial de versiones.

Endpoint

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

Autenticación

Requiere una clave API válida en el encabezado de Authorization:
Authorization: Bearer YOUR_API_KEY

Parámetros de Ruta

id
string
required
UUID de la regla a recuperar

Respuesta

id
string
UUID de la regla
organizationId
string
ID de su organización
name
string
Nombre de la regla
description
string
Descripción de la regla
category
string
Categoría de la regla (kyc, kyb, aml, fraud, compliance, custom)
status
string
Estado actual (draft, active, shadow, archived, inactive)
enabled
boolean
Si la regla está habilitada
priority
number
Prioridad de la regla (1-100)
score
number
Puntaje de riesgo asignado cuando la regla coincide
conditions
object
Estructura de condiciones completa con lógica anidada
conditionCode
string
Representación en cadena JSON de condiciones (para almacenamiento)
actions
array
Array de acciones a ejecutar cuando la regla coincide
scope
object
Configuración de alcance de la regla (países, tipos de entidad, ventanas temporales)
targetEntityTypes
array
Array de tipos de entidad a los que se aplica la regla
evaluationMode
string
Modo de evaluación (sync o async)
riskMatrixId
string
UUID de matriz de riesgo asociada (si existe)
version
number
Número de versión actual
previousVersionId
string
UUID de la versión anterior (si existe)
tags
array
Array de etiquetas para organización
stats
object
Estadísticas de ejecución (ejecuciones, éxitos, fallos)
createdBy
string
ID del usuario que creó la regla
createdAt
string
Marca de tiempo ISO de creación
updatedBy
string
ID del usuario que actualizó la regla por última vez
updatedAt
string
Marca de tiempo ISO de última actualización

Ejemplos de Solicitudes

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

Ejemplo de Respuesta

{
  "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
  }
}

Respuestas de Error

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

Mostrar Detalles de Regla en 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]
    }))
  };
}

Monitorear Rendimiento de Regla

def monitor_rule_performance(rule_id):
    """Monitorear estadísticas de ejecución de regla"""
    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"Regla '{rule['name']}' no se ha ejecutado aún")
        return

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

    print(f"Regla: {rule['name']}")
    print(f"Estado: {rule['status']}")
    print(f"Habilitada: {rule['enabled']}")
    print(f"\nRendimiento:")
    print(f"  Total de Ejecuciones: {total}")
    print(f"  Tasa de Éxito: {success_rate:.1f}%")
    print(f"  Tasa de Fallo: {failure_rate:.1f}%")
    print(f"\nÚltima Actualización: {rule['updatedAt']}")

    # Alertar si la tasa de fallo es alta
    if failure_rate > 10:
        print(f"\nADVERTENCIA: Tasa de fallo alta detectada!")

    return rule

Clonar Configuración de Regla

async function cloneRule(sourceRuleId, newName) {
  // Obtener la regla origen
  const response = await fetch(
    `http://api.gu1.ai/rules/${sourceRuleId}`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const sourceRule = await response.json();

  // Crear nueva regla con nombre 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 deshabilitada
    priority: sourceRule.priority,
    score: sourceRule.score,
    status: 'draft', // Iniciar como borrador
    evaluationMode: sourceRule.evaluationMode,
    scope: sourceRule.scope,
    tags: [...sourceRule.tags, 'cloned']
  };

  // Crear la regla 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('Regla clonada exitosamente:', clonedRule.id);

  return clonedRule;
}

Exportar Configuración de Regla

import json

def export_rule_config(rule_id, output_file):
    """Exportar configuración de regla a archivo 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', [])
    }

    # Escribir a archivo
    with open(output_file, 'w') as f:
        json.dump(export_data, f, indent=2)

    print(f"Configuración de regla exportada a {output_file}")
    return export_data

Mejores Prácticas

  1. Cache de Datos de Regla: Cachear reglas accedidas frecuentemente para reducir llamadas API
  2. Monitorear Estadísticas: Revisar regularmente el objeto stats para insights de rendimiento
  3. Rastrear Versiones: Usar version y previousVersionId para pistas de auditoría
  4. Verificar Estado: Siempre verificar enabled y status antes de la ejecución
  5. Usar Etiquetas: Aprovechar etiquetas para organización y filtrado

Ver También