docsgen by Piensa IT
En esta página

Qué va dentro de data

Importes, campos abiertos, dirección de entrega, régimen fiscal, logo, software, autorización y leyendas legales.

Hay un cuerpo de ejemplo completo por cada tipo, y no son ilustrativos: forman parte de nuestras pruebas automáticas. La forma más rápida de empezar es tomar el ejemplo de su tipo, cambiarle los datos por los suyos y mandarlo. Después se recorta lo que no aplique.

Un solo vocabulario para los importes

Los totales van anidados, y son los mismos para todos los diseños:

"totals": {
  "gross": 240000,        // valor bruto
  "taxableBase": 240000,  // base imponible
  "tax": 45600,           // IVA
  "withholding": 6000,    // retefuente
  "discount": 0,          // descuento global
  "surcharge": 0,         // recargo global
  "total": 285600
}

Que no dependan del diseño elegido es deliberado: si cada uno leyera las cifras a su manera, usted tendría que saber qué diseño pidió para saber cómo mandarlas, y esa es la clase de trampa que se paga en una factura equivocada.

Recuerde que no se calcula nada: si total no cuadra con las líneas, se imprime lo que llegó. Tampoco la retefuente: se imprime en su línea y no se resta del total. Si no la manda, la línea sale sin cifra, porque un $ 0,00 diría que no hubo retención.

La tarifa de IVA de cada línea va en el concepto, y se imprime en su columna como 19 %. Va como número, sin el símbolo de porcentaje —19, no "19%"—: la coletilla « %» la añade el motor. Si no la manda, la celda queda vacía:

"items": [
  { "code": "SRV-DOM-001", "name": "Registro de dominio .com — anual",
    "quantity": 1, "amount": 240000, "taxRate": 19, "total": 240000 }
]

Lo que cada empresa imprime, en una lista abierta

Vendedor, canal, concepto, orden de compra, número de pedido, punto de entrega, centro de costo, periodo facturado… Cada empresa imprime unos distintos, así que no son campos con nombre propio: van en fields, y se dibujan en el orden en que los mande.

"fields": [
  { "label": "Vendedor", "value": "Mariana Gómez Uribe" },
  { "label": "Orden de compra", "value": "OC-2026-0448" },
  { "label": "Punto de entrega", "value": "Centro de datos, Carrera 70 #45-23, Medellín" }
]

Un campo que manda sin su valor —vacío, null o ausente— se imprime igual: sale la leyenda y el hueco se queda vacío. Así el renglón sigue ahí y usted no tiene que filtrar la lista antes de mandarla. Lo que sí se descarta es un campo sin leyenda: un hueco suelto no dice de qué. Un 0 es un dato y se imprime como tal. Si no manda ninguno, el recuadro no se dibuja.

Las claves se admiten en inglés y en español: { "label", "value" } o { "etiqueta", "valor" }.

Los datos con significado propio —el número, las fechas, el CUFE, los totales— no van aquí: esos tienen su lugar y su regla.

La dirección de entrega

Dirección de entrega (shipTo: name, address, phone) — hoy solo la dibuja el diseño destacada; si no la manda, no aparece. Es opcional: los demás diseños la ignoran, así que puede mandarla siempre sin que cambie nada en ellos.

"shipTo": {
  "name": "Bodega central",
  "address": "Autopista Sur 12-34, Itagüí",
  "phone": "6043334455"
}

Sin nombre ni dirección, el bloque no sale: un «Enviar a» sin decir adónde no le sirve a nadie.

Su régimen fiscal

Lo que su empresa declara de sí misma —responsable de IVA, autorretenedor o no, gran contribuyente— va en yourCompany.taxRegime y se imprime junto al NIT, tal como lo mande:

"yourCompany": {
  "name": "Empresa Emisora S.A.S.",
  "nit": "900123456-7",
  "taxRegime": "Responsables de IVA · No autorretenedores"
}

Si no lo manda, no ocupa renglón. No lo ponemos por usted a propósito: es una declaración tributaria suya, y un generador que la diera por puesta la estaría firmando en su nombre.

