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

ÍtemDescripción
payroll_receiptRecibo de pago de nómina o pensión (Beta)
Ver detalle completo y estructura de respuesta en Items de Nómina.

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

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

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

​
Ejemplo de flujo completo

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.
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 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 para detalle de cada sección del flujo.

​
Consideraciones

Fase BetaEl item payroll_receipt está actualmente en fase Beta. La estructura de respuesta puede tener ajustes. Contáctanos en help@gotrebol.com si encuentras casos no cubiertos.
Múltiples recibos = múltiples itemsCada recibo debe enviarse como un item separado. La estructura de respuesta extrae los campos de cada recibo individualmente en el payload.receipts[].
País del payloadUsa 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.).

​
Siguientes pasos

Items de Nómina

Detalle de estructura de respuesta para payroll_receipt.

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.