Colilla de nómina

Lo devengado, lo deducido y el neto de una persona en un periodo, en cinco colores y con opción de contraseña.

colilla-de-nomina: qué se le pagó a una persona en un periodo, qué se le descontó y cuánto recibe. Se lee como un comprobante de nómina y no como una factura: el título «COMPROBANTE DE NÓMINA», los datos en tres grupos —Empleado a todo el ancho y debajo Periodo y Pago lado a lado—, los devengados y las deducciones en dos columnas con sus totales, el neto destacado con su valor en letras, y al final una leyenda y las firmas.

Diseños

Tiene cinco diseños, la misma colilla en cinco colores:

plantilla	Color
azul	Azul —el de defecto—
esmeralda	Verde esmeralda
violeta	Violeta
grafito	Gris grafito, el más sobrio
ambar	Ámbar

premium es el nombre anterior de grafito y se sigue aceptando: quien ya lo manda recibe la colilla nueva en gris, sin cambiar nada. Si no manda plantilla, recibe azul. Los cinco admiten estilo con el esquema de color, como el resto de la familia.

Los datos

"empleado": { "nombre": "Valentina Ospina Cardona", "tipoDocumento": "CC", "numeroDocumento": "1037000001", "cargo": "Cajera",
  "sucursal": "El Poblado", "salarioBase": 2100000, "contrato": "Término indefinido", "fechaIngreso": "2023-03-01" },
"periodo": { "numero": "Nómina 2026-10", "desde": "2026-10-01", "hasta": "2026-10-31", "fechaPago": "2026-10-31",
  "diasTrabajados": 15, "diasVacaciones": 15, "diasAusencia": 0 },
"devengados": [ { "concepto": "Sueldo", "detalle": "15 días", "valor": 1050000 } ],
"deducciones": [ { "concepto": "Salud", "detalle": "4 %", "valor": 90290 } ],
"totales": { "devengado": 2457250, "deducido": 230580, "neto": 2226670 },
"pago": { "medio": "Transferencia bancaria", "banco": "Bancolombia", "cuenta": "Ahorros ****8901" },
"nominaElectronica": { "estado": "validada", "numero": "NE-002184", "cune": "…", "qr": "…" },
"notes": "…",
"paymentLegend": "…",
"leyenda": "Este comprobante detalla los valores devengados y deducidos en el periodo indicado. …",
"firmas": [ { "rol": "Empleador", "nombre": "Carolina Mejía Duque", "documento": "Directora de Gestión Humana" },
  { "rol": "Recibí conforme (empleado)" } ],
"sideNotes": [ "Generado mediante software MiDivisa by Piensa IT S.A.S." ]

• La identificación del empleado va en dos campos: empleado.tipoDocumento —CC, NIT, CE, lo que corresponda— y empleado.numeroDocumento. Se imprimen juntos, «CC 1037000001», tal como llegan. empleado.documento, con tipo y número en un solo texto, sigue funcionando para imprimir —se usa cuando no llegan los dos separados—, pero con él la colilla no se puede proteger con contraseña.
• Obligatorios: empleado.nombre, periodo.desde, periodo.hasta, devengados y deducciones (listas, pueden ir vacías) y totales.devengado, totales.deducido y totales.neto. Si falta alguno, la respuesta es un 400 con faltan, la lista de lo que falta, y no se compone nada. Un total en 0 no falta.
• Nada se calcula aquí. Los totales no son la suma de las líneas ni el neto la resta: se imprimen como llegan.
• Lo demás es opcional, y lo que no llega no ocupa renglón.
• La tarjeta del Empleado va a todo el ancho, con sus datos en dos columnas. Debajo, Periodo y Pago a media fila cada una; sin pago no hay tarjeta de Pago, y el Periodo ocupa toda la fila.
• Las fechas AAAA-MM-DD se imprimen «01 oct 2026»: el día con dos cifras, el mes abreviado en minúscula y sin punto, y el año. Vale para periodo.desde, periodo.hasta, periodo.fechaPago y empleado.fechaIngreso; el periodo se lee «01 oct 2026 – 15 oct 2026». Una fecha que llegue en otra forma —«31/10/2026», «Fin de mes», o con hora— se imprime tal como llega.
• sideNotes (opcional) es el texto del margen, como en la factura: una lista de textos escritos de arriba abajo en el margen izquierdo de cada hoja, fuera del cuerpo y del pie. Sin él, el margen queda en blanco; aquí no se añade ninguno por su cuenta.
• nominaElectronica.estado:
  • "validada" imprime «Nómina electrónica N.º …» y el CUNE, y el QR si manda qr con su contenido —aquí no se arma la URL de verificación—. Sin número o sin CUNE, lo dice.
  • Sin nominaElectronica, o con cualquier otro estado —"simulacion" incluido—, sale la colilla sin marca. La franja de simulación ya no existe.
