Forma 2: Validación

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

• 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

​

Payload

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

• 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.
• file_url (string, opcional): URL del documento. Si no incluyes file_url, Trébol devuelve una upload_url para carga directa. Ver Carga directa.

​

Resultado

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

• 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

​

Combinar con extracción

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

​

Siguientes pasos

• Webhooks — para recibir el resultado de la validación
• Estados de verificación — cómo monitorear el progreso