Choosing the design

Pick a design with plantilla, including the 80 mm POS receipts, list the available designs from the catalog and track the style each document used.

The same document can come out with different designs. You request one with plantilla, next to the type:

{
  "type": "factura",
  "plantilla": "premium",
  "data": { }
}

For the invoice there are seventeen: estandar —the default—, premium, destacada —a color band running edge to edge with the parties and the table mounted on it—, seven with the Premium structure in another color: moderna, clasica, minimalista, profesional, corporativa, serena and basica, and seven POS receipts. They all read the same data, so changing design means changing one word.

POS receipts

The receipts (tirillas) are the electronic sales invoice for the point-of-sale printer: an 80 mm wide roll, in a single strip as long as its content —it is not cut into pages, whether it has 3 items or 30— and printed in black only, with no colors or gray backgrounds —in some designs, with white text on black bands—, because they come out of a thermal printer.

They take the same body as any other invoice and say the same things, in one column: regime, numbering authorization, rate per line, totals, amount in words, payment, fields, legal notes, CUFE, QR, resolution and software manufacturer. The sideNotes text goes at the end, in upright lines, because a roll has no margin. The logo is drawn exactly as it arrives: if the printer is thermal, it is best to send it in black and white.

For a counter sale, also send the term and the due date (payment.term: "Contado", invoice.paymentDate with the day’s date): the receipt says what is missing, and without them it prints «Sin plazo» (“No term”) and «Sin vencimiento» (“No due date”).

There are seven, and choosing one means changing only plantilla. Since a thermal printer prints in a single color, they are told apart by typeface, rules, boxes and black bands, and what you see on screen is what gets printed.

plantilla	What it looks like
tirilla	Premium: understated, with dashed rules between blocks
tirilla-destacada	The total in a black bar with white text and the header between two thick rules
tirilla-clasica	All in Courier, like the classic cash register
tirilla-minimalista	No rules, more space between blocks and small labels
tirilla-corporativa	Each block in its own solid-bordered box
tirilla-moderna	Section labels in uppercase on black bands, and a large total
tirilla-estandar	Compact: the shortest on paper, for high volume

The other documents

For now:

Type	Designs
nota-credito	premium
nota-debito	premium
recibo-de-caja	estandar —the default— and premium
estado-de-cuenta	premium
colilla-de-nomina	azul —the default—, esmeralda, violeta, grafito and ambar; premium, the former name of grafito
informe	premium
entrada-de-inventario, salida-de-inventario, traslado-de-inventario	premium
cuenta-de-cobro	estandar (the default), media-carta and con-aviso, and all three in every palette: moderna, moderna-media-carta, moderna-con-aviso, and the same with clasica, minimalista and corporativa; plus destacada, destacada-media-carta and destacada-con-aviso
cotizacion, pedido, requisicion, orden-de-compra, factura-de-compra, documento-equivalente, anticipo, comprobante-de-egreso, contrato	estandar

The credit note, the debit note, the Premium cash receipt, the account statement, the report, the inventory movements and every Standard document —payment request, quote, sales order, requisition, purchase order, purchase invoice, equivalent document, advance payment and payment voucher— share the look of the Premium invoice: the same header with its logo, the same block with the customer and the document data, the same table, the same margin and the footer in the same place. That way, everything a company issues looks like one family.

The Standard documents close like the invoice: the amount in words, the payment-details box and, next to it, the QR code. In them the QR is not the DIAN verification one —they are not electronic documents—: it is the payment QR, and it arrives in payment.qr or in whichever payment method carries it. The payment request is the exception on the figures: it carries no VAT, so its table has no tax column and its total is the sum of the line items.

The label for whoever receives the document is yours to set: the payment request calls them «Copropietario» —the unit owner, which is where it is most used— and billToLabel prints whatever you send: «Cliente», «Paciente», «Estudiante». It works on every document, the invoice included, where without it the label stays «Adquiriente».

It can also carry the issuer’s logo as a watermark, behind the text, with marcaDeAgua: true —or { "imagen": "…", "opacidad": 0.06, "ancho": "62%" } for a different image, weight or size. Without that field nothing is drawn: a watermark that showed up on its own would change the look of documents for whoever is already integrated, without being asked for.

