Biblioteca de plantilles PDF

La biblioteca de plantilles PDF és on la teva empresa guarda els dissenys i les marques que donen forma al PDF de cada document que genera l’API. Crees una plantilla (maquetació, preajust, columnes, textos), li assignes una identitat comercial (logotip i marca) i decideixes on s’aplica: com a valor per defecte de l’empresa, per tipus de document, per sèrie o per contacte.

Tot el que hi ha a la biblioteca està versionat. Una plantilla o una identitat és una capçalera (nom, estat, version) que apunta a la seva revisió actual; una revisió és una instantània immutable del disseny o de la marca. Publicar mai no edita una revisió: n’afegeix la següent. Un document conserva el PDF amb què es va capturar: canviar, arxivar o restaurar recursos de la biblioteca només afecta els documents que creïs o revisis després.

Totes les rutes d’aquesta guia pengen de /v1/companies/{company}/…: {company} és l’id (UUID v7) del NIF amb què operes, i als exemples curl és $COMPANY_ID. Arribar a un NIF explica com resoldre’l.

Els recursos de la biblioteca es retornen com a objecte pla (sense l’embolcall data) i els llistats com { "items": [...], "meta": { "page", "per_page", "total" } }. Tots els identificadors són UUID v7 i s’exposen com a id.

Accés: mòdul, pla, scopes i rols

• Rols. Les lectures estan obertes als rols admin i user de l’empresa; les escriptures i la lectura de l’impacte exigeixen admin. Un employee rep 403 pdf_template_access_denied. Una API key actua amb el rol de l’usuari al qual pertany, i el rol i les restriccions de mòdul es tornen a comprovar a cada petició.
• Mòdul i pla. La biblioteca és el mòdul pdf_templates, disponible a Esencial, Profesional, Avanzado i Enterprise. L’editor avançat (tipografia, colors, columnes, maquetació de pàgina i els preajusts corporative i premium) és el mòdul pdf_templates_editor, inclòs des de Profesional. Sense ell pots continuar gestionant plantilles que només canvien la marca sobre els preajusts classic, modern i minimal; qualsevol altre canvi retorna 403 feature_not_available_in_plan. Llegeix pdf_capabilities a la personalització del compte per saber-ho per endavant. Un downgrade conserva el que ja havies desat; només els canvis avançats nous necessiten l’editor.
• Mode de prova. La biblioteca funciona igual amb claus fact_test_ i fact_live_.

Plantilles

Crear una plantilla

POST /v1/companies/{company}/pdf-templates crea una plantilla amb la seva primera revisió. Només name és obligatori; la resta té valors per defecte.

configuration és un objecte tancat amb els grups branding (mode: logo, imago o none; size: small, medium, large o inherit, consulta la mida de la marca), typography, colors, page, watermark, titles, columns, company_fields, client_fields, custom_field_definitions i sections. Una clau desconeguda, un tipus incorrecte o un valor fora de rang es rebutja amb 422 invalid_pdf_template_configuration i el param assenyala la ruta exacta, per exemple configuration.typography.font_size. Quan branding.mode és logo o imago, la plantilla necessita una marca efectiva: el seu propi commercial_identity_id o una identitat per defecte de l’empresa que estigui activa. Si no n’hi ha, la petició retorna 422 pdf_commercial_identity_required.

curl -X POST https://api.factuarea.com/v1/companies/$COMPANY_ID/pdf-templates \
  -H "Authorization: Bearer fact_test_3pXnR2VbY7TcA9eFmN5z8KqW" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Invoices with logo",
    "base_preset": "modern",
    "supported_types": ["invoice"],
    "commercial_identity_id": "0199f39e-1a20-7f6b-a2c8-3d5e9b0c4a71",
    "configuration": { "branding": { "mode": "logo", "size": "medium" } }
  }'

La resposta és 201 amb la plantilla i una capçalera ETag (abreujada aquí):

{
  "id": "0199f3a2-7c4e-7b1a-9d3e-5a2c8f1b6e40",
  "name": "Invoices with logo",
  "description": null,
  "state": "active",
  "version": 1,
  "availability": { "selectable": true, "reason": null },
  "supported_types": ["invoice"],
  "supported_purposes": { "invoice": ["complete", "simplified", "corrective", "simplified_corrective"] },
  "supported_formats": ["a4"],
  "commercial_identity_id": "0199f39e-1a20-7f6b-a2c8-3d5e9b0c4a71",
  "current_revision": {
    "id": "0199f3a2-7c52-7d03-8a41-6b9e0c2d7f15",
    "template_id": "0199f3a2-7c4e-7b1a-9d3e-5a2c8f1b6e40",
    "number": 1,
    "base_preset": "modern",
    "layout_version": "1",
    "schema_version": 1,
    "configuration": { "...": "complete normalized configuration" }
  },
  "created_at": "2026-10-14T09:12:41.000000Z",
  "updated_at": "2026-10-14T09:12:41.000000Z"
}

