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

# Ejecutar Regla

> Ejecutar una regla contra una entidad específica para pruebas y validación — en el motor de reglas gu1 para compliance y detección de riesgo.

## Descripción General

Ejecuta una regla específica contra una entidad para probar la lógica de la regla, validar condiciones y previsualizar resultados antes de desplegar a producción. Útil para probar reglas en modo shadow o depurar comportamiento de reglas.

## Endpoint

```
POST http://api.gu1.ai/rules/{ruleId}/execute
```

## Autenticación

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

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

## Parámetros de Ruta

<ParamField path="ruleId" type="string" required>
  UUID de la regla a ejecutar
</ParamField>

## Cuerpo de la Solicitud

<ParamField body="entityId" type="string" required>
  UUID de la entidad a evaluar contra la regla
</ParamField>

<ParamField body="testMode" type="boolean" default="false">
  Si es true, ejecuta en modo de prueba sin crear alertas o modificar entidades
</ParamField>

<ParamField body="includeDebug" type="boolean" default="false">
  Si es true, incluye información de depuración detallada sobre evaluación de condiciones
</ParamField>

## Respuesta

<ResponseField name="matched" type="boolean">
  Si las condiciones de la regla coincidieron
</ResponseField>

<ResponseField name="score" type="number">
  Puntaje de riesgo asignado por la regla (si coincidió)
</ResponseField>

<ResponseField name="executionTime" type="number">
  Tiempo de ejecución en milisegundos
</ResponseField>

<ResponseField name="conditions" type="object">
  Resultados de evaluación detallados para cada condición
</ResponseField>

<ResponseField name="actions" type="array">
  Acciones que se ejecutarían (o fueron ejecutadas si no está en modo de prueba)
</ResponseField>

<ResponseField name="debug" type="object">
  Información de depuración (si includeDebug=true)
</ResponseField>

## Ejemplos de Solicitudes

### Ejecutar Regla en Modo de Prueba

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST http://api.gu1.ai/rules/e2cdd639-52cc-4749-9b16-927bfa5dfaea/execute \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "entityId": "550e8400-e29b-41d4-a716-446655440000",
      "testMode": true,
      "includeDebug": true
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'http://api.gu1.ai/rules/e2cdd639-52cc-4749-9b16-927bfa5dfaea/execute',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        entityId: '550e8400-e29b-41d4-a716-446655440000',
        testMode: true,
        includeDebug: true
      })
    }
  );

  const result = await response.json();
  console.log('Regla coincidió:', result.matched);
  console.log('Puntaje:', result.score);
  console.log('Tiempo de ejecución:', result.executionTime + 'ms');
  ```

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

  response = requests.post(
      'http://api.gu1.ai/rules/e2cdd639-52cc-4749-9b16-927bfa5dfaea/execute',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'entityId': '550e8400-e29b-41d4-a716-446655440000',
          'testMode': True,
          'includeDebug': True
      }
  )

  result = response.json()
  print(f"Regla coincidió: {result['matched']}")
  print(f"Puntaje: {result['score']}")
  print(f"Tiempo de ejecución: {result['executionTime']}ms")
  ```
</CodeGroup>

### Ejecutar Regla en Modo de Producción

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST http://api.gu1.ai/rules/e2cdd639-52cc-4749-9b16-927bfa5dfaea/execute \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "entityId": "550e8400-e29b-41d4-a716-446655440000",
      "testMode": false
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'http://api.gu1.ai/rules/e2cdd639-52cc-4749-9b16-927bfa5dfaea/execute',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        entityId: '550e8400-e29b-41d4-a716-446655440000',
        testMode: false
      })
    }
  );

  const result = await response.json();
  if (result.matched) {
    console.log('Regla coincidió! Acciones ejecutadas:', result.actions.length);
  }
  ```

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

  response = requests.post(
      'http://api.gu1.ai/rules/e2cdd639-52cc-4749-9b16-927bfa5dfaea/execute',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'entityId': '550e8400-e29b-41d4-a716-446655440000',
          'testMode': False
      }
  )

  result = response.json()
  if result['matched']:
      print(f"Regla coincidió! Acciones ejecutadas: {len(result['actions'])}")
  ```
