> ## 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 — Nómina

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

Esta guía explica cómo crear verificaciones de **payroll lending** (créditos de nómina) 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?

Nómina permite verificar:

* **Ingresos laborales** (recibos de nómina)
* **Pensiones** (recibos de pago de pensión)
* **Historial de pagos** a un empleado o pensionado
* **Descuentos de ley** (salud, pensión, retención en la fuente)
* **Créditos y embargos** registrados en el comprobante

Trébol extrae de forma estructurada los campos clave del recibo: ingresos recurrentes y no recurrentes, descuentos, créditos, embargos e ingreso neto.

## Items aplicables

### Documentos específicos

| Ítem              | Descripción                                   |
| ----------------- | --------------------------------------------- |
| `payroll_receipt` | Recibo de pago de nómina o pensión (**Beta**) |

Ver detalle completo y estructura de respuesta en [Items de Nómina](/docs/guia-devs/uso-nomina/items).

### Items globales aplicables

Además del item específico de nómina, puedes usar items globales:

* `person_id` (identificación del empleado/pensionado)
* `proof_address` (comprobante de domicilio)
* `bank_statement` (estado de cuenta)
* `generic` (para clasificación automática)

<Note>
  El item `payroll_receipt` aplica a **cualquier país**. La estructura de respuesta incluye campos de identificación comunes a varios países (CC Colombia, RFC México, pasaporte, etc.).
</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": "co",
  "tag": "uuid-empleado-1234",
  "items": [
    {
      "type": "generic",
      "options": {
        "file_url": "https://www.ejemplo.com/recibo-nomina.pdf",
        "client_item_type": "payroll_receipt"
      }
    },
    {
      "type": "generic",
      "options": {
        "file_url": "https://www.ejemplo.com/cedula.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": "co",
  "tag": "uuid-empleado-validacion",
  "items": [
    {
      "type": "doc_validation",
      "options": {
        "file_url": "https://www.ejemplo.com/recibo-nomina.pdf",
        "client_item_type": "payroll_receipt",
        "ruleset": [
          {
            "id": "vr_trebol_entidad",
            "error_message": "El recibo debe estar a nombre de 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. `payroll_receipt`): Trébol extrae la información asumiendo que el documento es del tipo declarado. **No valida tipo ni reglas**.

```json theme={"dark"}
{
  "country": "co",
  "tag": "uuid-empleado-extraccion",
  "items": [
    {
      "type": "payroll_receipt",
      "options": {
        "file_url": "https://www.ejemplo.com/recibo-nomina.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 originación de crédito de nómina realista que combina las 3 formas de procesar documentos: recibo de nómina, identificación y estado de cuenta.

```json theme={"dark"}
{
  "country": "co",
  "tag": "uuid-empleado-completo",
  "friendly_name": "Juan Pérez",
  "items": [
    {
      "type": "generic",
      "options": {
        "file_url": "https://www.ejemplo.com/cedula.pdf"
      }
    },
    {
      "type": "doc_validation",
      "options": {
        "file_url": "https://www.ejemplo.com/recibo-nomina.pdf",
        "client_item_type": "payroll_receipt",
        "ruleset": [
          {
            "id": "vr_trebol_entidad",
            "error_message": "El recibo debe estar a nombre de Juan Pérez.",
            "params": {
              "entity_name": "Juan Pérez"
            }
          }
        ]
      }
    },
    {
      "type": "bank_statement",
      "options": {
        "file_url": "https://www.ejemplo.com/estado-cuenta.pdf"
      }
    }
  ],
  "metadata": {
    "custom_key": "custom_value"
  }
}
```

**Qué pasa en la verificación:**

* La **cédula** (`generic`) se clasifica automáticamente como `person_id` y se extrae su información.
* El **recibo de nómina** (`doc_validation`) se valida que sea un recibo de nómina y que esté a nombre de Juan Pérez. No se extrae información.
* El **estado de cuenta** (`bank_statement`) se extrae directamente como tipo conocido, sin validar tipo ni reglas.

***

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

Ejemplo de un flujo completo para payroll lending. Incluye el recibo de nómina como requerimiento obligatorio, identificación y estado de cuenta como opcionales con `conditional_render`, más un formulario para capturar datos adicionales del empleado.

<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 Crédito de Nómina",
  "id_slug": "onboarding-nomina-estandar",
  "country": "co",
  "record_validation_schema": {
    "version": 2,
    "requirements": {
      "doc_1": {
        "allowed_item_types": ["payroll_receipt"],
        "ui_options": {
          "label": "Recibo de nómina",
          "description": "Recibo de pago de nómina o pensión"
        },
        "validation_options": {
          "on_invalid_type_error": "invalidate"
        }
      }
    },
    "optional_requirements": {
      "doc_2": {
        "allowed_item_types": ["person_id"],
        "ui_options": {
          "label": "Identificación",
          "description": "Cédula, pasaporte u otro documento de identificación.",
          "conditional_render": true,
          "conditional_render_label": "¿Quieres adjuntar la identificación del empleado?"
        },
        "validation_options": {
          "on_invalid_type_error": "invalidate"
        }
      },
      "doc_3": {
        "allowed_item_types": ["bank_statement"],
        "ui_options": {
          "label": "Estado de cuenta",
          "description": "Estado de cuenta bancaria para validar depósitos de nómina.",
          "conditional_render": true,
          "conditional_render_label": "¿Quieres adjuntar el estado de cuenta del empleado?"
        },
        "validation_options": {
          "on_invalid_type_error": "invalidate"
        }
      }
    }
  },
  "flow_items": {
    "items": [
      {
        "type": "forms",
        "options": {
          "schema_id": "form-datos-empleado",
          "is_optional": false
        }
      }
    ],
    "options": {
      "creator_email": "creditos@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**

  El item `payroll_receipt` está 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>
  **Múltiples recibos = múltiples items**

  Cada recibo debe enviarse como un item separado. La estructura de respuesta extrae los campos de cada recibo individualmente en el `payload.receipts[]`.
</Note>

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

  Usa el campo `country` correspondiente al país del empleado/pensionado (ej: `co` para Colombia, `mx` para México). Esto afecta cómo Trébol interpreta algunos campos del recibo (moneda, tipo de ID, etc.).
</Note>

***

## Siguientes pasos

<CardGroup cols={2}>
  <Card title="Items de Nómina" href="/docs/guia-devs/uso-nomina/items">
    Detalle de estructura de respuesta para payroll\_receipt.
  </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>