Llistar i llegir

• GET /v1/companies/{company}/pdf-templates accepta q (cerca per nom), state (active per defecte, archived o all), document_type, purpose, format, page i per_page (d’1 a 100, per defecte 25). Els resultats surten ordenats per nom. Un filtre no vàlid retorna 422 amb el filtre a param; mai s’ignora en silenci.
• GET /v1/companies/{company}/pdf-templates/{template} retorna la plantilla amb la seva revisió actual i l’ETag que necessites per al següent PATCH.
• GET /v1/companies/{company}/pdf-templates/{template}/revisions/{revision} retorna una revisió exacta, també les arxivades.

Canviar el nom: només metadades

PATCH /v1/companies/{company}/pdf-templates/{template} canvia únicament name i description (description: null l’esborra). Mai no toca el disseny: enviar configuration aquí és un 422. Una petició que no canvia res no crea cap versió nova. La precondició és obligatòria, vegeu concurrència.

curl -X PATCH https://api.factuarea.com/v1/companies/$COMPANY_ID/pdf-templates/0199f3a2-7c4e-7b1a-9d3e-5a2c8f1b6e40 \
  -H "Authorization: Bearer fact_test_3pXnR2VbY7TcA9eFmN5z8KqW" \
  -H "Content-Type: application/json" \
  -H 'If-Match: "00295d3c3bb1b0b0ce5187e46fc6af39f41f507558608c8d14312fba4a710dc6"' \
  -d '{ "name": "Invoices with logo (2026)" }'

Publicar una revisió

Canviar el disseny vol dir publicar una revisió nova, en dos passos.

1. Demana l’impacte: GET /v1/companies/{company}/pdf-templates/{template}/impact?action=publish. La resposta enumera les associacions que apunten a la plantilla (company_default, type_default, contact_default, series i recurring), els retained_counts de presentacions, sortides preparades i ancoratges que queden intactes, els warnings si n’hi ha, i un impact_fingerprint.
2. Publica amb POST /v1/companies/{company}/pdf-templates/{template}/revisions, enviant l’expected_version de la plantilla, aquest expected_impact_fingerprint i almenys un canvi entre base_preset, commercial_identity_id, supported_types, supported_purposes, supported_formats i configuration.

Els objectes de configuration es combinen en profunditat sobre la revisió actual; les llistes com columns o custom_field_definitions se substitueixen per complet. La resposta és 201 amb la revisió nova, i la version de la plantilla puja una unitat. Si les associacions han canviat entre les dues crides, l’empremta ja no coincideix i reps 409 pdf_library_impact_conflict: torna a llegir l’impacte i decideix.

curl -X POST https://api.factuarea.com/v1/companies/$COMPANY_ID/pdf-templates/0199f3a2-7c4e-7b1a-9d3e-5a2c8f1b6e40/revisions \
  -H "Authorization: Bearer fact_test_3pXnR2VbY7TcA9eFmN5z8KqW" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "expected_version": 2,
    "expected_impact_fingerprint": "b8a9f15005a46cf651f5652419b2edba941b3090090a1934a96f37c9cd0b973f",
    "configuration": { "page": { "show_page_numbers": true }, "sections": { "footer_text": "Thank you for your business" } }
  }'

Els documents nous es resolen amb la revisió nova. Els documents ja capturats, les sortides preparades i els ancoratges de les factures recurrents conserven la revisió que tenien.

Duplicar

POST /v1/companies/{company}/pdf-templates/{template}/duplicate amb name i l’expected_version de l’origen crea una plantilla nova (version 1, revisió 1, active) amb la configuració actual de l’origen. L’origen pot estar arxivat; la còpia sempre neix activa. La còpia no hereta valors per defecte, assignacions de sèries ni preferències de contacte, i necessita la marca que l’origen necessitaria avui (les capacitats del pla es comproven en el moment de copiar).

Arxivar i restaurar

Una plantilla arxivada continua sent llegible i conserva les seves revisions i actius, però ja no es pot seleccionar (availability.selectable és false).

1. GET /v1/companies/{company}/pdf-templates/{template}/impact?action=archive retorna les associacions que en depenen i una empremta.

