Layout options for PDF templates
PDF template configuration gains the schema_version 2 keys: header layout and logo side, lines table style and concept, legal footer, page density, font size per zone, highlight and surface colors, privacy text, general terms, optional block titles, the xl brand size and the total with tax column. Revisions report schema_version.
22 October 2026 (provisional: the final date is the day this release is
published) — The configuration of a PDF template can now
describe the layout of the document, not only its colors, fonts and texts. Everything is
additive: omitting the new keys keeps the PDF you have today, byte for byte.
schema_version
PdfTemplateRevision reports schema_version: 1 for revisions saved before this release (they
are read exactly as they were stored, without the new keys) and 2 for those that carry
header, table and legal_footer. A write always stores a revision as schema_version 2: the keys
you omit take the defaults listed below, which render exactly like a version 1 configuration.
New keys in configuration
| Key | Values | What it does |
|---|---|---|
header.layout | preset (default), executive, beside_logo, centered | Header: the one of the design, issuer and document data split, title and dates next to the logo, or everything centered. |
header.logo_side | left (default), right | Mirrors the header; ignored with centered. |
table.row_style | preset (default), rules, zebra, none | Separators between lines. |
table.concept_mode | separate (default), combined | combined prints the SKU in bold above the description. |
table.show_line_descriptions | true (default), false | Prints or hides the additional description of each line. |
legal_footer.mode | last_page, every_page, body | Where the footer text and the commercial register go. New templates use last_page; a version 1 revision keeps body. |
legal_footer.notices_placement | after_content (default), page_bottom | Where the legal mentions and the data protection text are printed: right after the lines and totals, or anchored to the bottom of the last page, before the general terms annex when they are on their own page. If the anchored block would exceed about 60 mm it is printed after the content and the preview reports legal_notices_not_anchored; the ticket never anchors. Available on every plan. |
page.density | standard (default), compact | compact reduces the vertical spacing so that a short document fits on one page. |
typography.zone_scale.body, .lines, .legal | s, m (default), l | Text size of each zone: 0.9x, 1x or 1.1x of font_size. |
typography.highlight | brand (default), ink | Color of the highlighted texts: colors.primary or colors.text. |
colors.surface | #rrggbb or null | Decorative surface of premium and corporative; the other designs ignore it. |
branding.size | adds xl | The largest brand size, for wide logos. |
sections.privacy_text | {es, en, ca} | Data protection text in small type. |
sections.show_generic_privacy_notice | true, false | Whether the generic data protection notice that an invoice to a natural person adds to its legal mentions is printed, in the PDF and on the public link. false by default in a new template, true in an imported one and when a stored revision does not carry the key. It is never printed when the template has its own privacy_text for the document language. Fiscal mentions (exemption, reverse charge, cash-basis regime) and your own texts are always printed. Available on every plan. |
sections.general_terms | {es, en, ca} | General terms, printed on invoices only. |
sections.general_terms_placement | after_totals (default), annex_page | After the totals (in two columns when the text is long) or on an annex page. |
sections.section_titles.notes, .conditions, .payment, .custom_fields, .references, .general_terms, .legal_mentions | true (default; .legal_mentions is false in a new template, and a stored revision without the key reads as true), false | false prints that optional block without its title and keeps its text or rows; with .legal_mentions the legal mentions are still always printed, only the «Legal mentions» heading disappears. The corrective and simplified invoice notices, the tax QR block and the ticket «Register» are never hidden. |
columns[].id | adds total_with_tax | Amount with tax per line. In columns, the sku column is only printed on the pro forma; on the other documents the SKU appears with table.concept_mode combined. |
A value outside the catalog returns 422 invalid_pdf_template_configuration with the exact param, for
example configuration.header.layout. Layout options belong to the advanced editor: a company without it
receives 403 feature_not_available_in_plan (the brand, including xl, is not restricted). The Essential plan, which has no advanced editor, can still change the brand color (colors.primary) and the highlighted texts (typography.highlight); any other color, sections.section_titles and the rest of the layout options return that same 403 there, and the server never derives the other colors from colors.primary.
Line table limits
The line table accepts at most 10 visible columns. Creating or publishing a revision with more returns
422 invalid_pdf_template_configuration with param configuration.columns and error.subcode
column_limit_exceeded. If the visible columns do not fit the page width even at the minimum font size (8 pt),
counting the template's worst case (its columns, the ones an invoice requires and up to three tax columns), the
response is the same 422 with error.subcode columns_exceed_page_width: hide columns, reduce the margins or
switch the page to landscape. When they fit by reducing the font, the PDF lowers the document font size just
enough for the table to fit, with nothing for you to change. The preview responds 422 pdf_presentation_invalid
with the same subcodes.
A template saved earlier with more than 10 visible columns is still rendered, with the first 10 in their order and the ones the invoice requires, but it cannot be published again until the extra ones are hidden.
Another paper for an issued document
The preview of a revision (source.kind presentation_revision) now accepts a format other than the one of
the retained presentation: ask for the receipt of a simplified invoice issued in A4, or the A4 of one issued as a
receipt. It is an alternative output with the captured tax data; it creates no revision, does not change the
retained presentation and does not require the document to be revisable. If the retained template does not
support that paper, the one the document would inherit or the default design is used. Saving a revision still
requires the paper of the retained presentation.
Operations
No operation is new. The request body changes in create (POST /v1/companies/{company}/pdf-templates), publish revision
and the preview (POST /v1/companies/{company}/pdf-template-previews); the response changes in the operations that
return a template or a revision. The same keys are accepted and read through the MCP tools.
MCP tools
create_pdf_template and publish_pdf_template_revision describe configuration key by key in their input schema
(types, closed catalogs and what each value does), and preview_pdf_template describes the complete form, so an
assistant can use every option without reading this page. create_pdf_commercial_identity and
publish_pdf_commercial_identity_revision now accept null in a configuration key to clear a nullable field, as the
HTTP operations already did.
The tables below list the operations of this release.
Updated endpoints10
| Endpoint | Description |
|---|---|
POST/v1/companies/{company}/pdf-templates | Create a PDF template |
POST/v1/companies/{company}/pdf-templates/{template}/revisions | Publish a PDF template revision |
POST/v1/companies/{company}/pdf-template-previews | Create a PDF template preview |
GET/v1/companies/{company}/pdf-templates/{template}/revisions/{revision} | Retrieve a PDF template revision |
GET/v1/companies/{company}/pdf-templates/{template} | Retrieve a PDF template |
GET/v1/companies/{company}/pdf-templates | List PDF templates |
POST/v1/companies/{company}/pdf-templates/{template}/duplicate | Duplicate a PDF template |
PATCH/v1/companies/{company}/pdf-templates/{template} | Update PDF template metadata |
POST/v1/companies/{company}/pdf-templates/{template}/archive | Archive a PDF template |
POST/v1/companies/{company}/pdf-templates/{template}/restore | Restore a PDF template |