• leyenda (opcional) es el texto que cierra la colilla, y se imprime tal como llega: si debe citar una norma, cítela usted, aquí no se añade ninguna. Sin ella, una neutra: «Este comprobante detalla los valores devengados y deducidos en el periodo indicado. Consérvelo como soporte de su pago.»
• firmas (opcional) es una lista de { rol, nombre, documento }, de dos en dos lado a lado: la raya para firmar y debajo el nombre y el documento si llegan, y el rol. Sin ella, Empleador y Recibí conforme (empleado), sin nombre, para firmar a mano. Con [], ninguna.
• Las dos columnas paginan juntas, lado a lado: una liquidación con muchas novedades sigue en la hoja siguiente, y los totales y el neto nunca empiezan una hoja solos. La leyenda y las firmas tampoco: van con la última caja que haya encima —observaciones, pago o nómina validada— o, sin ninguna, con el neto, y pasan juntas a la hoja siguiente si no caben.
• El archivo se llama ColillaNomina_<periodo.numero>.pdf, sin tildes ni espacios (ColillaNomina_Nomina-2026-10.pdf), o ColillaNomina_sin-periodo.pdf si no llega el número.

Ejemplos: colilla-de-nomina.json y, con salario integral, colilla-de-nomina-integral.json.

Colillas de nómina protegidas con contraseña

Una colilla de nómina lleva datos personales y financieros, y viaja por correo o por WhatsApp, donde se reenvía. Puede pedirla cifrada con contraseña añadiendo cifrar: true junto a type y data:

{
  "type": "colilla-de-nomina",
  "plantilla": "azul",
  "cifrar": true,
  "data": {
    "empleado": { "nombre": "Valentina Ospina Cardona", "tipoDocumento": "CC", "numeroDocumento": "1037000001" }
    // … el resto de la colilla
  }
}

La contraseña es empleado.numeroDocumento, exactamente como lo manda. Aquí no se interpreta ni se corrige: si manda "1.037.000.001", la contraseña lleva los puntos; si manda "CC 1037000001", la contraseña es «CC 1037000001». Mándelo en la forma en que el empleado lo escribe —casi siempre el número solo, sin puntos—; eso queda de su lado. Aquí no se inventa ni se guarda ninguna clave.

Solo se protege con empleado.tipoDocumento CC o NIT, escrito así, en mayúsculas. empleado.documento, el campo con tipo y número juntos, no sirve para proteger.

El ejemplo colilla-de-nomina-cifrada.json abre con 1037000001.

• cifrar es true o false. Sin él, o con false, la colilla sale como siempre.
• La respuesta cifrada lleva la cabecera x-docgen-cifrado: true. Sin cifrar, no la lleva.
• Cifrado AES-256 (PDF 1.7, extensión 3). Cualquier lector actual pide la contraseña al abrir, y con ella la colilla es la misma: el mismo texto y las mismas hojas.
• No lleva permisos —bloquear la impresión o la copia—: los visores los respetan por cortesía y cualquier herramienta se los salta.
• La contraseña no se escribe en ningún registro ni vuelve en ninguna respuesta.

Nunca sale abierta una colilla que se pidió proteger. Estos casos responden 400, con un error que lo dice, y sin PDF:

Caso	error
cifrar: true en otro tipo de documento	«Solo las colillas de nómina se pueden proteger con contraseña.»
Falta empleado.tipoDocumento o empleado.numeroDocumento, o el número llega vacío o no es texto ni número —también si solo llega empleado.documento—	«Para proteger la colilla hacen falta empleado.tipoDocumento (CC o NIT) y empleado.numeroDocumento.»
empleado.tipoDocumento no es CC ni NIT	«empleado.tipoDocumento debe ser CC o NIT para proteger la colilla.»
cifrar no es true ni false ("true", entre comillas, no vale)	«cifrar tiene que ser true o false, sin comillas.»