2. POST /v1/companies/{company}/pdf-templates/{template}/archive amb expected_version, expected_impact_fingerprint i replacements, una llista (pot anar buida) amb una decisió per cada associació l’action de la qual sigui replace_or_clear o pause:

   Decisió	Camps
   Substituir per una altra plantilla	{ "key", "expected_version", "action": "replace", "replacement_id" }
   Treure el vincle	{ "key", "expected_version", "action": "clear", "replacement_id": null }
   Posar en pausa (factures recurrents que segueixen l’última plantilla)	{ "key", "expected_version", "action": "pause", "replacement_id": null }

   Copia key i version de l’associació tal com els va retornar l’impacte; key és opaca. Les associacions marcades retained no necessiten decisió.

Cada decisió i cada associació es validen abans de canviar res, i l’arxivament s’aplica com un únic canvi atòmic. Si falta una decisió es retorna 422 pdf_template_default_replacement_required. POST /v1/companies/{company}/pdf-templates/{template}/restore (només expected_version) torna a activar la plantilla; no reinstal·la els valors per defecte, els vincles de sèrie ni les preferències de contacte que l’arxivament va substituir o treure.

Identitats comercials

Una identitat comercial és la marca que mostra una plantilla. Té el mateix cicle de vida que una plantilla, amb les mateixes operacions sota /v1/companies/{company}/pdf-commercial-identities: GET (llistat, amb q, state, page, per_page), POST (crear), GET /{identity}, PATCH /{identity} (nom i descripció), GET /{identity}/impact, POST /{identity}/revisions, POST /{identity}/archive, POST /{identity}/restore i GET /{identity}/revisions/{revision}.

La marca viu a configuration, que accepta exactament aquestes claus:

Totes les claus admeten null excepte dark_background_fallback i brand_size. Una marca no té adreça: el domicili de l’emissor al PDF és sempre el de l’empresa, una dada legal que la marca no pot substituir.

Els actius han de ser de la teva empresa i del tipus correcte; si no, la petició falla (404 pdf_template_asset_not_found o 422). Publicar una revisió demana expected_version, expected_impact_fingerprint i una configuration parcial amb almenys una clau. L’impacte d’una marca també enumera les plantilles que la fan servir (associacions template), i arxivar-la demana una decisió per associació, exactament igual que arxivar una plantilla (la decisió sobre una associació template també pot dur revision_id).

curl -X POST https://api.factuarea.com/v1/companies/$COMPANY_ID/pdf-commercial-identities \
  -H "Authorization: Bearer fact_test_3pXnR2VbY7TcA9eFmN5z8KqW" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Main brand",
    "configuration": {
      "commercial_name": "Acme Studio",
      "logo_asset_id": "0199f39d-52b1-7e34-9c07-1f6a8d3b2e90",
      "logo_dark_asset_id": "0199f39d-6a14-7c52-8e31-2b7c9e4d1f05",
      "brand_mode": "logo",
      "contact_email": "hello@acme.example"
    }
  }'

La marca sobre fons foscos

Alguns dissenys posen la marca sobre un fons fosc, com el marc del preajust corporative o la banda de la capçalera del document de control. A cada captura nova, la imatge que mostra la plantilla (la de brand_mode) es pinta en aquest ordre:

1. La versió per a fons fosc, si la marca en té. Sobre un fons fosc, logo_dark_asset_id (o brand_image_dark_asset_id per a la imatge de marca) es pinta tal com és. Sobre el paper no s’utilitza.
2. La imatge tal com és, si es llegeix. Una imatge amb fons propi (un JPEG, o un PNG sense transparència) es pinta tal com és, i també una amb una tinta que contrasta amb el fons.
3. Si no, una silueta o la placa. Sobre un fons fosc decideix dark_background_fallback: silhouette (per defecte) pinta la forma de la marca en blanc, i plate la posa sobre una placa clara, sempre que s’hi llegeixi (si no, la silueta blanca).
4. Sobre un fons clar, com el paper, una imatge que desapareixeria (un logotip blanc, per exemple) es pinta com una silueta negra.

La silueta conserva la forma i la transparència de la imatge; només canvia el color de la seva tinta. A la pràctica: puja el teu logotip en color com a logo_asset_id i la seva versió blanca com a logo_dark_asset_id. Els documents capturats abans d’aquesta regla conserven l’aspecte amb què es van capturar.

La mida de la marca