The three paper sizes come in five palettes, the same ones the invoice has: Premium —estandar, media-carta, con-aviso— plus moderna, clasica, minimalista and corporativa, which prefix their name: moderna-media-carta, clasica-con-aviso. A company picks one colour for everything it issues, so the same colour exists on all three paper sizes and not on one only.

And one more, which is not another colour but another layout: destacada, the one from the Destacada invoice —a full-bleed colour band with the issuer and the parties, the table on a card riding over it and the total in a bar of the same colour—, on all three paper sizes like the rest. On the split sheet its band runs from the edge of the paper to the cut line, which is its own half and leaves the notice side alone.

It also has one more design: media-carta, the same document on 14 x 21.6 cm paper —a Letter sheet cut in half, so two requests fit on one sheet and are cut apart afterwards. Nothing is left out: it says exactly the same, with the type size and margins of that paper. What a document states cannot depend on the size it is printed at.

And a third one, con-aviso: that same half-letter on a landscape sheet, with the other half for whatever you want to tell whoever receives the request —a meeting call, a change of hours, a reminder from the building manager— and a cut line down the middle. You print the whole sheet and cut it in two. The notice arrives as one more piece of data:

"aviso": {
  "subtitulo": "Convocatoria",
  "titulo": "Asamblea general ordinaria de copropietarios",
  "imagen": "https://…/banner.png",   // PNG o JPEG, opcional
  "datos": [
    { "etiqueta": "Lugar", "valor": "Salón social, Torre 1" },
    { "etiqueta": "Fecha", "valor": "Sábado 21 de marzo de 2026" },
    { "etiqueta": "Hora", "valor": "9:00 a. m. · Registro desde las 8:15 a. m." }
  ],
  "parrafos": ["…", "…"],
  "tituloDeLosPuntos": "Orden del día",
  "puntos": ["…", "…"],
  "qr": "https://…",                  // opcional
  "textoDelQr": "Confirme su asistencia",
  "notaLegal": "Se convoca conforme a …",
  "pie": "Administración"
}

datos is what people look for first in a notice —where, when, at what time— so it gets its own box instead of being buried in a paragraph. notaLegal is the rule or bylaw the meeting is called under, small and at the end. Everything is drawn exactly as it arrives: no address is assembled, no text is summarised and no law is interpreted. Without aviso, that half says so instead of coming out blank.

A word about what you send in billTo: an HOA payment request is handed out at the front desk and dropped in mailboxes, so whatever it carries in print is readable by anyone who walks past. The name, the ID number and the unit are enough to say who is being billed; the owner’s phone and email are not needed there, which is why the example does not send them. The engine prints whatever it receives: the call is yours, and it is worth making on purpose.

If you don’t send plantilla, you get the default design —the same as always—, so existing integrations don’t need to change anything. A plantilla that doesn’t exist responds 400 with the list of the ones that do, so you don’t have to go looking for it elsewhere.

Listing the available designs

A GET to the same address returns the catalog: the types, their designs, which one is the default and a description of each.

curl https://docsgen.piensait.com/api/documents

It lets you offer a picker in your application without keeping a hand-written list. A copied list goes stale the day we add a design, and nobody notices until someone requests one that no longer exists. It needs no key.

The style of each design

We can adjust the style of a design —its colors and, on the receipts, its black features: typeface, rules, boxes and bands— without you changing anything in your integration. What never changes with a style is what you send and what the document says: the same type, the same plantilla, the same data, the same sections in the same order and the same tax data. A style only changes how it looks. Before applying one, we compose it with a sample document and check that it is readable and takes up the same space; if not, it is not applied. An adjustment takes up to a minute to reach all documents.

To know which style each design is drawn with, the catalog includes in each one:

• estilo: the colors or features it comes out with today.
• versionDeEstilo: the version of that style, or null if it is the original one.

A design that doesn’t support styles —the contract, the collection account— has both set to null. They are the same values used by the document you request with that design, so you can use them to show an accurate preview in your picker.

And each document says which one it came out with, in the x-docgen-estilo response header: factura/premium@v3 if it used version 3 of that design’s style, or factura/premium@codigo if it used the original one. If you ever need to recompose a document identical to one you delivered, store that value alongside it.