Payslip

The payroll voucher with earnings, deductions and net pay in five color designs, optionally protected with a password.

colilla-de-nomina: what a person was paid in a period, what was deducted and how much they receive. It reads like a payroll voucher, not an invoice: the title «COMPROBANTE DE NÓMINA», the data in three groups —Empleado (employee) at full width and below it Periodo (period) and Pago (payment) side by side—, earnings and deductions in two columns with their totals, the net pay highlighted with its amount in words, and at the end a legend and the signatures.

Designs

It has five designs, the same payslip in five colors:

plantilla	Color
azul	Blue —the default—
esmeralda	Emerald green
violeta	Violet
grafito	Graphite gray, the most understated
ambar	Amber

premium is the former name of grafito and is still accepted: whoever already sends it gets the new payslip in gray, without changing anything. If you don’t send plantilla, you get azul. All five support styling with the color scheme, like the rest of the family.

The body

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

• The employee’s ID goes in two fields: empleado.tipoDocumento —CC, NIT, CE, whatever applies— and empleado.numeroDocumento. They are printed together, «CC 1037000001», exactly as they arrive. empleado.documento, with type and number in a single text, still works for printing —it is used when the two separate fields don’t arrive—, but with it the payslip cannot be password-protected.
• Required: empleado.nombre, periodo.desde, periodo.hasta, devengados and deducciones (lists, may be empty) and totales.devengado, totales.deducido and totales.neto. If any is missing, the response is a 400 with faltan, the list of what is missing, and nothing is composed. A total of 0 is not missing.
• Nothing is calculated here. Totals are not the sum of the lines, nor is the net the difference: they are printed as they arrive.
• Everything else is optional, and whatever doesn’t arrive takes up no row.
• The Empleado card goes at full width, with its data in two columns. Below it, Periodo and Pago take half a row each; without pago there is no Pago card, and Periodo takes the whole row.
• Dates in AAAA-MM-DD (YYYY-MM-DD) form are printed «01 oct 2026»: the day with two digits, the month abbreviated in lowercase (in Spanish) without a period, and the year. This applies to periodo.desde, periodo.hasta, periodo.fechaPago and empleado.fechaIngreso; the period reads «01 oct 2026 – 15 oct 2026». A date that arrives in another form —«31/10/2026», «Fin de mes», or with a time— is printed as it arrives.
• sideNotes (optional) is the margin text, as on the invoice: a list of texts written top to bottom in the left margin of every page, outside the body and the footer. Without it, the margin stays blank; none is added here on its own.
• nominaElectronica.estado:
  • "validada" prints «Nómina electrónica N.º …» and the CUNE, and the QR if you send qr with its content —the verification URL is not built here—. Without a number or without a CUNE, it says so.
  • Without nominaElectronica, or with any other status —"simulacion" included—, the payslip comes out unmarked. The simulation band no longer exists.
• leyenda (optional) is the text that closes the payslip, and it is printed exactly as it arrives: if it must cite a regulation, you cite it; none is added here. Without it, a neutral one: «Este comprobante detalla los valores devengados y deducidos en el periodo indicado. Consérvelo como soporte de su pago.»
• firmas (optional) is a list of { rol, nombre, documento }, two by two side by side: the line to sign on and below it the name and document if they arrive, and the role. Without it, Empleador (employer) and Recibí conforme (empleado) (received in agreement, employee), with no name, to be signed by hand. With [], none.
• The two columns paginate together, side by side: a settlement with many entries continues on the next page, and the totals and the net pay never start a page alone. Neither do the legend and the signatures: they stay with the last box above them —notes, payment or validated payroll— or, if there is none, with the net pay, and move together to the next page if they don’t fit.
• The file is named ColillaNomina_<periodo.numero>.pdf, without accents or spaces (ColillaNomina_Nomina-2026-10.pdf), or ColillaNomina_sin-periodo.pdf if the number doesn’t arrive.

Examples: colilla-de-nomina.json and, with integral salary, colilla-de-nomina-integral.json.

Password-protected payslips

A payslip carries personal and financial data, and it travels by email or WhatsApp, where it gets forwarded. You can request it encrypted with a password by adding cifrar: true next to type and data:

{
  "type": "colilla-de-nomina",
  "plantilla": "azul",
  "cifrar": true,
  "data": {
    "empleado": { "nombre": "Valentina Ospina Cardona", "tipoDocumento": "CC", "numeroDocumento": "1037000001" }
    // … the rest of the payslip
  }
}

The password is empleado.numeroDocumento, exactly as you send it. It is not interpreted or corrected here: if you send "1.037.000.001", the password includes the dots; if you send "CC 1037000001", the password is «CC 1037000001». Send it the way the employee types it —almost always just the number, without dots—; that is on your side. No key is invented or stored here.

It is only protected with empleado.tipoDocumento CC or NIT, written exactly like that, in uppercase. empleado.documento, the field with type and number together, cannot be used for protection.

The example colilla-de-nomina-cifrada.json opens with 1037000001.

• cifrar is true or false. Without it, or with false, the payslip comes out as always.
• The encrypted response carries the x-docgen-cifrado: true header. Unencrypted, it doesn’t.
• AES-256 encryption (PDF 1.7, extension level 3). Any current reader asks for the password on opening, and with it the payslip is the same: the same text and the same pages.
• It carries no permissions —blocking printing or copying—: viewers honor them as a courtesy and any tool bypasses them.
• The password is not written to any log and is not returned in any response.

A payslip that was requested protected never comes out open. These cases respond 400, with an error that says so, and no PDF:

Case	error
cifrar: true on another document type	«Solo las colillas de nómina se pueden proteger con contraseña.»
empleado.tipoDocumento or empleado.numeroDocumento is missing, or the number arrives empty or is neither text nor number —also if only empleado.documento arrives—	«Para proteger la colilla hacen falta empleado.tipoDocumento (CC o NIT) y empleado.numeroDocumento.»
empleado.tipoDocumento is neither CC nor NIT	«empleado.tipoDocumento debe ser CC o NIT para proteger la colilla.»
cifrar is neither true nor false ("true", in quotes, is not valid)	«cifrar tiene que ser true o false, sin comillas.»