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.

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.

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

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

​
Reglas disponibles

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

​
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)
{
  "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
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.
{
  "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

Importante: No mezcles la estructura de reglas predefinidas con personalizadas en una misma regla. Cada tipo tiene campos específicos.
AspectoReglas predefinidasReglas personalizadas
idvr_trebol_*Cualquier texto
error_message✅ Requerido✅ Requerido
validation_rule❌ No incluir✅ Requerido
params✅ Requerido❌ No incluir
RendimientoOptimizadoEstándar

​
Combinación de reglas

Puedes combinar múltiples reglas en un mismo ruleset, mezclando predefinidas y personalizadas: 
{
  "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"
    }
  ]
}