brand_size és la mida per defecte de la marca: small, medium (per defecte) o large. Una plantilla fixa la seva a configuration.branding.size, o fa servir inherit, el valor de les plantilles noves, per prendre la mida de la seva marca; sense marca, medium. Les plantilles que ja guardaven una mida la conserven. Cada mida és una superfície òptica de la tinta, no una caixa màxima: un logotip apaïsat baixa d’alçada i guanya amplada, un de vertical creix una mica d’alçada, i el marge transparent que envolta la imatge no compta. La mateixa mida s’aplica a tots els dissenys, al tiquet i al document de control.

Pujar actius

POST /v1/companies/{company}/pdf-templates/assets puja un logotip o una imatge de marca com a multipart/form-data. Idempotency-Key és obligatòria en aquesta operació.

curl -X POST https://api.factuarea.com/v1/companies/$COMPANY_ID/pdf-templates/assets \
  -H "Authorization: Bearer fact_test_3pXnR2VbY7TcA9eFmN5z8KqW" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F kind=logo \
  -F file=@logo.png

{
  "id": "0199f39d-52b1-7e34-9c07-1f6a8d3b2e90",
  "kind": "logo",
  "mime": "image/png",
  "sha256": "7a265f5f003866f84e23c7e237301879b7d4a4ecc0ab80d2041a3c980b12310a",
  "size_bytes": 18342,
  "created_at": "2026-10-14T09:05:12.000000Z"
}

