> ## Documentation Index
> Fetch the complete documentation index at: https://gotrebol.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Reglas de validación

> Reglas predefinidas y personalizadas que puedes aplicar al validar documentos con Trébol, tanto en widget como en API.

Las reglas de validación permiten aplicar condiciones sobre un documento para determinar si cumple con ciertos criterios (antigüedad, mención de entidad, vigencia, etc.).

Trébol ofrece dos tipos de reglas:

* **Reglas predefinidas**: reglas optimizadas que Trébol provee listas para usar (IDs con prefijo `vr_trebol_`)
* **Reglas personalizadas**: reglas donde tú defines el prompt de validación

***

## Dónde se usan las reglas

Las reglas de validación se aplican en dos contextos:

### En widget (dentro de un `account-flow`)

Al crear un flujo para widget, las reglas se definen dentro del `record_validation_schema` del flujo. Cada requerimiento de documento puede tener su propio `ruleset`. Ver [Crear el flujo](/docs/guia-devs/crear-verificaciones/via-widget/crear-flujo).

### En API (dentro de un item `doc_validation`)

Al crear una verificación vía API con un item de tipo `doc_validation`, las reglas se pasan directamente en `options.ruleset`. Ver [Forma 2: Validación](/docs/guia-devs/crear-verificaciones/via-api/forma-validacion).

***

## Reglas predefinidas

Las reglas predefinidas de Trébol están optimizadas y no requieren que escribas el prompt de validación. Solo necesitas el ID de la regla y los parámetros necesarios.

<Tip>
  **Ventaja de usar reglas predefinidas:** Mejor rendimiento y resultados más consistentes que las reglas personalizadas. **Importante:** No incluyas el campo `validation_rule` cuando uses reglas predefinidas.
</Tip>

### Reglas disponibles

<AccordionGroup>
  <Accordion title="vr_trebol_vencimiento - Validar vencimiento del documento">
    Valida si el documento ha vencido o no. Ideal para documentos con fecha de vencimiento como identificaciones oficiales, pasaportes, o certificados.

    **Parámetros:**

    * Ninguno

    **Ejemplo de uso:**

    ```json theme={"dark"}
    {
      "id": "vr_trebol_vencimiento",
      "error_message": "El documento no debe estar vencido",
      "params": {}
    }
    ```

    **Casos de uso:**

    * Validar que una identificación oficial (INE) esté vigente
    * Verificar que un pasaporte no haya expirado
    * Confirmar la vigencia de certificados o licencias
  </Accordion>

  <Accordion title="vr_trebol_antiguedad - Validar antigüedad del documento">
    Valida si el documento tiene menos de X días de antigüedad desde su fecha de emisión. Útil para documentos que solo tienen fecha de emisión y necesitas verificar que no sean muy antiguos.

    **Parámetros:**

    * `days` (number): Número máximo de días permitidos desde la emisión del documento

    **Ejemplo de uso:**

    ```json theme={"dark"}
    {
      "id": "vr_trebol_antiguedad",
      "error_message": "El documento debe tener menos de 90 días de antigüedad",
      "params": {
        "days": 90
      }
    }
    ```

    **Casos de uso:**

    * Validar que una Constancia de Situación Fiscal tenga menos de 60 días
    * Verificar que un comprobante de domicilio sea reciente (menos de 90 días)
    * Confirmar que un estado de cuenta bancario sea actual
  </Accordion>

  <Accordion title="vr_trebol_entidad - Validar mención de entidad">
    Valida si un texto específico (nombre de persona, empresa, RFC, etc.) es mencionado en el documento.

    **Parámetros:**

    * `entity_name` (string): Texto que debe aparecer en el documento

    **Ejemplo de uso:**

    ```json theme={"dark"}
    {
      "id": "vr_trebol_entidad",
      "error_message": "El documento debe mencionar a ACME Corporation S.A. de C.V.",
      "params": {
        "entity_name": "ACME Corporation S.A. de C.V."
      }
    }
    ```

    **Casos de uso:**

    * Verificar que un documento pertenezca a una persona específica
    * Confirmar que el RFC coincida con el esperado
    * Validar que una empresa sea mencionada en el documento
  </Accordion>
</AccordionGroup>

### Estructura de una regla predefinida

Las reglas predefinidas usan una estructura simplificada:

* **`id`**: Debe comenzar con `vr_trebol_`
* **`error_message`**: Mensaje que Trébol devuelve si la validación falla
* **`params`**: Parámetros requeridos por la regla (vacío si la regla no tiene parámetros)
* **Campo prohibido**: `validation_rule` (NO lo incluyas en reglas predefinidas)

```json theme={"dark"}
{
  "id": "vr_trebol_antiguedad",
  "error_message": "La CSF debe tener menos de 60 días de antigüedad",
  "params": {
    "days": 60
  }
}
```

***

## Reglas personalizadas

Las reglas personalizadas requieren que definas tu propio prompt de validación. Útiles cuando necesitas validar algo que no está cubierto por las reglas predefinidas.

### Estructura de una regla personalizada

* **`id`**: Cualquier identificador personalizado
* **`validation_rule`**: Prompt que describe la condición a validar (Trébol lo interpreta con IA)
* **`error_message`**: Mensaje que Trébol devuelve si la validación falla

<Info>
  `validation_rule` es el prompt que Trébol interpreta para validar; `error_message` es el mensaje corto que se devuelve si la regla falla. Conviene escribirlos con propósitos distintos.
</Info>

```json theme={"dark"}
{
  "id": "mi_regla_personalizada",
  "validation_rule": "Verifica que el documento contenga un sello de agua visible en todas las páginas",
  "error_message": "El documento no tiene sello de agua visible"
}
```

***

## Comparación: predefinidas vs personalizadas

<Warning>
  **Importante:** No mezcles la estructura de reglas predefinidas con personalizadas en una misma regla. Cada tipo tiene campos específicos.
</Warning>

| Aspecto              | Reglas predefinidas | Reglas personalizadas |
| -------------------- | ------------------- | --------------------- |
| **id**               | `vr_trebol_*`       | Cualquier texto       |
| **error\_message**   | ✅ Requerido         | ✅ Requerido           |
| **validation\_rule** | ❌ No incluir        | ✅ Requerido           |
| **params**           | ✅ Requerido         | ❌ No incluir          |
| **Rendimiento**      | Optimizado          | Estándar              |

***

## Combinación de reglas

Puedes combinar múltiples reglas en un mismo `ruleset`, mezclando predefinidas y personalizadas:

```json theme={"dark"}
{
  "ruleset": [
    {
      "id": "vr_trebol_antiguedad",
      "error_message": "La CSF debe tener menos de 60 días de antigüedad",
      "params": {
        "days": 60
      }
    },
    {
      "id": "vr_trebol_entidad",
      "error_message": "El documento debe mencionar a ACME Corporation S.A. de C.V.",
      "params": {
        "entity_name": "ACME Corporation S.A. de C.V."
      }
    },
    {
      "id": "regla_personalizada_1",
      "validation_rule": "Verifica que el RFC siga el formato mexicano correcto (4 letras para persona moral o 3-4 para física, 6 dígitos de fecha, 3 caracteres de homoclave)",
      "error_message": "El RFC no tiene el formato correcto"
    }
  ]
}
```