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.

Esta guía explica cómo crear verificaciones de mortgage underwriting (hipotecas) usando Trébol. Incluye los items aplicables, variaciones de creación con ejemplos de payload copy-pasteables, y consideraciones específicas. Para entender el método de creación a usar (Aplicativo Web, widget, API sin flujo, API con flujo), consulta Cómo funciona Trébol. Esta guía asume creación vía API.

​
¿Qué puedes verificar?

Hipotecas permite verificar:
  • Titularidad de inmuebles mediante escrituras de compraventa
  • Gravámenes (hipotecas, embargos) sobre un inmueble
  • Pago de impuesto predial (situación fiscal del inmueble)
  • Valor del inmueble mediante avalúos oficiales
Trébol automatiza la extracción de información de los documentos oficiales de propiedad.

​
Items aplicables

​
Documentos específicos

Items orientados a la validación de inmuebles.
ÍtemDescripción
property_deedEscritura de compraventa de inmuebles (Beta)
lien_certificateCertificado de gravámenes sobre inmuebles (Beta)
property_tax_receiptRecibo de pago de impuesto predial (Beta)
property_appraisalAvalúo de inmueble (Beta)
Ver detalle completo y estructura de respuesta en Items de Hipotecas.

​
Items globales aplicables

Además de los específicos de hipotecas, puedes usar items globales:
  • person_id (identificación del propietario)
  • proof_address (comprobante de domicilio)
  • bank_statement (estado de cuenta)
  • generic (para clasificación automática)
Los items de hipotecas aplican a cualquier país (son genéricos en país pero específicos en propósito). El formato de respuesta incluye campos mexicanos (CURP, RFC) y genéricos.

​
Variaciones de creación

Cada variación incluye un ejemplo de payload completo copy-pasteable.

​
1. Con documentos: clasificación automática + extracción

Verificación que incluye documentos para que Trébol clasifique automáticamente y extraiga la información. Usa items de tipo generic. El campo client_item_type es opcional: si lo defines, ayudas al clasificador con un hint del tipo esperado; si lo omites, Trébol detecta el tipo por sí solo. 
{
  "country": "mx",
  "tag": "uuid-inmueble-1234",
  "items": [
    {
      "type": "generic",
      "options": {
        "file_url": "https://www.ejemplo.com/escritura.pdf",
        "client_item_type": "property_deed"
      }
    },
    {
      "type": "generic",
      "options": {
        "file_url": "https://www.ejemplo.com/certificado-gravamenes.pdf"
      }
    }
  ]
}

​
2. Con tipo conocido: solo validación o solo extracción

Cuando ya sabes qué tipo de documento te entregan, puedes saltarte la clasificación. Hay dos sub-casos: 2.a — Solo validación (item doc_validation): Trébol verifica que el archivo coincida con el tipo declarado y cumpla las reglas que configures. No extrae información. El campo client_item_type es obligatorio porque define contra qué tipo se compara. 
{
  "country": "mx",
  "tag": "uuid-inmueble-validacion",
  "items": [
    {
      "type": "doc_validation",
      "options": {
        "file_url": "https://www.ejemplo.com/escritura.pdf",
        "client_item_type": "property_deed",
        "ruleset": [
          {
            "id": "vr_trebol_entidad",
            "error_message": "La escritura debe mencionar al titular Juan Pérez.",
            "params": {
              "entity_name": "Juan Pérez"
            }
          }
        ]
      }
    }
  ]
}
ruleset es opcional. Para el catálogo completo de reglas predefinidas (vr_trebol_*) y cómo armar reglas personalizadas, ver Reglas de validación. 2.b — Solo extracción (tipo directo, ej. lien_certificate): Trébol extrae la información asumiendo que el documento es del tipo declarado. No valida tipo ni reglas. 
{
  "country": "mx",
  "tag": "uuid-inmueble-extraccion",
  "items": [
    {
      "type": "lien_certificate",
      "options": {
        "file_url": "https://www.ejemplo.com/certificado-gravamenes.pdf"
      }
    }
  ]
}
Si quieres validar y extraer, ver Combinar Validación + Extracción.

​
3. Combinación completa (las 3 formas en una verificación)

