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

# Overview — Hipotecas

> Guía end-to-end para crear verificaciones de mortgage underwriting: items aplicables, variaciones de creación con ejemplos de payload.

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](/docs/producto/como-funciona). 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.

| Ítem                   | Descripción                                          |
| ---------------------- | ---------------------------------------------------- |
| `property_deed`        | Escritura de compraventa de inmuebles (**Beta**)     |
| `lien_certificate`     | Certificado de gravámenes sobre inmuebles (**Beta**) |
| `property_tax_receipt` | Recibo de pago de impuesto predial (**Beta**)        |
| `property_appraisal`   | Avalúo de inmueble (**Beta**)                        |

Ver detalle completo y estructura de respuesta en [Items de Hipotecas](/docs/guia-devs/uso-hipotecas/items).

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

<Note>
  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.
</Note>

***

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

```json theme={"dark"}
{
  "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.

```json theme={"dark"}
{
  "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](/docs/guia-devs/crear-verificaciones/via-api/reglas-validacion).

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

```json theme={"dark"}
{
  "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](/docs/guia-devs/crear-verificaciones/via-api/forma-extraccion#combinar-con-validacion).

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

Caso de underwriting realista que combina las 3 formas de procesar documentos.

```json theme={"dark"}
{
  "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.

***

<h2 id="ejemplo-de-flujo-completo">
  Ejemplo de flujo completo
</h2>

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.

<Note>
  El `schema_id` del item `forms` se obtiene primero creando el esquema con [el endpoint de esquemas de formularios](https://docs.gotrebol.com/api-reference/gestión-de-esquemas-de-formularios/crear-nuevo-esquema-de-formulario). Ver detalle en [Items del flujo — forms](/docs/guia-devs/crear-verificaciones/via-widget/items#forms-formularios-personalizados).
</Note>

```json theme={"dark"}
{
  "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](/docs/guia-devs/crear-verificaciones/via-widget/crear-flujo) para detalle de cada sección del flujo.

***

## Consideraciones

<Note>
  **Fase Beta**

  Los items de hipotecas están actualmente en **fase Beta**. La estructura de respuesta puede tener ajustes. Contáctanos en [help@gotrebol.com](mailto:help@gotrebol.com) si encuentras casos no cubiertos.
</Note>

<Note>
  **País del payload**

  Usa 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.
</Note>

***

## Siguientes pasos

<CardGroup cols={2}>
  <Card title="Items de Hipotecas" href="/docs/guia-devs/uso-hipotecas/items">
    Detalle de estructura de respuesta para property\_deed, lien\_certificate, etc.
  </Card>

  <Card title="Cómo funciona Trébol" href="/docs/producto/como-funciona">
    Comparación de Aplicativo Web, widget, API sin/con flujo.
  </Card>

  <Card title="Estados de verificación" href="/docs/guia-devs/monitorear/estados-verificacion">
    Ciclo de vida de una verificación.
  </Card>
</CardGroup>