</CodeGroup>

## Ejemplos de Respuestas

### Coincidencia Exitosa con Información de Depuración

```json theme={null}
{
  "matched": true,
  "score": 85,
  "executionTime": 45,
  "conditions": {
    "operator": "AND",
    "result": true,
    "conditions": [
      {
        "id": "cond-1",
        "field": "enrichmentData.normalized.taxId",
        "operator": "eq",
        "expectedValue": "33.592.510/0001-54",
        "actualValue": "33.592.510/0001-54",
        "result": true
      }
    ]
  },
  "actions": [
    {
      "type": "createAlert",
      "status": "would_execute",
      "details": {
        "type": "COMPLIANCE",
        "title": "Blocklisted Company Detected",
        "severity": "CRITICAL"
      }
    },
    {
      "type": "updateEntityStatus",
      "status": "would_execute",
      "details": {
        "status": "blocked",
        "reason": "CNPJ in blocklist"
      }
    }
  ],
  "debug": {
    "entitySnapshot": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "company",
      "taxId": "33.592.510/0001-54",
      "name": "Test Company"
    },
    "conditionEvaluationOrder": ["cond-1"],
    "shortCircuited": false,
    "cacheHits": 0
  }
}
```

### Sin Coincidencia

```json theme={null}
{
  "matched": false,
  "score": 0,
  "executionTime": 23,
  "conditions": {
    "operator": "AND",
    "result": false,
    "conditions": [
      {
        "id": "cond-1",
        "field": "enrichmentData.normalized.taxId",
        "operator": "eq",
        "expectedValue": "33.592.510/0001-54",
        "actualValue": "12.345.678/0001-90",
        "result": false
      }
    ]
  },
  "actions": [],
  "debug": null
}
```

### Modo de Producción - Acciones Ejecutadas

```json theme={null}
{
  "matched": true,
  "score": 85,
  "executionTime": 156,
  "conditions": {
    "operator": "AND",
    "result": true,
    "conditions": [...]
  },
  "actions": [
    {
      "type": "createAlert",
      "status": "executed",
      "alertId": "alert-uuid-123",
      "details": {
        "type": "COMPLIANCE",
        "title": "Blocklisted Company Detected",
        "severity": "CRITICAL"
      }
    },
    {
      "type": "updateEntityStatus",
      "status": "executed",
      "details": {
        "previousStatus": "active",
        "newStatus": "blocked",
        "reason": "CNPJ in blocklist"
      }
    }
  ]
}
```

## Respuestas de Error

### 404 Not Found - Regla

```json theme={null}
{
  "error": "Rule not found",
  "ruleId": "e2cdd639-52cc-4749-9b16-927bfa5dfaea"
}
```

### 404 Not Found - Entidad

```json theme={null}
{
  "error": "Entity not found",
  "entityId": "550e8400-e29b-41d4-a716-446655440000"
}
```

### 400 Bad Request - Desajuste de Tipo

```json theme={null}
{
  "error": "Entity type mismatch",
  "details": {
    "ruleTargetTypes": ["company"],
    "entityType": "person",
    "message": "This rule only applies to company entities"
  }
}
```

### 400 Bad Request - Regla Deshabilitada

```json theme={null}
{
  "error": "Rule is disabled",
  "ruleId": "e2cdd639-52cc-4749-9b16-927bfa5dfaea"
}
```

## Casos de Uso

### Probar Nuevas Reglas

