Skip to content

Invoice templates

How to write, look at, validate, publish and promote the design of the printed invoice: the language, the functions, the data, the paper and what SUNAT requires.

A template says what the printed invoice looks like (the PDF in the email, the ticket at the till). You write it once; the service validates it against what SUNAT requires, stores it as a version that never changes and uses it for every invoice. Read this guide once, before you start.

The whole path

Step Route What happens
1. Create from a shared one POST /v1/templates With from: "system:a4" (or system:thermal-80, system:thermal-58) you start from a template that already passes validation.
2. Edit the draft PUT /v1/templates/{id}/draft Send source, manifest and the revision you read. Saving checks the syntax and renders a sample; if someone saved first, it answers a conflict and overwrites nothing.
3. Look at it POST /v1/templates/{id}/render The draft rendered with a sample, as html, png or pdf. If you can see images, ask for png and check your work.
4. Validate POST /v1/templates/{id}/validate Renders every official sample, prints it and checks what is VISIBLE on the paper. Answers every rule and the validated revision.
5. Publish POST /v1/templates/{id}/publish With the validated revision: creates a version that never changes, and TEST invoices use it from then on.
6. Promote POST /v1/templates/{id}/promote A person decides: LIVE invoices use the promoted version. Going back is promoting another one.

For a person to look or edit without signing in, create a link with POST /v1/templates/{id}/preview_links (scope view, edit or publish). From the command line, invoicing templates pull | push | watch | validate | publish | promote | render does the same with two files in a folder. To print with that design, send template_id when issuing, or set it as the issuer’s default_template with PUT /v1/issuer. An organization has up to 20 active templates.

The language

Liquid over HTML and CSS, with rules made for a template written by a third party:

  • Everything you write with {{ }} is escaped. There is no raw.
  • A field or a function that does not exist is an error with line, column and a suggestion (“Did you mean…?”), not a silent blank. A condition on a missing field is simply false.
  • There is no include, render or layout: everything goes in one template.
  • No JavaScript and no network when printing: what is not inside the document does not exist. Images come from your library and fonts from the catalog, both embedded.

The limits count steps, not time:

Limit Value
Length of the template 200 000 characters
Steps while rendering (one per node and per turn of a loop) 100 000
Writes 50 000
Size of the rendered document, images included 4 MB

An A4 with 60 lines uses about 2 000 steps. Going over a limit answers template_limit_exceeded and says which one.

The functions

Function What for Example
money Dinero con el símbolo de la moneda del documento; money: false sin símbolo. {{ invoice.totals.total | money }} → S/ 1,593.00
quantity Una cantidad sin ceros de más. {{ item.quantity | quantity }} → 2
percent Un porcentaje. {{ tax.rate | percent }} → 18 %
date Fecha u hora de Lima, por su texto. Formato opcional (dd, MM, MMMM, yyyy, HH, mm, ss). {{ document.issued_at | date: "dd/MM/yyyy HH:mm" }} → 17/11/2026 10:30
in_words Un monto en letras, en la moneda del documento. El del total ya viene en invoice.amount_in_words. {{ invoice.totals.total | in_words }} → SON: MIL QUINIENTOS NOVENTA Y TRES CON 00/100 SOLES
pad Rellena con ceros a la izquierda. {{ document.number | pad: 8 }} → 00000123
qr Dibuja el código QR (nivel Q, como pide SUNAT), sin red. Tamaño en píxeles CSS (96 = 25,4 mm). {{ document.qr_content | qr: 96 }}
barcode Code 128 o EAN-13. Alto opcional en milímetros. {{ document.full_number | barcode: "code128", 10 }}
asset Una imagen de la biblioteca de la organización, incrustada. <img src="{{ brand.images.logo | asset }}">
font_family La familia de una fuente del catálogo, para CSS, con su respaldo. font-family: {{ brand.fonts.body | font_family: "inter" }};
color Un color hexadecimal seguro para CSS, o el de respaldo. color: {{ brand.colors.primary | color: "#16181d" }};
gt_zero Verdadero si un monto es mayor que cero. {% assign show = invoice.totals.exempt | gt_zero %}{% if show %}…{% endif %}
upcase · downcase · truncate Texto en mayúsculas, minúsculas o recortado (de Liquid). {{ document.customer.name | truncate: 40 }}

The print data

Your template receives a JSON with four keys: version, document (the common data: issuer, establishment, customer, series and number, date, QR, marks, labels), invoice (items, taxes, discounts, totals, amount in words, payment and instalments, legends) and brand (the organization’s brand). Every key is ALWAYS present: what is missing is null, an empty list is []. Money comes as text with two decimals. The full schema is at GET /v1/print_data/schema and the official samples at GET /v1/print_data/samples.

