Items de Nómina

Este documento describe los items aplicables a verificaciones de payroll lending (créditos de nómina). Estos items pueden utilizarse en cualquier país y aplican para la validación de ingresos laborales y pensiones en procesos de originación de crédito. Para items generales de KYB (verificación de empresas), consulta las guías en Guías por caso de uso > KYB.

Tabla resumen

Ítem	Descripción
`payroll_receipt`	Recibo de pago de pensión o nómina de una persona. (Beta)

El item payroll_receipt se crea bajo el wrapper genérico document, especificando "type": "payroll_receipt" en el payload.

`payroll_receipt` — Recibo de nómina o pensión

Este ítem representa un recibo de pago de nómina o pensión. A continuación se detalla la estructura de datos extraída.

Descripción del Esquema

El objeto principal PaymentReceipt contiene la siguiente información estructurada:

informacion_emisor: Detalles de la entidad que emite el pago (nombre, ID fiscal).
informacion_empleado: Detalles del empleado (nombre, ID, tipo de ID).
informacion_pago: Detalles del periodo de pago (fecha emisión, periodo, inicio, fin, periodicidad, moneda).
ingresos: Detalle de ingresos recurrentes y no recurrentes, y el total.
creditos: Lista de créditos con entidad y monto de cuota.
embargos: Lista de embargos con tipo y monto.
descuentos: Descuentos de ley (salud, pensión, retención en la fuente) y otros descuentos detallados.
ingreso_neto_reportado: Ingreso neto explícitamente mencionado en el documento (si existe).
ingreso_neto_calculado: Ingreso neto calculado a partir de los ingresos y descuentos extraídos.

Estructura de respuesta

{
  "type": "payroll_receipt",
  "payload": {
    "tipo_comprobante": "desprendible_pago|resolucion_pension|ninguno",
    "tipo_pension": "invalidez|vejez|sustitucion|otro",
    "informacion_emisor": { "nombre_emisor": "...", "id_emisor": "..." },
    "informacion_empleado": {
      "nombre_empleado": "...",
      "id_empleado": "...",
      "tipo_id": "cc_co|ce_co|nit_co|ti_co|pasaporte|rfc_mx|curp_mx|nss_mx|otro",
      "numero_afiliacion": "..."
    },
    "informacion_pago": {
      "fecha_emision": "YYYY-MM-DD",
      "periodo": "YYYY-MM",
      "periodo_inicio": "YYYY-MM-DD",
      "periodo_fin": "YYYY-MM-DD",
      "periodicidad": "quincenal|mensual|semanal|otro",
      "moneda": "COP|MXN|USD|EUR|otro"
    },
    "ingresos": {
      "detalle_recurrentes": [{ "concepto": "...", "valor": 0 }],
      "detalle_no_recurrentes": [{ "concepto": "...", "valor": 0 }],
      "total_ingresos": 0
    },
    "creditos": {
      "detalle_creditos": [
        { "entidad": "...", "valor": 0, "cuotas_totales": 0 }
      ]
    },
    "embargos": {
      "detalle_embargos": [
        { "tipo_embargo": "alimentos|civil|fiscal|financiero|otro", "valor": 0 }
      ]
    },
    "descuentos": {
      "salud": 0,
      "pension": 0,
      "retencion_fuente": 0,
      "otros_descuentos": [{ "concepto": "...", "valor": 0 }]
    },
    "ingreso_neto_reportado": 0
  }
}

Ejemplo completo de item

{
  "id": 99999,
  "item_order": 0,
  "item_status": "complete",
  "item_type": "document",
  "item_internal_status": "finish_extraction",
  "item_value": {
    "type": "payroll_receipt",
    "payload": {
      "metadata": {
        "file_type": "application/pdf",
        "error_count": 0,
        "processed_at": "YYYY-MM-DDTHH:MM:SS.ffffff",
        "success_count": 1,
        "total_pages_processed": 1
      },
      "receipts": [
        {
          "creditos": {
            "detalle_creditos": [
              { "valor": 1000.0, "entidad": "ENTIDAD_A" },
              { "valor": 200.0, "entidad": "ENTIDAD_B" }
            ]
          },
          "embargos": {
            "detalle_embargos": [{ "valor": 500.0, "tipo_embargo": "otro" }]
          },
          "ingresos": {
            "total_ingresos": 5000.0,
            "detalle_recurrentes": [
              { "valor": 4000.0, "concepto": "SUELDO BASICO" }
            ],
            "detalle_no_recurrentes": [
              { "valor": 150.0, "concepto": "BONO_A" },
              { "valor": 100.0, "concepto": "BONO_B" },
              { "valor": 400.0, "concepto": "PRIMA_X" },
              { "valor": 200.0, "concepto": "PRIMA_Y" },
              { "valor": 150.0, "concepto": "PRIMA_Z" }
            ]
          },
          "descuentos": {
            "salud": 150.0,
            "pension": 40.0,
            "otros_descuentos": [
              { "valor": 10.0, "concepto": "OTRO_DESCUENTO" }
            ],
            "retencion_fuente": 0
          },
          "informacion_pago": {
            "moneda": "COP",
            "periodo": "YYYY-MM",
            "periodo_fin": "YYYY-MM-DD",
            "periodicidad": "mensual",
            "fecha_emision": "YYYY-MM-DD",
            "periodo_inicio": "YYYY-MM-DD"
          },
          "receipt_metadata": {
            "end_page": 0,
            "start_page": 0,
            "receipt_metadata": 1,
            "extraction_status": "success"
          },
          "informacion_emisor": {
            "id_emisor": "NIT_EMISOR_EJEMPLO",
            "nombre_emisor": "EMPRESA_EJEMPLO"
          },
          "informacion_empleado": {
            "tipo_id": "otro",
            "id_empleado": "ID_EMPLEADO_EJEMPLO",
            "nombre_empleado": "NOMBRE APELLIDO"
          },
          "ingreso_neto_calculado": 3000.0,
          "ingreso_neto_reportado": 2000.0
        }
      ],
      "num_receipts": 1,
      "internalStatus": "comprehend_completed"
    }
  },
  "validation_result": null,
  "user_event_name": null,
  "user_event_reason": null,
  "tag": null,
  "item_scope": "advanced",
  "original_file_url": "..."
}

​Tabla resumen

​payroll_receipt — Recibo de nómina o pensión

​Descripción del Esquema

​Estructura de respuesta

​Ejemplo completo de item

Tabla resumen

`payroll_receipt` — Recibo de nómina o pensión

Descripción del Esquema

Estructura de respuesta

Ejemplo completo de item