```javascript theme={null}
// Probar una nueva regla contra entidades de muestra antes de habilitar
async function testRuleAgainstSamples(ruleId, sampleEntityIds) {
  const results = [];

  for (const entityId of sampleEntityIds) {
    const response = await fetch(
      `http://api.gu1.ai/rules/${ruleId}/execute`,
      {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          entityId,
          testMode: true,
          includeDebug: true
        })
      }
    );

    const result = await response.json();
    results.push({
      entityId,
      matched: result.matched,
      executionTime: result.executionTime
    });
  }

  console.log('Resultados de Prueba:', results);
  console.log('Tasa de coincidencia:',
    results.filter(r => r.matched).length / results.length * 100 + '%'
  );

  return results;
}
```

### Depurar Comportamiento de Regla

```python theme={null}
def debug_rule_execution(rule_id, entity_id):
    """Obtener información detallada de depuración para ejecución de regla"""
    response = requests.post(
        f'http://api.gu1.ai/rules/{rule_id}/execute',
        headers={
            'Authorization': 'Bearer YOUR_API_KEY',
            'Content-Type': 'application/json'
        },
        json={
            'entityId': entity_id,
            'testMode': True,
            'includeDebug': True
        }
    )

    result = response.json()

    print(f"Regla Coincidió: {result['matched']}")
    print(f"Tiempo de Ejecución: {result['executionTime']}ms")
    print("\nEvaluación de Condiciones:")

    for condition in result['conditions']['conditions']:
        print(f"  - {condition['field']}: ", end='')
        print(f"{condition['actualValue']} {condition['operator']} {condition['expectedValue']}")
        print(f"    Resultado: {'✅ Pasa' if condition['result'] else '❌ Falla'}")

    if result.get('debug'):
        print("\nInformación de Depuración:")
        print(f"  Short-circuited: {result['debug']['shortCircuited']}")
        print(f"  Cache hits: {result['debug']['cacheHits']}")

    return result
```

### Pruebas por Lotes

```javascript theme={null}
// Probar múltiples entidades contra una regla
async function batchTestRule(ruleId, entityIds) {
  const batchSize = 10;
  const results = {
    total: entityIds.length,
    matched: 0,
    failed: 0,
    avgExecutionTime: 0
  };

  for (let i = 0; i < entityIds.length; i += batchSize) {
    const batch = entityIds.slice(i, i + batchSize);
    const promises = batch.map(entityId =>
      fetch(`http://api.gu1.ai/rules/${ruleId}/execute`, {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          entityId,
          testMode: true
        })
      }).then(r => r.json())
    );

    const batchResults = await Promise.all(promises);

    batchResults.forEach(result => {
      if (result.matched) results.matched++;
      results.avgExecutionTime += result.executionTime;
    });
  }

  results.avgExecutionTime = Math.round(
    results.avgExecutionTime / entityIds.length
  );

  console.log('Resultados de Prueba por Lotes:', results);
  return results;
}
```

## Mejores Prácticas

1. **Siempre Probar Primero**: Use `testMode: true` antes de ejecutar reglas en producción
2. **Habilitar Depuración para Desarrollo**: Use `includeDebug: true` para entender comportamiento de reglas
3. **Probar Casos Extremos**: Pruebe con entidades que deberían y no deberían coincidir
4. **Monitorear Tiempo de Ejecución**: Optimice reglas que toman más de 200ms
5. **Validar Acciones**: Revise detalles de acciones antes de habilitar modo de producción
6. **Usar Modo Shadow**: Despliegue reglas con `status: "shadow"` para registrar coincidencias sin ejecutar acciones

## Notas de Rendimiento

* Tiempo promedio de ejecución: 50-150ms
* Reglas sync bloquean la solicitud, reglas async retornan inmediatamente
* Condiciones anidadas complejas pueden aumentar tiempo de ejecución
* Evaluaciones de campos de array con filtros agregan \~10-30ms por array

## Ver También

* [Crear Regla](/es/api-reference/rules/create) - Crear nuevas reglas
* [Referencia de Campos de Condiciones](/es/api-reference/rules/conditions) - Campos de condición disponibles
* [Listar Reglas](/es/api-reference/rules/list) - Consultar reglas
* [Actualizar Regla](/es/api-reference/rules/update) - Modificar reglas existentes