Opcions de maquetació de les plantilles PDF
La configuració de les plantilles PDF incorpora les claus de schema_version 2: capçalera i costat del logo, estil i concepte de la taula de línies, peu legal, densitat de pàgina, mida de lletra per zona, colors de realç i de superfície, text de privadesa, condicions generals, títols opcionals de bloc, la mida de marca xl i la columna d'import amb impost. Les revisions informen schema_version.
22 d'octubre de 2026 (provisional: la data final és el dia en què es publiqui aquesta
versió) — La configuration d'una plantilla PDF ja pot descriure la
maquetació del document, no només els seus colors, lletres i textos. Tot és additiu: si omets les
claus noves, el PDF que tens avui es conserva byte a byte.
schema_version
PdfTemplateRevision informa schema_version: 1 per a les revisions desades abans d'aquesta versió (es llegeixen
exactament com es van desar, sense les claus noves) i 2 per a les que porten header, table i
legal_footer. Una escriptura sempre desa la revisió com a schema_version 2: les claus que ometis prenen
els valors per defecte de la llista, que es renderitzen exactament igual que una configuració de la versió 1.
Claus noves de configuration
| Clau | Valors | Què fa |
|---|---|---|
header.layout | preset (per defecte), executive, beside_logo, centered | Capçalera: la del disseny, dades de l'emissor i del document separades, títol i dates al costat del logo, o tot centrat. |
header.logo_side | left (per defecte), right | Emmiralla la capçalera; s'ignora amb centered. |
table.row_style | preset (per defecte), rules, zebra, none | Separadors entre línies. |
table.concept_mode | separate (per defecte), combined | combined imprimeix l'SKU en negreta sobre la descripció. |
table.show_line_descriptions | true (per defecte), false | Imprimeix o amaga la descripció addicional de cada línia. |
legal_footer.mode | last_page, every_page, body | On van el text de peu i el registre mercantil. Les plantilles noves usen last_page; una revisió de la versió 1 conserva body. |
legal_footer.notices_placement | after_content (per defecte), page_bottom | On s'imprimeixen les mencions legals i el text de protecció de dades: just després de les línies i els totals, o ancorades al final de l'última pàgina, abans de l'annex de condicions generals quan van en pàgina pròpia. Si el bloc ancorat superés uns 60 mm s'imprimeix després del contingut i la vista prèvia avisa amb legal_notices_not_anchored; el tiquet mai ancora. Disponible en tots els plans. |
page.density | standard (per defecte), compact | compact redueix l'espaiat vertical perquè un document curt càpiga en un full. |
typography.zone_scale.body, .lines, .legal | s, m (per defecte), l | Mida de lletra de cada zona: 0,9x, 1x o 1,1x de font_size. |
typography.highlight | brand (per defecte), ink | Color dels textos destacats: colors.primary o colors.text. |
colors.surface | #rrggbb o null | Superfície decorativa de premium i corporative; els altres dissenys la ignoren. |
branding.size | afegeix xl | La mida de marca més gran, per a logos amples. |
sections.privacy_text | {es, en, ca} | Text de protecció de dades en lletra petita. |
sections.show_generic_privacy_notice | true, false | Si s'imprimeix l'avís genèric de protecció de dades que una factura a una persona física afegeix a les seves mencions legals, al PDF i a l'enllaç públic. false per defecte en una plantilla nova, true en una d'importada i quan una revisió desada no porta la clau. Mai s'imprimeix si la plantilla té el seu propi privacy_text per a l'idioma del document. Les mencions fiscals (exempció, inversió del subjecte passiu, criteri de caixa) i els teus propis textos s'imprimeixen sempre. Disponible en tots els plans. |
sections.general_terms | {es, en, ca} | Condicions generals, només en factures. |
sections.general_terms_placement | after_totals (per defecte), annex_page | Després dels totals (a dues columnes quan el text és llarg) o en un full d'annex. |
sections.section_titles.notes, .conditions, .payment, .custom_fields, .references, .general_terms, .legal_mentions | true (per defecte; .legal_mentions és false en una plantilla nova, i una revisió desada sense la clau es llegeix com a true), false | false imprimeix aquest bloc opcional sense el seu títol i conserva el seu text o les seves files; amb .legal_mentions les mencions legals s'imprimeixen sempre, només desapareix l'encapçalament «Mencions legals». Els avisos de la factura rectificativa i simplificada, el bloc del QR tributari i el «Registre» del tiquet mai s'oculten. |
columns[].id | afegeix total_with_tax | Import amb impost per línia. A columns, la columna sku només s'imprimeix a la proforma; als altres documents l'SKU apareix amb table.concept_mode combined. |
Un valor fora del catàleg retorna 422 invalid_pdf_template_configuration amb el param exacte, per
exemple configuration.header.layout. Les opcions de maquetació són de l'editor avançat: una empresa sense ell
rep 403 feature_not_available_in_plan (la marca, inclòs xl, no està restringida). El pla Esencial, que no té editor avançat, sí que pot canviar el color de marca (colors.primary) i els textos destacats (typography.highlight); qualsevol altre color, sections.section_titles i la resta d'opcions de maquetació hi retornen aquest mateix 403, i el servidor mai deriva els altres colors de colors.primary.
Límits de la taula de línies
La taula de línies admet com a màxim 10 columnes visibles. Crear o publicar una revisió amb més retorna
422 invalid_pdf_template_configuration amb param configuration.columns i error.subcode
column_limit_exceeded. Si les columnes visibles no hi caben en l'amplada de la pàgina ni amb la lletra al mínim
(8 pt), comptant el pitjor cas de la plantilla (les seves columnes, les que exigeix una factura i fins a tres
columnes d'impost), la resposta és el mateix 422 amb error.subcode columns_exceed_page_width: amaga columnes,
redueix els marges o passa la pàgina a horitzontal. Quan hi caben reduint la lletra, el PDF baixa la mida de
lletra del document el just perquè la taula hi càpiga, sense que hagis de canviar res. La vista prèvia respon
422 pdf_presentation_invalid amb aquests mateixos subcodis.
Una plantilla desada abans amb més de 10 columnes visibles es continua pintant, amb les 10 primeres en el seu ordre i les que la factura exigeix, però no es pot tornar a publicar fins que s'amaguin les sobreres.
Un altre paper d'un document emès
La vista prèvia d'una revisió (source.kind presentation_revision) admet ara un format diferent del de la
presentació conservada: demana el tiquet d'una factura simplificada emesa en A4, o l'A4 d'una emesa en tiquet. És
una sortida alternativa amb les dades fiscals capturades; no crea revisió, no canvia la presentació conservada i
no requereix que el document es pugui revisar. Si la plantilla conservada no admet aquest paper, s'usa la que
heretaria el document o el disseny per defecte. Desar una revisió continua exigint el paper de la presentació
conservada.
Operacions
No hi ha cap operació nova. El cos de la petició canvia a crear (POST /v1/companies/{company}/pdf-templates),
publicar revisió i la vista prèvia (POST /v1/companies/{company}/pdf-template-previews); la resposta canvia a les
operacions que retornen una plantilla o una revisió. Les mateixes claus s'accepten i es llegeixen per les tools MCP.
Tools MCP
create_pdf_template i publish_pdf_template_revision descriuen configuration clau a clau en el seu esquema
d'entrada (tipus, catàlegs tancats i què fa cada valor), i preview_pdf_template descriu el formulari complet,
de manera que un assistent pot usar totes les opcions sense llegir aquesta pàgina. create_pdf_commercial_identity i
publish_pdf_commercial_identity_revision ara accepten null en una clau de configuration per netejar un
camp anul·lable, com ja feien les operacions HTTP.
Les taules següents llisten les operacions d'aquesta versió.
Endpoints actualitzats10
| Endpoint | Descripció |
|---|---|
POST/v1/companies/{company}/pdf-templates | Crear una plantilla PDF |
POST/v1/companies/{company}/pdf-templates/{template}/revisions | Publicar una revisió de plantilla PDF |
POST/v1/companies/{company}/pdf-template-previews | Crear una vista prèvia de plantilla PDF |
GET/v1/companies/{company}/pdf-templates/{template}/revisions/{revision} | Obtenir una revisió de plantilla PDF |
GET/v1/companies/{company}/pdf-templates/{template} | Obtenir una plantilla PDF |
GET/v1/companies/{company}/pdf-templates | Llistar les plantilles PDF |
POST/v1/companies/{company}/pdf-templates/{template}/duplicate | Duplicar una plantilla PDF |
PATCH/v1/companies/{company}/pdf-templates/{template} | Actualitzar les metadades d'una plantilla PDF |
POST/v1/companies/{company}/pdf-templates/{template}/archive | Arxivar una plantilla PDF |
POST/v1/companies/{company}/pdf-templates/{template}/restore | Restaurar una plantilla PDF |