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

# Forma 2: Validación

> Valida que un documento sea del tipo esperado y cumpla reglas específicas usando el item doc_validation.

En esta forma, usas un item de tipo `doc_validation` para que Trébol verifique que el documento cargado cumple con ciertos criterios:

1. **Que sea del tipo esperado** (ej: confirma que el documento es una Constancia de Situación Fiscal si tú esperas una CSF)
2. **Que cumpla las reglas que definas** (antigüedad, mención de entidad, vigencia, etc.)

**Cuándo usar:**

* Sabes qué tipo de documento esperas (ej: una CSF, un acta constitutiva, un comprobante de domicilio)
* Quieres verificar criterios antes de procesar (ej: que no tenga más de 60 días)
* Quieres tomar una decisión en tu backend basada en si el documento es válido

## Cómo funciona

1. Envías el item con `type: "doc_validation"`, el `file_url`, el `client_item_type` esperado y un `ruleset`
2. Trébol valida que el documento sea del tipo esperado y que cumpla todas las reglas
3. El resultado incluye: si es del tipo correcto, si cada regla pasó o falló, y los motivos

<Info>
  Esta forma **solo valida** — no extrae los datos del documento. Si además necesitas extraer información, consulta [Forma 3: Extracción](/docs/guia-devs/crear-verificaciones/via-api/forma-extraccion).
</Info>

## Payload

```json theme={"dark"}
{
  "country": "mx",
  "tag": "uuid-cliente-1234",
  "items": [
    {
      "type": "doc_validation",
      "options": {
        "file_url": "https://www.ejemplo.com/documento.pdf",
        "client_item_type": "csf_mx",
        "ruleset": [
          {
            "id": "vr_trebol_antiguedad",
            "error_message": "El documento debe tener menos de 60 días de antigüedad",
            "params": { "days": 60 }
          }
        ]
      },
      "tags": {
        "internal_id": "csf-validation-001"
      }
    }
  ]
}
```

**Campos clave:**

* `client_item_type` (string, requerido): tipo de documento esperado (ej: `csf_mx`, `ac_mx`, `rut_co`). Trébol verifica que el archivo sea de este tipo.
* `ruleset` (array, opcional): lista de reglas de validación a aplicar. Ver [Reglas de validación](/docs/guia-devs/crear-verificaciones/via-api/reglas-validacion).
* `file_url` (string, opcional): URL del documento. Si no incluyes `file_url`, Trébol devuelve una `upload_url` para carga directa. Ver [Carga directa](/docs/guia-devs/crear-verificaciones/via-api/carga-directa).

## Resultado

Trébol devuelve un item completo con el resultado de cada regla y la validación del tipo:

```json theme={"dark"}
{
  "id": 12345,
  "item_type": "doc_validation",
  "item_status": "complete",
  "item_internal_status": "validation_completed",
  "item_value": {
    "item_type_validation_result": [
      {
        "validation_result": true,
        "reason": "El documento es una CSF mexicana porque está titulado 'Constancia de Situación Fiscal' y contiene elementos clave como RFC, nombre, domicilio fiscal, actividades económicas, regímenes, obligaciones y un sello digital, todos emitidos por el SAT."
      }
    ],
    "rules_validation_result": [
      {
        "id": "vr_trebol_antiguedad",
        "validation_rule": "El documento debe tener menos de 60 días de antigüedad",
        "variable_value": "2024-05-13",
        "validation_result": true
      }
    ],
    "log": {
      "item_type_validated_at": "2025-09-16T18:54:38.694Z",
      "rules_validated_at": "2025-09-16T18:54:38.694Z"
    }
  }
}
```

**Campos clave del resultado:**

* `item_type_validation_result`: si el documento es del tipo esperado. Incluye `validation_result` (true/false) y `reason`.
* `rules_validation_result`: un resultado por cada regla del `ruleset`. Incluye el valor extraído (`variable_value`) y si pasó (`validation_result: true`).

## Reglas de validación

Para detalle de reglas predefinidas (`vr_trebol_*`) y personalizadas, consulta [Reglas de validación](/docs/guia-devs/crear-verificaciones/via-api/reglas-validacion).

## Combinar con extracción

Si después de validar quieres extraer la información del documento (por ejemplo: validaste que era una CSF válida y ahora quieres obtener el RFC, domicilio, etc.), combina esta forma con [Forma 3: Extracción](/docs/guia-devs/crear-verificaciones/via-api/forma-extraccion).

El flujo es:

1. Crea un item `doc_validation` (Forma 2)
2. Espera el resultado (via webhook o polling)
3. Si `item_type_validation_result.validation_result` es `true` y todas las reglas pasaron, agrega un item con tipo directo (Forma 3) usando el endpoint `PUT /verifications/{id}/add-items`
4. Espera el resultado de la extracción

Esta lógica condicional la construyes tú en tu backend; Trébol no la ejecuta automáticamente.

## Siguientes pasos

* [Webhooks](/docs/guia-devs/webhooks) — para recibir el resultado de la validación
* [Estados de verificación](/docs/guia-devs/monitorear/estados-verificacion) — cómo monitorear el progreso