Elegir el diseño

Los diseños de cada documento, las tirillas POS de 80 mm, el catálogo de diseños y el estilo con el que sale cada uno.

Un mismo documento puede salir con distintos diseños. Se pide con plantilla, junto al tipo:

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

La factura

Para la factura hay diecisiete: estandar —el de defecto—, premium, destacada —una banda de color de borde a borde con las partes y la tabla montada sobre ella—, siete con la estructura de la Premium en otro color: moderna, clasica, minimalista, profesional, corporativa, serena y basica, y siete tirillas POS. Todos leen los mismos datos, así que cambiar de diseño es cambiar una palabra.

Las tirillas POS

Las tirillas son la factura electrónica de venta para la impresora del punto de venta: un rollo de 80 mm de ancho, en una sola tira del largo de su contenido —no se corta en hojas, lleve 3 conceptos o 30— e impresas solo en negro, sin colores ni fondos grises —en algunos diseños, con letra blanca sobre bandas negras—, porque salen de una impresora térmica. Reciben el mismo cuerpo que cualquier otra factura y dicen lo mismo, en una columna: régimen, autorización de numeración, tarifa por línea, totales, valor en letras, pago, campos, leyendas, CUFE, QR, resolución y fabricante del software. El texto de sideNotes va al final, en renglones derechos, porque un rollo no tiene margen. El logo se dibuja tal como llega: si la impresora es térmica, conviene mandarlo en blanco y negro. En una venta de mostrador, mande también el plazo y el vencimiento (payment.term: "Contado", invoice.paymentDate con la fecha del día): la tirilla dice lo que falta, y sin ellos imprime «Sin plazo» y «Sin vencimiento».

Hay siete, y elegir una es cambiar solo plantilla. Como la térmica imprime en un solo color, se distinguen por la letra, las rayas, las cajas y las bandas negras, y lo que se ve en pantalla es lo que sale impreso.

plantilla	Cómo se ve
tirilla	Premium: sobria, con rayas discontinuas entre bloques
tirilla-destacada	El total en una barra negra con letra blanca y el encabezado entre dos filetes gruesos
tirilla-clasica	Toda en Courier, como la caja registradora de siempre
tirilla-minimalista	Sin rayas, con más aire entre bloques y rótulos pequeños
tirilla-corporativa	Cada bloque en su caja de borde continuo
tirilla-moderna	Los rótulos de sección en mayúsculas sobre bandas negras y el total grande
tirilla-estandar	Compacta: la más corta en papel, para mucho volumen

Los demás documentos

Por ahora:

Tipo	Diseños
nota-credito	premium
nota-debito	premium
recibo-de-caja	estandar —el de defecto— y premium
estado-de-cuenta	premium
colilla-de-nomina	azul —el de defecto—, esmeralda, violeta, grafito y ambar; premium, nombre anterior de grafito
informe	premium
entrada-de-inventario, salida-de-inventario, traslado-de-inventario	premium
cuenta-de-cobro	estandar —el de defecto—, media-carta y con-aviso, y los tres en cada paleta: moderna, moderna-media-carta, moderna-con-aviso, y lo mismo con clasica, minimalista y corporativa; más destacada, destacada-media-carta y destacada-con-aviso
cotizacion, pedido, requisicion, orden-de-compra, factura-de-compra, documento-equivalente, anticipo, comprobante-de-egreso, contrato	estandar

La nota crédito, la nota débito, el recibo de caja Premium, el estado de cuenta, el informe, los movimientos de inventario y todos los del Estándar —la cuenta de cobro, la cotización, el pedido, la requisición, la orden de compra, la factura de compra, el documento equivalente, el anticipo y el comprobante de egreso— tienen el aspecto de la factura Premium: el mismo encabezado con su logo, el mismo bloque con el cliente y los datos del documento, la misma tabla, el mismo margen y el pie en el mismo sitio. Así, lo que entrega una misma empresa se ve de la misma familia.

Los del Estándar cierran como la factura: el valor en letras, la caja de consignación y, a su lado, el código QR. En ellos el QR no es el de la verificación en la DIAN —no son documentos electrónicos—: es el del pago, y llega en payment.qr o en el medio de pago que lo traiga. La cuenta de cobro es la excepción de las cifras: no lleva IVA, así que su tabla no tiene columna de impuesto y su total es la suma de los conceptos.

El rótulo de quien recibe el documento lo dice usted: la cuenta de cobro lo llama «Copropietario», que es donde más se usa, y con billToLabel sale el que usted mande —«Cliente», «Paciente», «Estudiante»—. Vale en todos los documentos, también en la factura, donde de no mandarlo sigue diciendo «Adquiriente».