Els actius són privats i immutables; GET /v1/companies/{company}/pdf-templates/assets/{asset} retorna aquestes metadades en JSON, mai una ruta d’emmagatzematge. Amb una capçalera Accept image/* retorna els bytes desats en línia, amb Cache-Control: private, no-store. En JPEG i PNG s’eliminen les metadades EXIF, GPS i de text. Arxivar una plantilla o una marca no n’esborra els actius, i cada actiu compta una sola vegada per a l’espai d’emmagatzematge encara que el comparteixin diverses marques.

Per MCP, upload_pdf_template_asset rep la imatge com a image_base64 (fins a 2048 KiB ja descodificada), el mime declarat (image/jpeg, image/png o image/webp) i un filename.

Valors per defecte de l’empresa

GET /v1/companies/{company}/pdf-templates/defaults retorna el registre únic de la teva empresa:

{
  "id": "0199e0aa-4b10-7c33-9a52-6d8e1f3b7a24",
  "version": 1,
  "company_template_id": null,
  "company_commercial_identity_id": null,
  "type_defaults": [],
  "render_activation": "legacy"
}

Mentre no escriguis res, la lectura és virtual: id és l’UUID de la teva empresa, version és 1 i no hi ha res desat. El primer PATCH /v1/companies/{company}/pdf-templates/defaults el desa a version 2.

• Un camp omès conserva el seu valor i null l’esborra.
• type_defaults substitueix la llista sencera: envia totes les entrades que vulguis conservar. El format de paper no forma part de la clau.
• render_activation no s’accepta mai: enviar-lo, fins i tot com a null, és un 422. Forma part de la representació, així que quan canvia també canvia l’ETag i un If-Match caducat respon 412 com toca.

curl -X PATCH https://api.factuarea.com/v1/companies/$COMPANY_ID/pdf-templates/defaults \
  -H "Authorization: Bearer fact_test_3pXnR2VbY7TcA9eFmN5z8KqW" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "expected_version": 1,
    "company_template_id": "0199f3a2-7c4e-7b1a-9d3e-5a2c8f1b6e40",
    "type_defaults": [
      { "document_type": "quote", "purpose": "complete", "template_id": "0199f3b0-2a41-7c88-9e02-d4f6a8b1c3e5" }
    ]
  }'

Una plantilla arxivada no pot ser valor per defecte (422 pdf_template_archived), i una plantilla que no admet el tipus de document o el propòsit es rebutja amb 422.

L’ajust clàssic pdf_template de la personalització del compte és una altra capa, anterior. Aquests valors per defecte no la substitueixen: vegeu quina plantilla fa servir un document.

Valors per defecte per contacte

Un contacte pot preferir una plantilla per a cada tipus de document i propòsit:

• GET /v1/companies/{company}/pdf-templates/contact-defaults/{contact}/{document_type}/{purpose}
• PATCH /v1/companies/{company}/pdf-templates/contact-defaults/{contact}/{document_type}/{purpose}

document_type és invoice, quote, proforma o delivery-note, i purpose ha de pertànyer a aquest tipus (en factures complete, simplified, corrective o simplified_corrective; en els altres tipus complete).

{
  "id": "0199f2c1-8d10-7a55-8b3e-4c7d2e9f1a06",
  "document_type": "invoice",
  "purpose": "complete",
  "template_id": null,
  "version": 1,
  "persisted": false
}

id és el contacte. Si el contacte es va fusionar amb un altre, configura el contacte resultant: la preferència del fusionat no s’hereta. El contacte ha de ser un client de la teva empresa. Sense preferència desada la lectura és virtual (version 1, persisted: false); la primera escriptura la desa a version 2. PATCH rep template_id (null l’esborra) i la precondició. Un contacte desconegut o d’una altra empresa retorna 404, idèntic al d’un contacte inexistent.

Quina plantilla fa servir un document

Quan es crea, s’emet o s’envia un document, Factuarea tria la seva plantilla amb aquest ordre, i guanya el primer nivell que tingui una plantilla disponible per al tipus de document, el propòsit i el format de paper:

1. Selecció manual al document (selection_mode: manual). És exclusiva: si aquesta plantilla ja no està disponible l’operació falla, mai no recorre al nivell següent.
2. Valor per defecte de la sèrie, amb GET i PATCH /v1/companies/{company}/series/{series}/pdf-template.
3. Valor per defecte del contacte canònic.
4. Valor per defecte de l’empresa per al tipus de document i el propòsit (type_defaults).
5. Plantilla per defecte de l’empresa (company_template_id).
6. Legacy: la personalització del compte (pdf_template, accent_color, logotip) i el renderitzador clàssic.

Si un nivell heretat apunta a una plantilla arxivada o incompatible, es passa al nivell següent i el document informa d’un avís a presentation.warnings: pdf_series_template_unavailable quan era la sèrie i pdf_inherited_candidate_unavailable per a qualsevol altre nivell heretat. La marca es resol a part: el commercial_identity_id propi de la plantilla i, si no en té, la identitat per defecte de l’empresa. Com llegeix i canvia un document concret la seva selecció és a Presentacions de document.

Concurrència: versions, ETag i If-Match

Tot recurs mutable de la biblioteca té una version, i tota representació que després pots canviar porta un ETag fort: el SHA-256 del seu JSON complet, de manera que també canvia quan canvien availability o render_activation. Les mateixes regles valen per a plantilles, identitats, valors per defecte de l’empresa i valors per defecte per contacte.

Si envies les dues en un PATCH, primer s’avalua l’etiqueta i després la versió. If-Match accepta una o diverses etiquetes d’entitat, les febles (W/"...") i *.

Un conflicte mai no canvia el recurs, i current_version només surt del recurs de la teva pròpia empresa. Les sèries fan servir el mateix patró amb els seus propis codis: series_template_precondition_failed, series_template_version_conflict i series_template_precondition_required.

Idempotència

Idempotency-Key és obligatòria a POST /v1/companies/{company}/pdf-templates/assets i opcional, però recomanada, a la resta d’escriptures de la biblioteca. Una repetició amb la mateixa clau i el mateix cos retorna la resposta desada amb Idempotent-Replayed: true abans de la comprovació de versió, de manera que un reintent després d’un timeout no falla amb 409 perquè el teu propi primer intent ja va avançar la versió. L’autorització es comprova de nou abans de repetir: si has perdut el rol o l’accés, reps l’error d’autorització, no la resposta desada. Reutilitzar una clau amb un altre cos retorna 422 idempotency_key_reused. Consulta Idempotència per a la finestra i el format.

Errors

Ramifica segons code, mai segons message. Consulta el model d’errors.

MCP

La biblioteca té una tool MCP per operació: list_pdf_templates, get_pdf_template, create_pdf_template, update_pdf_template, publish_pdf_template_revision, duplicate_pdf_template, archive_pdf_template, restore_pdf_template, get_pdf_template_impact, get_pdf_template_revision, els equivalents de les marques sense duplicació (list_pdf_commercial_identities, get_pdf_commercial_identity, create_pdf_commercial_identity, update_pdf_commercial_identity, publish_pdf_commercial_identity_revision, archive_pdf_commercial_identity, restore_pdf_commercial_identity, get_pdf_commercial_identity_impact i get_pdf_commercial_identity_revision), get_pdf_template_defaults, set_pdf_template_defaults, get_pdf_template_contact_default, set_pdf_template_contact_default, upload_pdf_template_asset i get_pdf_template_asset. Necessiten els mateixos scopes i rols, reben la versió com a expected_version als arguments (a MCP no hi ha capçaleres) i accepten idempotency_key. Consulta les tools MCP.