Biblioteca de plantilles PDF i factures estructurades

19 d'octubre de 2026 (provisional: la data definitiva és el dia que es publiqui aquesta release) — L'API exposa ara la biblioteca de plantilles PDF de l'app, la presentació que conserva cada document, els artefactes PDF exactes i les dades de negoci estructurades d'una factura. Quatre guies expliquen el model complet: Biblioteca de plantilles PDF, Presentació de documents, Vistes prèvies i artefactes PDF i Dades de negoci de la factura.

Totes les operacions d'aquesta release pengen de l'eix d'empresa, /v1/companies/{company}/…, on {company} és l'id (UUID v7) del NIF amb què operes; arribar a un NIF ho explica. Cap de les operacions noves no es va publicar mai a l'arrel de /v1: són noves, no s'han mogut, així que no hi ha cap ruta antiga des de la qual migrar.

Les operacions s'escriuen com METHOD /path. Les taules del final d'aquesta pàgina enllacen cada operació nova i actualitzada amb la seva pàgina de l'API Reference.

Operacions noves

Cap d'aquestes operacions no està marcada amb x-irreversible. Les 27 escriptures accepten Idempotency-Key; és obligatòria a la vista prèvia, a la preparació i el renderitzat d'artefactes i a la pujada d'actius, i opcional a la resta.

• Biblioteca de plantilles (pdf_templates:read / pdf_templates:write) — GET|POST /v1/companies/{company}/pdf-templates, GET|PATCH /v1/companies/{company}/pdf-templates/{template}, POST /v1/companies/{company}/pdf-templates/{template}/revisions, /duplicate, /archive i /restore, GET /v1/companies/{company}/pdf-templates/{template}/impact i GET /v1/companies/{company}/pdf-templates/{template}/revisions/{revision}. Els valors per defecte de l'empresa són a GET|PATCH /v1/companies/{company}/pdf-templates/defaults, els de cada contacte a GET|PATCH /v1/companies/{company}/pdf-templates/contact-defaults/{contact}/{document_type}/{purpose}, i els logotips i imatges a POST /v1/companies/{company}/pdf-templates/assets i GET /v1/companies/{company}/pdf-templates/assets/{asset} (16 en total). El llistat usa page i per_page i respon { "items", "meta" }.
• Identitats comercials (mateixos scopes) — GET|POST /v1/companies/{company}/pdf-commercial-identities, GET|PATCH /v1/companies/{company}/pdf-commercial-identities/{identity}, POST .../{identity}/revisions, /archive i /restore, GET .../{identity}/impact i GET .../{identity}/revisions/{revision} (9 en total).
• Vista prèvia (pdfs:read i pdf_templates:read) — POST /v1/companies/{company}/pdf-template-previews renderitza una plantilla abans d'usar-la, a partir d'un exemple, un formulari sense desar, un esborrany desat, una revisió de presentació o una substitució de factura (el camp source). Retorna les metadades d'un artefacte de vista prèvia i respon 200, o 202 mentre el renderitzat és a la cua.
• Artefactes PDF (pdfs:read) — POST /v1/companies/{company}/pdf-artifacts prepara el PDF d'una presentació conservada, POST /v1/companies/{company}/pdf-artifacts/{artifact}/render el renderitza, GET /v1/companies/{company}/pdf-artifacts/{artifact} consulta el seu estat i GET /v1/companies/{company}/pdf-artifacts/{artifact}/download retorna els bytes amb ETag, 304 davant If-None-Match i 503 amb Retry-After mentre està pendent.
• Presentació de cada document — en factures, pressupostos, proformes i albarans (scope {document}:read|write): GET|PATCH /v1/companies/{company}/{documents}/{id}/presentation, GET /v1/companies/{company}/{documents}/{id}/presentation-history (paginat amb page i per_page) i POST /v1/companies/{company}/{documents}/{id}/presentation-revisions (16 en total).
• Plantilla d'una sèrie (series:read|write) — GET|PATCH /v1/companies/{company}/series/{series}/pdf-template.
• Revisions administratives d'una factura (invoices:read|write) — GET|POST /v1/companies/{company}/invoices/{invoice}/administrative-revisions revisen l'encaminament DIR3 d'una factura emesa o vençuda amb una comprovació de versió al cos.