También puede llevar el logo del emisor como marca de agua, detrás del texto, con marcaDeAgua: true —o { "imagen": "…", "opacidad": 0.06, "ancho": "62%" } para otra imagen, otro peso u otro tamaño—. Sin ese campo no se dibuja: una marca de agua que apareciera sola le cambiaría el aspecto a quien ya está integrado sin haberla pedido.

Los tres papeles vienen en cinco paletas, las mismas de la factura: la Premium —estandar, media-carta, con-aviso— y moderna, clasica, minimalista y corporativa, que anteponen su nombre: moderna-media-carta, clasica-con-aviso. Quien elige un color lo elige para todo lo que entrega, así que el mismo color está en los tres papeles y no en uno sí y otro no.

Y una más, que no es otro color sino otra maquetación: destacada, la de la factura Destacada —una banda de color de borde a borde con el emisor y las partes, la tabla en una tarjeta montada sobre ella y el total en una barra del mismo color—, en los tres papeles, como las demás. En la carta partida su banda va del canto de la hoja a la línea de corte, que es lo suyo sin invadir la mitad del aviso.

Y tiene un diseño más: media-carta, el mismo documento en papel de 14 x 21,6 cm. Es la carta partida por la mitad, con la que caben dos cuentas en una hoja para cortarlas después. No se quita nada —dice lo mismo, con la letra y los márgenes de ese papel—: lo que un documento afirma no puede depender del tamaño en el que se imprima.

Y un tercero, con-aviso: esa misma media carta en una hoja apaisada, con la otra mitad para lo que usted quiera contarle a quien recibe la cuenta —una convocatoria, un cambio de horario, un recordatorio de la administración— y una línea de corte por el medio. Se imprime entera y se parte en dos. El aviso llega como un dato más:

"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 es lo que se busca primero en un aviso —dónde, cuándo, a qué hora— y por eso sale en su propio recuadro y no dentro de un párrafo, donde hay que leerlo entero para encontrar la fecha. notaLegal es la norma o el reglamento con el que se convoca, en pequeño y al final. Todo se dibuja tal como llega: no se arma ninguna dirección, no se resume ningún texto y no se interpreta ninguna ley. Sin aviso, esa mitad lo dice en vez de salir en blanco.

Una advertencia sobre lo que manda en billTo: una cuenta de cobro de administración se reparte en porterías y buzones, así que lo que lleve impreso lo lee cualquiera que pase. Con el nombre, el documento de identidad y el inmueble se sabe a quién se le cobra; el teléfono y el correo del copropietario no hacen falta ahí, y por eso el ejemplo no los manda. El motor imprime lo que reciba: la decisión es suya, y conviene tomarla a propósito.

Si no la manda, recibe el diseño por defecto —el mismo de siempre—, así que quien ya está integrado no tiene que cambiar nada. Un plantilla que no existe responde 400 con la lista de los que sí, para que no haya que ir a buscarla a otra parte.

Ver qué diseños hay

Un GET a la misma dirección devuelve el catálogo: los tipos, sus diseños, cuál es el de defecto y una descripción de cada uno.

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

Sirve para ofrecer un selector en su aplicación sin llevar la lista escrita a mano. Una lista copiada se queda vieja el día que añadimos un diseño, y nadie se entera hasta que alguien pide uno que ya no existe. No necesita clave.

El estilo de cada diseño

Podemos ajustar el estilo de un diseño —sus colores y, en las tirillas, sus rasgos en negro: la letra, las rayas, las cajas y las bandas— sin que usted cambie nada de su integración. Lo que no cambia nunca con un estilo es lo que usted manda y lo que el documento dice: el mismo type, la misma plantilla, los mismos data, las mismas secciones en el mismo orden y los mismos datos fiscales. Un estilo solo cambia cómo se ve. Antes de aplicarlo, lo componemos con un documento de ejemplo y comprobamos que se lee y que ocupa lo mismo; si no, no se aplica. Un ajuste tarda hasta un minuto en llegar a todos los documentos.

Para saber con qué estilo se dibuja cada diseño, el catálogo trae en cada uno:

• estilo: los colores o rasgos con los que sale hoy.
• versionDeEstilo: la versión de ese estilo, o null si es el de siempre.

Un diseño que no admite estilo —el contrato, la cuenta de cobro— trae los dos en null. Son los mismos que usa el documento que pida con ese diseño, así que sirven para enseñar una muestra fiel en su selector.

Y cada documento dice con cuál salió, en la cabecera x-docgen-estilo de la respuesta: factura/premium@v3 si salió con la versión 3 del estilo de ese diseño, o factura/premium@codigo si salió con el de siempre. Si alguna vez necesita recomponer un documento igual al que entregó, guarde ese valor junto a él.