Opciones de maquetación de las plantillas PDF
La configuración de las plantillas PDF incorpora las claves de schema_version 2: cabecera y lado del logo, estilo y concepto de la tabla de líneas, pie legal, densidad de página, tamaño de letra por zona, colores de realce y de superficie, texto de privacidad, condiciones generales, títulos opcionales de bloque, el tamaño de marca xl y la columna de importe con impuesto. Las revisiones informan schema_version.
22 de octubre de 2026 (provisional: la fecha final es el día en que se publique esta
versión) — La configuration de una plantilla PDF ya puede describir la
maquetación del documento, no solo sus colores, letras y textos. Todo es aditivo: si omites las
claves nuevas, el PDF que tienes hoy se conserva byte a byte.
schema_version
PdfTemplateRevision informa schema_version: 1 para las revisiones guardadas antes de esta versión (se leen
exactamente como se guardaron, sin las claves nuevas) y 2 para las que llevan header, table y
legal_footer. Una escritura siempre guarda la revisión como schema_version 2: las claves que omitas toman
los valores por defecto de la lista, que se renderizan exactamente igual que una configuración de la versión 1.
Claves nuevas de configuration
| Clave | Valores | Qué hace |
|---|---|---|
header.layout | preset (por defecto), executive, beside_logo, centered | Cabecera: la del diseño, datos del emisor y del documento separados, título y fechas junto al logo, o todo centrado. |
header.logo_side | left (por defecto), right | Espeja la cabecera; se ignora con centered. |
table.row_style | preset (por defecto), rules, zebra, none | Separadores entre líneas. |
table.concept_mode | separate (por defecto), combined | combined imprime el SKU en negrita sobre la descripción. |
table.show_line_descriptions | true (por defecto), false | Imprime u oculta la descripción adicional de cada línea. |
legal_footer.mode | last_page, every_page, body | Dónde van el texto de pie y el registro mercantil. Las plantillas nuevas usan last_page; una revisión de la versión 1 conserva body. |
legal_footer.notices_placement | after_content (por defecto), page_bottom | Dónde se imprimen las menciones legales y el texto de protección de datos: justo después de las líneas y los totales, o ancladas al final de la última página, antes del anexo de condiciones generales cuando van en página propia. Si el bloque anclado superase unos 60 mm se imprime después del contenido y la vista previa avisa con legal_notices_not_anchored; el ticket nunca ancla. Disponible en todos los planes. |
page.density | standard (por defecto), compact | compact reduce el espaciado vertical para que un documento corto quepa en una hoja. |
typography.zone_scale.body, .lines, .legal | s, m (por defecto), l | Tamaño de letra de cada zona: 0,9x, 1x o 1,1x de font_size. |
typography.highlight | brand (por defecto), ink | Color de los textos destacados: colors.primary o colors.text. |
colors.surface | #rrggbb o null | Superficie decorativa de premium y corporative; los demás diseños la ignoran. |
branding.size | añade xl | El mayor tamaño de marca, para logos anchos. |
sections.privacy_text | {es, en, ca} | Texto de protección de datos en letra pequeña. |
sections.show_generic_privacy_notice | true, false | Si se imprime el aviso genérico de protección de datos que una factura a una persona física añade a sus menciones legales, en el PDF y en el enlace público. false por defecto en una plantilla nueva, true en una importada y cuando una revisión guardada no lleva la clave. Nunca se imprime si la plantilla tiene su propio privacy_text para el idioma del documento. Las menciones fiscales (exención, inversión del sujeto pasivo, criterio de caja) y tus propios textos se imprimen siempre. Disponible en todos los planes. |
sections.general_terms | {es, en, ca} | Condiciones generales, solo en facturas. |
sections.general_terms_placement | after_totals (por defecto), annex_page | Tras los totales (a dos columnas cuando el texto es largo) o en una hoja de anexo. |
sections.section_titles.notes, .conditions, .payment, .custom_fields, .references, .general_terms, .legal_mentions | true (por defecto; .legal_mentions es false en una plantilla nueva, y una revisión guardada sin la clave se lee como true), false | false imprime ese bloque opcional sin su título y conserva su texto o sus filas; con .legal_mentions las menciones legales se imprimen siempre, solo desaparece el encabezado «Menciones legales». Los avisos de la factura rectificativa y simplificada, el bloque del QR tributario y el «Registro» del ticket nunca se ocultan. |
columns[].id | añade total_with_tax | Importe con impuesto por línea. En columns, la columna sku solo se imprime en la proforma; en los demás documentos el SKU aparece con table.concept_mode combined. |
Un valor fuera del catálogo devuelve 422 invalid_pdf_template_configuration con el param exacto, por
ejemplo configuration.header.layout. Las opciones de maquetación son del editor avanzado: una empresa sin él
recibe 403 feature_not_available_in_plan (la marca, incluido xl, no está restringida). El plan Esencial, que no tiene editor avanzado, sí puede cambiar el color de marca (colors.primary) y los textos destacados (typography.highlight); cualquier otro color, sections.section_titles y el resto de opciones de maquetación devuelven allí ese mismo 403, y el servidor nunca deriva los demás colores de colors.primary.
Límites de la tabla de líneas
La tabla de líneas admite como máximo 10 columnas visibles. Crear o publicar una revisión con más devuelve
422 invalid_pdf_template_configuration con param configuration.columns y error.subcode
column_limit_exceeded. Si las columnas visibles no caben en el ancho de la página ni con la letra al mínimo
(8 pt), contando el peor caso de la plantilla (sus columnas, las que una factura exige y hasta tres columnas de
impuesto), la respuesta es el mismo 422 con error.subcode columns_exceed_page_width: oculta columnas, reduce
los márgenes o pasa la página a horizontal. Cuando caben reduciendo la letra, el PDF baja el tamaño de letra del
documento lo justo para que la tabla quepa, sin que tengas que cambiar nada. La vista previa responde
422 pdf_presentation_invalid con esos mismos subcódigos.
Una plantilla guardada antes con más de 10 columnas visibles se sigue pintando, con las 10 primeras en su orden y las que la factura exige, pero no se puede volver a publicar hasta ocultar las sobrantes.
Otro papel de un documento emitido
La vista previa de una revisión (source.kind presentation_revision) admite ahora un format distinto del de
la presentación conservada: pide el ticket de una factura simplificada emitida en A4, o el A4 de una emitida en
ticket. Es una salida alternativa con los datos fiscales capturados; no crea revisión, no cambia la presentación
conservada y no requiere que el documento se pueda revisar. Si la plantilla conservada no admite ese papel, se
usa la que heredaría el documento o el diseño por defecto. Guardar una revisión sigue exigiendo el papel de la
presentación conservada.
Operaciones
No hay ninguna operación nueva. El cuerpo de la petición cambia en crear (POST /v1/companies/{company}/pdf-templates),
publicar revisión y la vista previa (POST /v1/companies/{company}/pdf-template-previews); la respuesta cambia en las
operaciones que devuelven una plantilla o una revisión. Las mismas claves se aceptan y se leen por las tools MCP.
Tools MCP
create_pdf_template y publish_pdf_template_revision describen configuration clave a clave en su esquema de
entrada (tipos, catálogos cerrados y qué hace cada valor), y preview_pdf_template describe el formulario completo,
de modo que un asistente puede usar todas las opciones sin leer esta página. create_pdf_commercial_identity y
publish_pdf_commercial_identity_revision ahora aceptan null en una clave de configuration para limpiar un
campo anulable, como ya hacían las operaciones HTTP.
Las tablas siguientes listan las operaciones de esta versión.
Endpoints actualizados10
| Endpoint | Descripción |
|---|---|
POST/v1/companies/{company}/pdf-templates | Crear una plantilla de PDF |
POST/v1/companies/{company}/pdf-templates/{template}/revisions | Publicar una revisión de plantilla de PDF |
POST/v1/companies/{company}/pdf-template-previews | Crear una vista previa de plantilla de PDF |
GET/v1/companies/{company}/pdf-templates/{template}/revisions/{revision} | Obtener una revisión de plantilla de PDF |
GET/v1/companies/{company}/pdf-templates/{template} | Obtener una plantilla de PDF |
GET/v1/companies/{company}/pdf-templates | Listar las plantillas de PDF |
POST/v1/companies/{company}/pdf-templates/{template}/duplicate | Duplicar una plantilla de PDF |
PATCH/v1/companies/{company}/pdf-templates/{template} | Actualizar los metadatos de una plantilla de PDF |
POST/v1/companies/{company}/pdf-templates/{template}/archive | Archivar una plantilla de PDF |
POST/v1/companies/{company}/pdf-templates/{template}/restore | Restaurar una plantilla de PDF |