El logo es suyo, no nuestro: llega en yourCompany.logo y cada aplicación manda el de la empresa que emite. No hay nada que subirnos ni que configurar de antemano.

"yourCompany": {
  "name": "Empresa Emisora S.A.S.",
  "nit": "900123456-7",
  "logo": "https://su-dominio.com/logo.png"
}

Tres cosas que evitan una sorpresa:

  • URL absoluta o data:. Una ruta como /logo.png no significa nada en un servidor: sin navegador que la complete, no hay dónde buscarla.
  • PNG o JPEG, no SVG. Está comprobado midiendo la matriz de transformación del PDF: un SVG se dibuja a su tamaño original y la caja de estilo solo lo recorta, así que sale cortado salvo que mida exactamente lo que la caja. Un PNG sí se ajusta.
  • Lo que se fija es el hueco, no el dibujo. El logo se acomoda dentro sin deformarse, así que una marca apaisada y una cuadrada caben las dos. Si no manda ninguno, el documento arranca por el nombre de la empresa: no se reserva un espacio en blanco ni se dibuja un recuadro de «sin logo», porque que una empresa no tenga logo no es una carencia que haya que anunciar.

Quién fabrica el software

Toda factura electrónica dice con qué software se emitió. No es un crédito de cortesía: identifica a quién responde por la emisión.

"software": {
  "manufacturer": "CoreLink S.A.S.",
  "name": "CoreLink Facturación Electrónica",
  "version": "1.0",
  "web": "www.corelink.com.co"
}

El número de autorización

Junto al consecutivo va el número de autorización de numeración, su fecha, el rango autorizado y su vencimiento. Sin eso nadie puede comprobar que el número impreso está dentro de lo autorizado:

"authorization": {
  "number": "18764101686441853",
  "authorizedAt": "18-11-2025",
  "prefix": "PIFE", "rangeFrom": 1, "rangeTo": 10000,
  "validFrom": "18-11-2025", "validUntil": "18-11-2027",
  "resolution": "18764101686441", "economicActivity": "6201"
}

Si falta, el documento dice «Sin número de autorización» en vez de callarse.

Texto en el margen

Lo que tiene que estar pero no tiene por qué estorbar —«Documento generado por computador», la marca del software, un número de control— se escribe de arriba abajo en el margen izquierdo, en todas las hojas:

"sideNotes": [
  "Documento generado por computador. No requiere firma autógrafa.",
  "CoreLink by Piensa IT S.A.S."
]

Ocupa un margen que de otro modo se desperdicia y descarga el pie, que en una factura electrónica ya va lleno de CUFE y resolución.

Funciona igual en la factura, las notas crédito y débito, el recibo de caja Premium, el estado de cuenta y la colilla de nómina. Si no manda ninguna, el margen queda en blanco.

Las leyendas legales las pone usted

Los textos que la factura debe llevar —la asimilación a letra de cambio, la aceptación tácita de la Ley 1231, lo que corresponda a su régimen— van en legalNotes, y se imprimen tal cual:

"legalNotes": [
  "Esta factura electrónica de venta se asimila en todos sus efectos legales a una letra de cambio, conforme al artículo 774 del Código de Comercio.",
  "Documento generado por computador. No requiere firma autógrafa."
]

No las elegimos nosotros a propósito. Qué leyendas debe llevar una factura depende del régimen, las responsabilidades fiscales y la actividad de quien la emite; un generador que las decidiera por su cuenta estaría redactando el documento de otro, y una leyenda equivocada en una factura firmada no la corrige nadie después.

Qué cambia para quien ya está integrado

Unas cuantas cosas nuevas, para quien ya venía mandando facturas:

  • El margen izquierdo y el recuadro de campos ya no se rellenan solos: si no manda sideNotes y fields, sencillamente no salen.
  • Los campos de fields se dibujan en el orden en que los mande.
  • La tarifa de IVA de cada línea sale vacía si no manda taxRate —antes la Estándar escribía 0 %—.
  • La línea de retefuente aparece sin cifra si no manda totals.withholding.
  • El pie con la resolución, el fabricante del software y el número de página se ve ahora en todas las hojas, no solo en la primera.
  • El título de la Premium se imprime más pequeño.