Field What it is
document.type_label, document.full_number “Factura electrónica”, “F001-00000123”
document.issued_at Lima date and time, with no zone (use date)
document.issuer.legal_name, .trade_name, .tax_id, .address.full The issuer as it was when the invoice was issued
document.establishment.code, .name, .address.full The establishment it was issued from (null on older invoices)
document.customer.name, .id_type_label, .id_number The customer
document.qr_content The text of the QR: draw it with qr
document.marks “SIN VALOR FISCAL”, “ANULADO”: loop over them and show them all
document.labels The fixed labels (“RUC”, “Total”…) and printed_representation
invoice.items[] quantity, unit_label, description, unit_price, value, total
invoice.totals taxable, exempt, unaffected, taxes, subtotal, total…
invoice.amount_in_words “SON: … SOLES”, the same text as in the signed XML
invoice.payment Cash or credit, with its instalments
invoice.legends[] The SUNAT legends (Amazonía, free transfer…)

The official samples it is validated with:

Sample Name What it tests
boleta_cash Boleta al contado Una venta de mostrador sin cliente identificado, desde un local anexo.
boleta_customer Boleta con cliente Una boleta de más de S/ 700 con cliente identificado por DNI: el cliente debe verse.
factura_discounts Factura con descuentos Descuento por ítem, descuento global que afecta la base y otro que no la afecta, y un ítem exonerado.
factura_credit Factura a crédito Pago a crédito en tres cuotas con descuento global del 10 %.
many_lines Muchas líneas Sesenta ítems: la tabla debe continuar en varias páginas sin perder filas ni totales.
long_names Nombres muy largos Razón social, cliente, dirección y descripción largas: nada debe salirse del papel ni cortarse.
voided Anulada Una factura anulada: la marca «ANULADO» debe verse.
test De prueba Una boleta emitida en Pruebas: la marca «SIN VALOR FISCAL» debe verse.
boleta_icbper Boleta con ICBPER Una bolsa plástica: el impuesto a las bolsas (ICBPER) debe verse.
credit_note Nota de crédito La devolución de un monitor: el documento que modifica y el motivo deben verse.
debit_note Nota de débito Intereses por pago tardío de una factura: el documento que modifica y el motivo deben verse.

The brand and the images

brand carries the organization’s values, never a design: brand.colors (primary, accent, text, muted…), brand.fonts (heading, body, mono), brand.images (logo, logo_mono: names in the library) and brand.texts (header, footer). They are edited with PUT /v1/brand; every invoice keeps the brand it had when it was issued. Using or ignoring them is up to your template.

Images live in the organization’s library: upload them with PUT /v1/assets/{name} (PNG, JPEG, WebP or sanitized SVG, up to 512 KB) and use them by name: {{ 'logo' | asset }} or {{ brand.images.logo | asset }}. On publishing, the version keeps the exact fingerprint of every image it used: changing the image later does not change what was published. A name that is not in the library answers asset_not_found.

The paper

The manifest declares it, not the CSS:

{
  "paper": {
    "kind": "thermal_80"
  },
  "print_data_version": 1,
  "document_types": [
    "factura",
    "boleta"
  ],
  "fonts": [
    "geist-mono"
  ]
}
paper.kind Width Height
a4 210 mm 297 mm
letter 215.9 mm 279.4 mm
thermal_80 80 mm measured from the content (up to 4 000 mm per page; anything taller continues on another)
thermal_58 58 mm measured from the content (up to 4 000 mm per page; anything taller continues on another)
custom width_mm (40 to 500) height_mm (40 to 4 000), or null to measure it

Do not put @page { size } in your CSS: the manifest decides the paper, and a rule that changes the sheet is rejected when printing. The margins of @page are respected.

The fonts

Only those in the catalog (GET /v1/fonts), embedded when printing. Declare them in manifest.fonts or ask for them with font_family; one that is not in the catalog answers font_not_in_catalog.

Font Family Kind
inter Inter sans-serif
ibm-plex-sans IBM Plex Sans sans-serif
source-serif-4 Source Serif 4 serif
geist-mono Geist Mono monospace

What printing for real taught us

  • One block per required field. RUC, legal name, series and number, date and totals are looked for in the text left on the paper. Put each one in its own block (<p>, <div>): two fields stuck together on one line can be read as one.
  • Long names must wrap. Use overflow-wrap: anywhere on descriptions and names: text that runs off the paper fails validation (documento_desborde).
  • No links. The sanitizer removes every href, script, iframe, form and outside resource. Anything the sanitizer has to remove fails validation (plantilla_saneado): remove it from the template yourself.
  • Hidden does not count. A required field with display:none, white on white or off the page is not on the paper, and validation fails.
  • The QR goes at the bottom, at its size. Draw it with qr (a QR made any other way does not count), after the totals, at least as large as validation says.
  • Always the marks. Loop over document.marks: a test or voided invoice must never look valid.