Les nou operacions PATCH d'aquesta llista (plantilles, identitats, valors per defecte de l'empresa i dels contactes, les quatre presentacions de document i la plantilla de sèrie) accepten If-Match, i les operacions que retornen un sol recurs responen amb un ETag.

Tools MCP

El servidor MCP publica 51 tools noves: una per cada una d'aquestes operacions i generate_recurring_invoice per a l'operació de generació ja existent. L'empresa surt de la sessió MCP, així que les tools no porten argument company. Consulta el catàleg de tools.

• Reintents. Les 14 escriptures de la biblioteca, assign_*_presentation, revise_*_presentation, assign_series_pdf_template, prepare_pdf_artifact, render_pdf_artifact, preview_pdf_template i generate_recurring_invoice accepten idempotency_key: reutilitza la mateixa clau quan reintentis una crida perquè no s'apliqui dues vegades.
• Errors. Un rebuig que es produeix mentre s'executa una d'aquestes tools (per exemple pdf_presentation_not_ready, pdf_template_version_conflict o un 404) arriba com un resultat normal amb isError: true, i _meta["com.factuarea/error"] porta el mateix http_status, code i param que l'error REST. Decideix per code; Errors MCP en té la forma completa.
• Tools existents. accept_quote i accept_proforma segueixen la regla d'acceptació de les operacions REST (expected_presentation_uuid opcional, precondició només a la primera captura), i get_invoice_pdf, get_quote_pdf, get_proforma_pdf i get_delivery_note_pdf tornen a reclamar una renderització fallida reintentable en lloc de retornar la fallada anterior. create_invoice i update_invoice descriuen la regla de due_on de les factures amb terminis, i tota tool que emet una factura respon invoice_due_date_not_last_instalment si no es compleix; també schedule_invoice i reschedule_invoice, i duplicate_invoice desplaça els terminis amb la data d'emissió.

Scopes

Dos scopes nous, pdf_templates:read i pdf_templates:write, cobreixen la biblioteca i les identitats. Cap macro de scopes no els inclou. La vista prèvia necessita alhora pdfs:read i pdf_templates:read. La presentació dels documents reutilitza el scope del seu document. La biblioteca és el mòdul pdf_templates i l'editor avançat necessita pdf_templates_editor; consulta Accés. POST /v1/accounts/{account}/api-keys accepta els scopes nous a la seva llista scopes.

Canvis en operacions existents

Canvien de contracte 137 de les operacions existents. Són a les taules del final de la pàgina; aquests són els grups. Les operacions dels documents de control de transport que també canvien són a la seva pròpia publicació.

