Skip to main content

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.

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
Esta forma solo valida — no extrae los datos del documento. Si además necesitas extraer información, consulta Forma 3: Extracción.

​
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"
      }
    }
  ]
}
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.
  • 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

Trébol devuelve un item completo con el resultado de cada regla y la validación del tipo: 
{
  "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.

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