A starting point

The shortest template that can pass validation for factura and boleta (the system:* templates are the complete example):

<!DOCTYPE html>
<html lang="es">
<head>
  <meta charset="utf-8">
  <title>{{ document.type_label }} {{ document.full_number }}</title>
  <style>
    body { font-family: {{ brand.fonts.body | font_family: "geist-mono" }}; font-size: 8pt; margin: 3mm; }
    .linea { display: block; margin: 0 0 1mm; overflow-wrap: anywhere; }
  </style>
</head>
<body>
  {% for mark in document.marks %}<p class="linea"><strong>{{ mark.text }}</strong></p>{% endfor %}
  <p class="linea">{{ document.issuer.legal_name }}</p>
  {% if document.issuer.trade_name %}<p class="linea">{{ document.issuer.trade_name }}</p>{% endif %}
  <p class="linea">{{ document.labels.tax_id }} {{ document.issuer.tax_id }}</p>
  <p class="linea">{{ document.type_label }}</p>
  <p class="linea">{{ document.full_number }}</p>
  <p class="linea">{{ document.issued_at | date: "dd/MM/yyyy HH:mm" }}</p>
  <p class="linea">{{ document.currency.name }}</p>
  <p class="linea">{{ document.customer.id_type_label }} {{ document.customer.id_number }}</p>
  <p class="linea">{{ document.customer.name }}</p>
  {% for item in invoice.items %}
  <div class="linea">
    <p class="linea">{{ item.description }}</p>
    <p class="linea">{{ item.quantity | quantity }} {{ item.unit_label | default: item.unit_code }} x {{ item.unit_price | money }}</p>
    <p class="linea">Valor unitario {{ item.unit_value | money }}</p>
    <p class="linea">Valor de venta {{ item.value | money }}</p>
    {% for tax in item.taxes %}<p class="linea">{{ tax.label }} {{ tax.amount | money }}</p>{% endfor %}
    <p class="linea">Importe {{ item.total | money }}</p>
  </div>
  {% endfor %}
  {% for adjustment in invoice.discounts %}<p class="linea">{{ adjustment.label }} {{ adjustment.amount | money }}</p>{% endfor %}
  {% for adjustment in invoice.charges %}<p class="linea">{{ adjustment.label }} {{ adjustment.amount | money }}</p>{% endfor %}
  <p class="linea">Op. gravadas {{ invoice.totals.taxable | money }}</p>
  <p class="linea">Op. exoneradas {{ invoice.totals.exempt | money }}</p>
  <p class="linea">Op. inafectas {{ invoice.totals.unaffected | money }}</p>
  <p class="linea">Valor de venta {{ invoice.totals.sale_value | money }}</p>
  <p class="linea">Descuentos {{ invoice.totals.discounts | money }}</p>
  {% for tax in invoice.taxes %}<p class="linea">{{ tax.label }} {{ tax.amount | money }}</p>{% endfor %}
  <p class="linea">Total {{ invoice.totals.total | money }}</p>
  <p class="linea">{{ invoice.amount_in_words }}</p>
  {% if document.qr_content %}{{ document.qr_content | qr: 120 }}{% endif %}
  <p class="linea">{{ document.labels.printed_representation }}</p>
</body>
</html>

What validation checks

Every official sample your template accepts is rendered, printed with the real service and checked. A rule that fails blocks publishing; a warning does not. The answer says, per rule, in which sample it failed and how to fix it.