• Plantilla en escriure — crear i actualitzar de pressupostos, proformes i albarans, crear, actualitzar i rectificar de factures, i POST /v1/companies/{company}/invoices/substitute-simplified accepten pdf_template_id, amb expected_selection_version allà on hi ha una selecció anterior amb què comparar (no a la rectificativa ni a substitute-simplified). Les sèries accepten pdf_template_id en crear i actualitzar, més pdf_template_expected_version en actualitzar, i ara retornen pdf_template_id i pdf_template_version.
• Presentació a les respostes — factures, pressupostos, proformes i albarans porten presentation i pdf_output_state a tota resposta que retorna el document (llistat, consulta, creació, actualització, transicions, cerques i duplicats).
• Presentació amb revisions inactiva o activa — amb ella inactiva els camps de presentació (presentation_precondition, presentation_preconditions, pdf_template_uuid, expected_presentation_uuid, expected_selection_version i els altres expected_*) s'ignoren i el comportament és l'anterior a aquesta release. Amb ella activa es validen, i una plantilla indicada sense expected_selection_version, o un lliurament sense la seva precondició, respon 428. Els clients que no usen plantilles no es veuen afectats.
• Precondició de lliurament — issue i send de factures reben plans els set camps expected_*, purpose i format; send i accept de pressupostos, send i accept de proformes i send d'albarans reben presentation_precondition; les operacions bulk-send i bulk-status dels quatre documents reben presentation_preconditions. Les operacions de conversió declaren aquests camps com a no acceptats. Consulta la precondició de lliurament.
• Acceptació de pressupostos i proformes — POST /v1/companies/{company}/quotes/{quote}/accept i POST /v1/companies/{company}/proformas/{proforma}/accept només necessiten presentation_precondition a la primera captura: quan el document encara no té captura retinguda o el seu esborrany s'ha editat o ha canviat de plantilla després de capturar-se (sense l'objecte, 428 pdf_presentation_precondition_required i no s'escriu res). Un document que ja té captura retinguda s'accepta sense l'objecte; el camp opcional expected_presentation_uuid (nou als pressupostos) cita aquesta captura i respon 409 pdf_presentation_conflict si ja no és la vigent. Acceptar un esborrany el numera, també una proforma, i captura el que s'ha revisat. Els exemples de la petició són first_capture i retained_capture.
• pdf_presentation_not_ready és 422 — és una regla de negoci, no un permís. Decideix per code.
• Conflictes (409) — cap 409 d'aquesta release no canvia res: torna a llegir, revisa i repeteix. Les escriptures, transicions, conversions, duplicats, signatures i descàrregues de documents declaren pdf_presentation_conflict (la presentació ha canviat des que la vas llegir) i pdf_presentation_context_changed (el que vas revisar ja no coincideix amb el document). Les operacions de factura que lliuren o registren un fet fiscal (crear, issue, send, annul, void, corrective, substitute-simplified, mark-paid, mark-sent, els cobraments i la seva reversió, send-reminder, el ZIP i el correu trimestrals, i la generació d'una factura recurrent) declaren a més pdf_legal_source_changed. A la biblioteca, les escriptures amb expected_version declaren pdf_template_version_conflict (details.current_version i recovery: reload_or_keep_local), publicar i arxivar declaren pdf_library_impact_conflict, la pujada d'actius pdf_template_asset_conflict i crear i duplicar resource_conflict. La plantilla de la sèrie, la política de presentació d'una recurrent i el calendari de pagaments declaren el seu propi conflicte de versió.
• Enllaços públics — PATCH {document}/public-link accepta action: "publish" amb publication_context (presentation_id i expected_binding_version), i tant GET com PATCH retornen un bloc publication. Oberta sense selector de versió, la url de l'enllaç mostra ara la darrera versió que vas compartir amb publish, no la vinculada a la presentació vigent; publication.public_url sempre anomena la seva versió exacta, i un selector desconegut o privat respon 404 en lloc de recórrer a una altra versió. Consulta Enviament de documents.
• Signatura de l'albarà — signed_at a POST /v1/companies/{company}/delivery-notes/{id}/sign és obsolet i s'ignora: la data la fixa el servidor. signed_by admet fins a 120 caràcters. L'operació també rep els identificadors expected_* de la presentació que va veure qui signa.
• Factures — les respostes porten payment_terms (venciments), business_references de capçalera i de línia, legal_literals, el període de facturació i l'encaminament administrative_*. Les escriptures els accepten amb la semàntica ometre / null / [] de Dades de negoci de la factura, i expected_payment_terms_version protegeix el calendari d'una factura existent. Amb terminis, la factura venç el dia del seu últim termini: emetre-la amb un due_on absent o diferent respon 422 invoice_due_date_not_last_instalment, un esborrany conserva la data que enviïs i una actualització que substitueix payment_terms sense due_on el porta a l'últim termini. Una rectificativa sense calendari venç 30 dies després d'emetre's. Programar o reprogramar una factura (POST /v1/companies/{company}/invoices/{invoice}/schedule i PATCH /v1/companies/{company}/invoices/{invoice}/reschedule) comprova la mateixa regla i respon 422 invoice_due_date_not_last_instalment (param: due_on); la factura conserva el seu estat i la seva data. Duplicar una factura emet l'esborrany amb data d'avui: cada termini conserva el seu import i es desplaça els dies que hi ha entre les dues dates d'emissió, i due_on és l'últim termini desplaçat. El 422 de crear, actualitzar, rectificar i emetre comença pel text general de la validació de factures i al darrere enumera els codis de terminis. La factura ampliada també viatja dins de GET /v1/companies/{company}/events, GET /v1/companies/{company}/events/{event} i els lliuraments de webhook (llistat i consulta), així que canvien els seus payloads. Amb les plantilles revisionades, el bloc pdf de POST /v1/companies/{company}/invoices és la sortida retinguda de la presentació capturada en emetre, en el paper d'aquesta presentació (una simplificada pot ser un tiquet de 80 mm), i mentre és pending la seva url respon 503 pdf_artifact_not_ready amb Retry-After.
• Contactes — el perfil de client accepta i retorna el dir3_proponent opcional (rol 04), així que canvia tota operació que retorna un contacte.
• FacturaE i FACe — GET /v1/companies/{company}/invoices/{id}/facturae accepta submission_id, retorna ETag i X-Facturae-Sha256 quan l'artefacte està conservat i rebutja amb 422 una factura en esborrany o programada. POST /v1/companies/{company}/invoices/{id}/face-submissions accepta submission_id i respon 201 (intent nou), 200 (continuació o repetició) o 409 (per exemple face_transmission_uncertain). POST /v1/companies/{company}/invoices/{id}/send rep attach_facturae i submission_id. Consulta Facturació a FACe.
• Descàrregues i renderització de PDF — GET /v1/companies/{company}/{documents}/{id}/pdf i GET /v1/companies/{company}/invoices/{id}/pdf-link poden respondre 202 mentre es prepara el PDF, i 409 o 410 quan la font ha canviat o s'ha esborrat. Una renderització que ha fallat però es pot reintentar no es respon mai amb aquella fallada anterior: la descàrrega la torna a reclamar i respon 202, així que reintentar avança. Una renderització que ha fallat de manera definitiva respon 500 amb el seu codi (pdf_engine_profile_unavailable, pdf_payload_resource_unavailable, pdf_image_resource_unavailable) i no s'encua res. POST /v1/companies/{company}/pdf-artifacts/{artifact}/render i POST /v1/companies/{company}/pdf-template-previews només responen 200 amb un artefacte a punt: un que cap renderització no pot completar respon 500 amb el seu codi. Consulta com responen les descàrregues. Les quatre operacions bulk-pdf declaren X-Bulk-Total, X-Bulk-Successful i X-Bulk-Failed, i POST /v1/companies/{company}/invoices/quarterly/download-zip declara les seves capçaleres X-Quarterly-*.
• Recurrents i rectificatives — una factura recurrent porta una política de presentació (presentation_policy, presentation_policy_version, presentation_pause_reason) i payment_terms_template; una factura rectificativa hereta el que llista Factures rectificatives. Consulta també Factures recurrents.
• Altres declaracions — GET /v1/tax-catalog declara If-None-Match; POST /v1/companies/{company}/employees i POST /v1/companies/{company}/employees/{employee}/reactivate declaren la capçalera de correlació X-Request-Id al seu 503; POST /v1/companies/{company}/contacts/import i la seva vista prèvia declaren el límit del camp mapping; POST /v1/companies/{company}/contacts i el perfil de client declaren 409 idempotency_key_in_use (una altra petició amb la mateixa clau encara s'està executant); PATCH /v1/companies/{company}/delivery-notes/{delivery_note} deixa de declarar resource_conflict, perquè editar un albarà no el numera.

La marca sobre fons foscos i la mida de la marca

La revisió d'una identitat comercial té quatre claus més, que accepten POST /v1/companies/{company}/pdf-commercial-identities i POST /v1/companies/{company}/pdf-commercial-identities/{identity}/revisions i que retorna tota resposta d'identitat:

• logo_dark_asset_id i brand_image_dark_asset_id: versions opcionals del logotip i de la imatge de marca per a fons foscos. Cadascuna necessita la seva imatge base.
• dark_background_fallback: silhouette (per defecte) o plate.
• brand_size: small, medium (per defecte) o large.

Una marca no té adreça: contact_address no forma part de la seva configuració i el domicili de l'emissor al PDF és sempre el de l'empresa. Tampoc no hi ha un bloc a part de contacte comercial: quan la plantilla mostra el correu o el telèfon de l'empresa, el contact_email o el contact_phone de la marca el substitueix a la línia de contacte de l'emissor, i quan la plantilla l'amaga no en surt cap. Per això la marca sense desar d'una vista prèvia porta sis claus obligatòries.

Sobre un fons fosc (el marc del preajust corporative, la banda de la capçalera del document de control), la marca es pinta en aquest ordre: la seva versió per a fons fosc, si en té; la imatge tal com és, si es llegeix; si no, una silueta blanca, o la placa clara si la marca prefereix plate. Sobre un fons clar, una imatge que desapareixeria, com un logotip blanc, es pinta com una silueta negra. A la pràctica, puja el logotip en color com a base i el blanc com a versió per a fons fosc.

El configuration.branding.size d'una plantilla admet a més inherit, el valor de les plantilles noves, que pren el brand_size de la seva marca (medium si no en té). La vista prèvia accepta les quatre claus en una marca sense desar (commercial_identity amb mode: draft), i també les accepten les tools MCP create_pdf_commercial_identity, publish_pdf_commercial_identity_revision i preview_pdf_template. Els documents capturats abans conserven el seu aspecte. Consulta els fons foscos i la mida de la marca.

Textos de secció per idioma

footer_text, conditions_text i commercial_register_text del bloc sections de PdfTemplateConfiguration passen a ser objectes amb un text per idioma: { "es": "…", "en": "…", "ca": "…" }. Cada idioma és un text o null, amb els mateixos límits de sempre per idioma (500, 5.000 i 5.000 caràcters), i un text buit es guarda com a null.

• Lectura. Totes les respostes retornen sempre l'objecte. Un text guardat en la forma anterior, un string, es retorna com a { "es": text, "en": null, "ca": null }. Les revisions, captures i artefactes ja publicats no es reescriuen, de manera que la seva empremta no canvia.
• Escriptura. Crear i publicar accepten un string o l'objecte. Un string substitueix el text dels tres idiomes per aquest text a es. Un objecte parcial només canvia els idiomes que enviïs. Una clau desconeguda, com fr, retorna 422 invalid_pdf_template_configuration amb param configuration.sections.footer_text (o el camp que has enviat).
• Pintat. El PDF utilitza el text de l'idioma del document. Si és buit, utilitza el castellà, i si aquest també és buit, el bloc no es pinta. Un string es pinta igual als tres idiomes.

Operacions afectades: POST /v1/companies/{company}/pdf-templates i POST /v1/companies/{company}/pdf-templates/{template}/revisions (accepten totes dues formes), i GET /v1/companies/{company}/pdf-templates, GET /v1/companies/{company}/pdf-templates/{template}, PATCH /v1/companies/{company}/pdf-templates/{template}, GET /v1/companies/{company}/pdf-templates/{template}/revisions/{revision}, /duplicate, /archive, /restore i POST /v1/companies/{company}/pdf-template-previews (retornen o reben la configuració de la plantilla). Les tools MCP de la biblioteca segueixen el mateix contracte.

sections.notes_mode conserva els seus tres valors: auto imprimeix les notes del document quan en té, no les amaga i yes encara s'accepta i es comporta exactament com auto.

pdf_output_state a cada document

Les respostes d'Invoice, Quote, Proforma i DeliveryNote inclouen pdf_output_state, un resum de la sortida PDF conservada que mai no exposa snapshots, justificants ni rutes d'emmagatzematge. GET /v1/companies/{company}/{documents}/{id}/pdf també respon 202 mentre es prepara el PDF.

La clau sempre hi és. L'exemple del camp representa l'estat en què tots els valors són null:

{
  "state": null,
  "presentation_id": null,
  "artifact_id": null,
  "format": null,
  "variant": null,
  "unavailable_reason": null,
  "error": null,
  "retry_after": null,
  "download_url": null
}

Consulta com llegir-lo i reintentar.

Codis d'error

61 codis són nous; cap no canvia l'estat d'un codi existent. Els més rellevants:

idempotency_key_reused continua sent 422: reutilitzar una Idempotency-Key amb un altre cos, també a la vista prèvia i a les operacions d'artefactes, que comparen el cos cru byte a byte. Reenviar un cobrament desatès amb un external_id ja emès amb un altre tipus o total és un altre error, 409 unattended_replay_mismatch.

Decideix per code, mai per message. El catàleg d'errors els recull tots. Per MCP els mateixos codis arriben a _meta["com.factuarea/error"] d'un resultat amb isError: true.