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 noraw. - 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,renderorlayout: 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: anywhereon 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. |