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, contrato	estandar

La nota crédito, la nota débito, el recibo de caja Premium, el estado de cuenta, el informe y los movimientos de inventario tienen el aspecto de la factura Premium: el mismo encabezado, el mismo bloque con el cliente y los datos del documento, el mismo margen y el pie en el mismo sitio. Así, lo que entrega una misma empresa se ve de la misma familia.

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.