Caso de underwriting realista que combina las 3 formas de procesar documentos. 
{
  "country": "mx",
  "tag": "uuid-inmueble-completo",
  "friendly_name": "Inmueble Av. Reforma 123",
  "items": [
    {
      "type": "generic",
      "options": {
        "file_url": "https://www.ejemplo.com/avaluo.pdf"
      }
    },
    {
      "type": "doc_validation",
      "options": {
        "file_url": "https://www.ejemplo.com/escritura.pdf",
        "client_item_type": "property_deed",
        "ruleset": [
          {
            "id": "vr_trebol_entidad",
            "error_message": "La escritura debe mencionar al titular Juan Pérez.",
            "params": {
              "entity_name": "Juan Pérez"
            }
          }
        ]
      }
    },
    {
      "type": "lien_certificate",
      "options": {
        "file_url": "https://www.ejemplo.com/certificado-gravamenes.pdf"
      }
    },
    {
      "type": "property_tax_receipt",
      "options": {
        "file_url": "https://www.ejemplo.com/recibo-predial.pdf"
      }
    }
  ],
  "metadata": {
    "custom_key": "custom_value"
  }
}
Qué pasa en la verificación:
  • El avalúo (generic) se clasifica automáticamente y se extrae su información.
  • La escritura (doc_validation) se valida que sea del tipo esperado y que mencione al titular Juan Pérez. No se extrae información.
  • El certificado de gravámenes y el recibo predial (tipos directos) se extraen directamente, sin validar tipo ni reglas.

​
Ejemplo de flujo completo

Ejemplo de un flujo completo para underwriting hipotecario. Incluye escritura y certificado de gravámenes como obligatorios; recibo predial y avalúo como opcionales con conditional_render; y un formulario para capturar datos del crédito.
El schema_id del item forms se obtiene primero creando el esquema con el endpoint de esquemas de formularios. Ver detalle en Items del flujo — forms.
{
  "friendly_name": "Onboarding Hipoteca - Validación Inmueble",
  "id_slug": "onboarding-hipoteca-estandar",
  "country": "mx",
  "record_validation_schema": {
    "version": 2,
    "requirements": {
      "doc_1": {
        "allowed_item_types": ["property_deed"],
        "ui_options": {
          "label": "Escritura de compraventa",
          "description": "Escritura pública del inmueble"
        },
        "validation_options": {
          "on_invalid_type_error": "invalidate"
        }
      },
      "doc_2": {
        "allowed_item_types": ["lien_certificate"],
        "ui_options": {
          "label": "Certificado de gravámenes",
          "description": "Certificado de libertad de gravámenes del inmueble"
        },
        "validation_options": {
          "on_invalid_type_error": "invalidate"
        }
      }
    },
    "optional_requirements": {
      "doc_3": {
        "allowed_item_types": ["property_tax_receipt"],
        "ui_options": {
          "label": "Recibo predial",
          "description": "Recibo de pago de impuesto predial del inmueble.",
          "conditional_render": true,
          "conditional_render_label": "¿Quieres adjuntar el recibo de predial del inmueble?"
        },
        "validation_options": {
          "on_invalid_type_error": "invalidate"
        }
      },
      "doc_4": {
        "allowed_item_types": ["property_appraisal"],
        "ui_options": {
          "label": "Avalúo",
          "description": "Avalúo oficial del inmueble.",
          "conditional_render": true,
          "conditional_render_label": "¿Quieres adjuntar el avalúo del inmueble?"
        },
        "validation_options": {
          "on_invalid_type_error": "invalidate"
        }
      }
    }
  },
  "flow_items": {
    "items": [
      {
        "type": "forms",
        "options": {
          "schema_id": "form-datos-credito",
          "is_optional": false
        }
      }
    ],
    "options": {
      "creator_email": "underwriting@tuempresa.com"
    }
  }
}
Ver Crear el flujo para detalle de cada sección del flujo.

​
Consideraciones

Fase BetaLos items de hipotecas están actualmente en fase Beta. La estructura de respuesta puede tener ajustes. Contáctanos en help@gotrebol.com si encuentras casos no cubiertos.
País del payloadUsa el campo country correspondiente al país donde se encuentra el inmueble (ej: mx para inmuebles en México). Esto afecta cómo Trébol interpreta algunos campos del documento.

​
Siguientes pasos

Items de Hipotecas

Detalle de estructura de respuesta para property_deed, lien_certificate, etc.

Cómo funciona Trébol

Comparación de Aplicativo Web, widget, API sin/con flujo.

Estados de verificación

Ciclo de vida de una verificación.