Group What it checks
plantilla The manifest is valid, every sample renders within the limits and the sanitizer had nothing to remove.
contenido_obligatorio What SUNAT requires on the printed representation, looked for in the VISIBLE text: 45 rules (below).
codigo_qr qr_presente, qr_nivel_q, qr_tamano, qr_parte_inferior: the invoice’s QR, level Q, on the paper, with modules of 0.19 mm or more and at the bottom.
documento The marks are visible, nothing runs off the paper, nothing was requested from outside; the payment terms and the instalments (warning only).
Rule What must be visible Source
emisor_razon_social Razón social del emisor A1 it. 3; A2 it. 3; A3/A4 it. 3
emisor_nombre_comercial Nombre comercial del emisor A1 it. 4; A2 it. 4; A3/A4 it. 4
emisor_ruc RUC del emisor A1 it. 6; A2 it. 6; A3/A4 it. 6
denominacion_documento Denominación del documento A1 it. 7; A2 it. 7; A3/A4 it. 8
serie_numero Serie y número A1 it. 8; A2 it. 8; A3/A4 it. 8
fecha_emision Fecha de emisión A1 it. 1; A2 it. 1; A3/A4 it. 1
moneda Moneda del documento A1 it. 9; A2 it. 9; A3/A4 it. 9
adquirente_documento Documento del cliente A1 it. 11; A3/A4 it. 11
adquirente_nombre Nombre del cliente A1 it. 12; A3/A4 it. 12
boleta_adquirente Cliente de la boleta A2 it. 11 y 12; RCP art. 8 num. 3.10 (regla conservadora de 07 §5)
item_descripcion Descripción de cada ítem A1 it. 16; A2 it. 17; A3/A4 it. 18
item_cantidad Cantidad de cada ítem A1 it. 15; A2 it. 16; A3/A4 it. 14
item_unidad Unidad de cada ítem A1 it. 14; A2 it. 15; A3/A4 it. 13
item_precio_unitario Precio unitario por ítem A1 it. 22; A2 it. 23; A3/A4 it. 21
item_valor_unitario Valor unitario por ítem A3/A4 it. 19
boleta_item_valor_venta Valor y tributos por ítem A2 it. 29 y 30
total_op_gravadas Total de operaciones gravadas A1 it. 33; A2 it. 33; A3/A4 it. 28
total_op_inafectas Total de operaciones inafectas A1 it. 34; A2 it. 34; A3/A4 it. 29
total_op_exoneradas Total de operaciones exoneradas A1 it. 35; A2 it. 35; A3/A4 it. 30
total_op_exportacion Total de exportación A1 it. 36; A2 it. 36; A3/A4 it. 31
total_op_gratuitas Total de operaciones gratuitas A1 it. 37; A2 it. 37
total_igv Total del IGV A1 it. 39; A3/A4 it. 34
total_isc Total del ISC A1 it. 40; A3/A4 it. 35
total_otros_tributos Total de otros tributos A1 it. 41; A3/A4 it. 36
total_icbper Total del ICBPER A1 it. 40-A; A2 it. 40-A; A3/A4 it. 35-A
total_otros_cargos Otros cargos A1 it. 43; A3/A4 it. 37
total_otros_descuentos Otros descuentos A1 it. 44; A2 it. 44
cargos_descuentos_globales Cargos y descuentos globales A1 it. 45; A2 it. 45
boleta_total_valor_venta Valor de venta y subtotal A2 it. 46 y 47
nota_total_tributos Tributos de la nota A3/A4 it. 38
importe_total Importe total A1 it. 48; A2 it. 48; A3/A4 it. 39
redondeo Redondeo del total A1 it. 49
guia_relacionada Guía de remisión relacionada A1 it. 59
documento_relacionado Documento relacionado A1 it. 60; A2 it. 56; A4 it. 43
placa_vehiculo Placa del vehículo A1 it. 63
direccion_itinerante Dirección de venta itinerante A1 it. 64
leyendas_del_comprobante Leyendas del comprobante A1 it. 61; A2 it. 57
leyenda_gratuita Leyenda de transferencia gratuita A1 it. 61; A2 it. 57; catálogo 52 (1002)
leyenda_amazonia Leyenda de la Amazonía DS 103-99-EF art. 10; catálogo 52 (2001 a 2003)
leyenda_detraccion Leyenda de detracción RS 183-2004 art. 19.1 b); catálogo 52 (2006)
leyenda_percepcion Leyenda de percepción Catálogo 52 (2000)
boleta_consolidada Boleta consolidada A2 it. 17
nota_motivo Motivo de la nota A3/A4 it. 10
nota_documento_modificado Documento que modifica la nota A3/A4 it. 41 y 42
leyenda_representacion_impresa Leyenda de representación impresa A1 it. 62; A2 it. 58; A3/A4 it. 45

The errors and what to do

Error What to do
template_syntax_error Fix the line and column it gives; the answer carries a suggestion when there is an obvious one.
template_limit_exceeded Check the loops: one may never end, or may go over too much.
template_draft_conflict Someone saved another revision: read again, merge and save with the current revision.
template_validation_failed The answer carries every rule that failed, in which sample and how to fix it. Fix it, validate and publish the new revision.
render_unavailable The print service is not answering right now: retry. Nothing was published.
asset_not_found Upload the image with that name, or use another one.
font_not_in_catalog Use a font from the catalog.
template_document_type_not_accepted Add the document type to the manifest’s document_types, or issue with another template.
template_not_published The template has no published version: publish it before issuing with it in test mode.
template_version_not_promoted In production only a promoted version is printed: a person must approve and promote it.
template_is_default Set another default on the issuer before archiving it.

Type to search…

↑↓ navigate↵ selectEsc close