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

# Listar Reglas

> Consultar y filtrar reglas con paginación — en el motor de reglas gu1 para compliance y detección de riesgo, con ejemplos para list.

## Descripción General

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
```

## Autenticación

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

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Parámetros de Consulta

<ParamField query="page" type="number" default="1">
  Número de página para paginación
</ParamField>

<ParamField query="pageSize" type="number" default="20">
  Número de reglas por página (máx: 100)
</ParamField>

<ParamField query="status" type="string">
  Filtrar por estado: `draft`, `active`, `shadow`, `archived`, `inactive`
</ParamField>

<ParamField query="category" type="string">
  Filtrar por categoría: `kyc`, `kyb`, `aml`, `fraud`, `compliance`, `custom`
</ParamField>

<ParamField query="enabled" type="boolean">
  Filtrar por estado habilitado: `true` o `false`
</ParamField>

<ParamField query="targetEntityType" type="string">
  Filtrar por tipo de entidad: `person`, `company`, `transaction`
</ParamField>

<ParamField query="riskMatrixId" type="string">
  Filtrar por UUID de matriz de riesgo
</ParamField>

<ParamField query="tags" type="string">
  Filtrar por etiquetas (separadas por comas): `high-risk,pep,sanctions`
</ParamField>

<ParamField query="search" type="string">
  Buscar en nombre y descripción de regla
</ParamField>

<ParamField query="sortBy" type="string" default="updatedAt">
  Campo de ordenamiento: `name`, `priority`, `createdAt`, `updatedAt`, `score`
</ParamField>

<ParamField query="sortOrder" type="string" default="desc">
  Orden de clasificación: `asc` o `desc`
</ParamField>

## Respuesta

<ResponseField name="rules" type="array">
  Array de objetos de regla
</ResponseField>

<ResponseField name="total" type="string">
  Número total de reglas que coinciden con los filtros
</ResponseField>

<ResponseField name="page" type="number">
  Número de página actual
</ResponseField>

<ResponseField name="pageSize" type="number">
  Número de elementos por página
</ResponseField>

<ResponseField name="totalPages" type="number">
  Número total de páginas
</ResponseField>

## Ejemplos de Solicitudes

### Listar Todas las Reglas Activas

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "http://api.gu1.ai/rules?status=active&enabled=true" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'http://api.gu1.ai/rules?status=active&enabled=true',
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const data = await response.json();
  console.log(`Encontradas ${data.total} reglas activas`);
  console.log('Reglas:', data.rules.map(r => r.name));
  ```

  ```python Python theme={null}
  import requests

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

  data = response.json()
  print(f"Encontradas {data['total']} reglas activas")
  for rule in data['rules']:
      print(f"  - {rule['name']}")
  ```
</CodeGroup>

### Buscar Reglas

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "http://api.gu1.ai/rules?search=sanctions&category=aml" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'http://api.gu1.ai/rules?search=sanctions&category=aml',
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const data = await response.json();
  console.log(`Encontradas ${data.total} reglas que coinciden con "sanctions"`);
  ```

  ```python Python theme={null}
  response = requests.get(
      'http://api.gu1.ai/rules',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY'
      },
      params={
          'search': 'sanctions',
          'category': 'aml'
      }
  )

  data = response.json()
  print(f"Encontradas {data['total']} reglas que coinciden con 'sanctions'")
  ```
</CodeGroup>

### Filtrar por Tipo de Entidad y Matriz de Riesgo

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "http://api.gu1.ai/rules?targetEntityType=company&riskMatrixId=d257247b-af7b-402a-ad8f-eac209e2990e&pageSize=50" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'http://api.gu1.ai/rules?' + new URLSearchParams({
      targetEntityType: 'company',
      riskMatrixId: 'd257247b-af7b-402a-ad8f-eac209e2990e',
      pageSize: 50
    }),
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const data = await response.json();
  console.log(`Encontradas ${data.total} reglas de empresas en esta matriz`);
  ```

  ```python Python theme={null}
  response = requests.get(
      'http://api.gu1.ai/rules',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY'
      },
      params={
          'targetEntityType': 'company',
          'riskMatrixId': 'd257247b-af7b-402a-ad8f-eac209e2990e',
          'pageSize': 50
      }
  )

  data = response.json()
  print(f"Encontradas {data['total']} reglas de empresas en esta matriz")
  ```
</CodeGroup>

### Ordenar por Prioridad

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "http://api.gu1.ai/rules?sortBy=priority&sortOrder=desc&status=active" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'http://api.gu1.ai/rules?sortBy=priority&sortOrder=desc&status=active',
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const data = await response.json();
  console.log('Reglas ordenadas por prioridad:');
  data.rules.forEach(rule => {
    console.log(`  [${rule.priority}] ${rule.name}`);
  });
  ```

  ```python Python theme={null}
  response = requests.get(
      'http://api.gu1.ai/rules',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY'
      },
      params={
          'sortBy': 'priority',
          'sortOrder': 'desc',
          'status': 'active'
      }
  )

  data = response.json()
  print('Reglas ordenadas por prioridad:')
  for rule in data['rules']:
      print(f"  [{rule['priority']}] {rule['name']}")
  ```
</CodeGroup>

### Filtrar por Etiquetas

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "http://api.gu1.ai/rules?tags=high-risk,pep" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'http://api.gu1.ai/rules?tags=high-risk,pep',
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const data = await response.json();
  console.log(`Encontradas ${data.total} reglas etiquetadas con high-risk O pep`);
  ```

  ```python Python theme={null}
  response = requests.get(
      'http://api.gu1.ai/rules',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY'
      },
      params={
          'tags': 'high-risk,pep'
      }
  )

  data = response.json()
  print(f"Encontradas {data['total']} reglas etiquetadas con high-risk O pep")
  ```
</CodeGroup>

## Ejemplo de Respuesta

```json theme={null}
{
  "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

```javascript theme={null}
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

```javascript theme={null}
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

```python theme={null}
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

```javascript theme={null}
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

```python theme={null}
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

```javascript theme={null}
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;
}
```

## Mejores Prácticas

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

## Ver También

* [Obtener Regla](/es/api-reference/rules/get) - Recuperar detalles específicos de regla
* [Crear Regla](/es/api-reference/rules/create) - Crear nuevas reglas
* [Actualizar Regla](/es/api-reference/rules/update) - Modificar reglas existentes
* [Ejecutar Regla](/es/api-reference/rules/execute) - Probar ejecución de regla