Presentació de documents

La presentació d'un document és l'aspecte del seu PDF: quina plantilla, quina marca, quin format de paper. La presentació mai no canvia el contingut fiscal del document. L'acompanya en tres moments:

1. Mentre és un esborrany tries una plantilla (o deixes que s'hereti). Encara no es congela res.
2. En emetre'l o lliurar-lo Factuarea conserva la presentació que s'ha usat. A partir d'aquí l'original ja no es pot editar.
3. Després pots afegir una revisió de presentació: una nova presentació conservada, derivada de l'anterior i amb un motiu. L'historial és de només afegir.

Aquesta guia cobreix els quatre recursos que l'exposen (invoices, quotes, proformas i delivery_notes), la plantilla d'una sèrie, la precondició que demanen les operacions de lliurament i com recuperar-te de cada conflicte. Per construir les plantilles consulta Plantilles de documents, i per generar un PDF abans de comprometre res, Vistes prèvies de plantilles.

Les operacions

Cada recurs exposa les mateixes quatre operacions. {id} és l'UUID del document i el recurs és invoices, quotes, proformas o delivery-notes. 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.

{resource}:read i {resource}:write són els scopes que el document ja tenia: invoices:write per a factures, delivery_notes:write per a albarans, etc. La presentació no afegeix scopes a les operacions del document. La vista prèvia que alimenta una revisió necessita a més pdfs:read i pdf_templates:read. El servidor MCP exposa les mateixes operacions com get_invoice_presentation, assign_invoice_presentation, list_invoice_presentations i revise_invoice_presentation (i els seus equivalents quote, proforma i delivery_note), amb els scopes de dalt.

Les escriptures accepten un Idempotency-Key com qualsevol altra escriptura de la v1; consulta Idempotència. Cap d'aquestes operacions genera un PDF: mouen metadades i no consumeixen pressupost de PDF.

Llegeix l'estat

curl -i https://api.factuarea.com/v1/companies/$COMPANY_ID/invoices/0197c4a0-6b1e-7d52-8f3a-2c9d4e1b7a60/presentation \
  -H "Authorization: Bearer fact_test_3pXnR2VbY7TcA9eFmN5z8KqW"

HTTP/1.1 200 OK
ETag: "9f2c1b7e0a4d5c8e3b6a1f0d2c9e4b7a5d8c3f6e1a0b9d2c7e4f5a8b1c3d6e90"

{
  "data": {
    "id": null,
    "manual_template_id": null,
    "selection_version": 1,
    "pointer_version": 1,
    "binding_version": 1,
    "render_activation": "revisioned",
    "can_select": true,
    "can_revise": false,
    "capture_matches_source": null,
    "selection": {
      "document_type": "invoice",
      "document_id": "0197c4a0-6b1e-7d52-8f3a-2c9d4e1b7a60",
      "origin": "series",
      "template_id": "0197c4a1-02aa-7c31-9e5b-6d2f8a4c1b73",
      "revision_id": "0197c4a1-02ab-7e08-8a14-3b7c9d5e2f40",
      "presentation_id": null,
      "selection_version": 1,
      "base_preset": "modern",
      "layout_version": "1",
      "locale": "es",
      "selection_mode": "inherit",
      "purpose": "complete",
      "format": "a4",
      "contact_id": null,
      "commercial_identity_id": null,
      "commercial_identity_revision_id": null,
      "commercial_identity_version": null,
      "preview_context_fingerprint": "5d8c3f6e1a0b9d2c7e4f5a8b1c3d6e909f2c1b7e0a4d5c8e3b6a1f0d2c9e4b7a",
      "warnings": []
    },
    "captured_presentation": null,
    "selection_candidate": null,
    "selection_availability": { "selectable": true, "reason": null, "requires_confirmation": false },
    "warnings": [],
    "legal_source_changed": false
  }
}

L'estat té exactament quinze camps. Els que t'interessen:

Un document que mai no s'ha tocat té un estat virtual: id és null i les versions valen 1. Llegir mai no crea res.

Tria una plantilla en un esborrany

Un esborrany rep la plantilla de dues maneres. Totes dues fan servir el mateix selector, pdf_template_id:

pdf_template_uuid és la grafia de l'aplicació interna i l'API pública no l'accepta: només importa quan la presentació amb revisions està activada per a l'empresa, on enviar-la, o enviar els dos selectors, respon 422; en cas contrari s'ignora.

En crear (POST /v1/companies/{company}/invoices, /quotes, /proformas, /delivery-notes i les operacions rectificatives de factures) envia pdf_template_id. Encara no hi ha cap versió amb què comparar, així que expected_selection_version es rebutja quan POST /v1/companies/{company}/invoices crea una factura i en les operacions rectificatives. A /quotes, /proformas i /delivery-notes només importa quan el POST resol un external_id existent (un upsert): llavors és el CAS de la selecció i viatja amb pdf_template_id.

En actualitzar (PATCH /v1/companies/{company}/invoices/{id} i els seus germans) la plantilla i la seva versió viatgen juntes: pdf_template_id i expected_selection_version han d'estar presents totes dues o absents totes dues. Si en falta una, la resposta és 422 sobre expected_selection_version.

curl -X PATCH https://api.factuarea.com/v1/companies/$COMPANY_ID/quotes/0197c4b2-91de-7a40-b6c3-5e8f1d2a9c04 \
  -H "Authorization: Bearer fact_test_3pXnR2VbY7TcA9eFmN5z8KqW" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "pdf_template_id": "0197c4a1-02aa-7c31-9e5b-6d2f8a4c1b73",
    "expected_selection_version": 1
  }'

Amb el recurs de presentació canvies només la plantilla, sense tocar la resta del document. El cos té una clau obligatòria, template_id (un null explícit la treu), i una precondició: expected_version al cos, una capçalera If-Match amb l'ETag que has llegit, o totes dues.

curl -X PATCH https://api.factuarea.com/v1/companies/$COMPANY_ID/invoices/0197c4a0-6b1e-7d52-8f3a-2c9d4e1b7a60/presentation \
  -H "Authorization: Bearer fact_test_3pXnR2VbY7TcA9eFmN5z8KqW" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'If-Match: "9f2c1b7e0a4d5c8e3b6a1f0d2c9e4b7a5d8c3f6e1a0b9d2c7e4f5a8b1c3d6e90"' \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "0197c4a1-02aa-7c31-9e5b-6d2f8a4c1b73",
    "expected_version": 1
  }'

Respon 200 amb l'estat nou i el seu ETag nou. Triar la plantilla que ja està triada no canvia res i no mou la versió. La plantilla ha d'estar disponible per al document (una teva, publicada, no arxivada i compatible: una plantilla de factura per a una factura, amb un format que encaixi amb el propòsit del document); si no, no es desa res. Un document que ja no és un esborrany respon 422 pdf_presentation_invalid amb param: "presentation": a partir d'aquí fes servir una revisió.

Precedència i sèries

Un document sense elecció manual es resol per una escala fixa, i guanya el primer nivell que tingui una plantilla disponible:

1. La selecció manual del document. És exclusiva: si aquesta plantilla deixa d'estar disponible reps un error explícit, no cau al nivell següent.
2. La plantilla de la sèrie en què es numera el document.
3. La preferència del client (contacte) per a aquell tipus de document i propòsit.
4. El valor per defecte de l'empresa per a aquell tipus de document i propòsit.
5. El valor per defecte de l'empresa.
6. Els ajustos de PDF que l'empresa ja tenia (legacy), que sempre existeixen.

Un nivell heretat que no es pot usar (plantilla arxivada, pla sense la funcionalitat) se salta i s'informa com a avís a warnings, de manera que el document continua generant-se. Els nivells de client i d'empresa es configuren amb les operacions de biblioteca de Plantilles de documents.

La plantilla d'una sèrie

Una sèrie desa una plantilla opcional i una versió pròpia, independent de les dades de la sèrie:

curl https://api.factuarea.com/v1/companies/$COMPANY_ID/series/0197c4c3-17f0-7b92-a1d4-8e6b3c5f2a18/pdf-template \
  -H "Authorization: Bearer fact_test_3pXnR2VbY7TcA9eFmN5z8KqW"

{
  "data": {
    "id": "0197c4c3-17f0-7b92-a1d4-8e6b3c5f2a18",
    "object": "series_pdf_template",
    "pdf_template_id": null,
    "version": 1,
    "document_type": "invoice",
    "purpose": "complete",
    "is_series_archived": false,
    "template_state": null,
    "supported_formats": ["a4", "ticket_80", "ticket_58"],
    "availability": { "selectable": true, "reason": null },
    "warnings": []
  }
}

Fes un PATCH amb pdf_template_id (omet-lo per conservar, null per heretar, un UUID per assignar) i la precondició, expected_version i/o If-Match:

curl -X PATCH https://api.factuarea.com/v1/companies/$COMPANY_ID/series/0197c4c3-17f0-7b92-a1d4-8e6b3c5f2a18/pdf-template \
  -H "Authorization: Bearer fact_test_3pXnR2VbY7TcA9eFmN5z8KqW" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "pdf_template_id": "0197c4a1-02aa-7c31-9e5b-6d2f8a4c1b73",
    "expected_version": 1
  }'

• Assignar una plantilla mai no canvia la màscara de numeració, el comptador ni cap document ja emès. La preferència és només un valor per defecte per als documents nous.
• També viatja a la pròpia escriptura de la sèrie: POST /v1/companies/{company}/series accepta pdf_template_id, i PATCH /v1/companies/{company}/series/{series} accepta pdf_template_id amb pdf_template_expected_version (obligatori sempre que hi hagi el selector, fins i tot si és null o no canvia). La resposta de la sèrie retorna pdf_template_id i pdf_template_version. Consulta Sèries.
• Factures, pressupostos, proformes i albarans només poden usar una plantilla si és compatible amb el propòsit de la sèrie. Pressupostos, proformes i albarans fan servir A4 i el propòsit complete.
• Si la plantilla desada deixa de poder seleccionar-se (ha canviat el pla, s'ha arxivat la plantilla) la preferència es conserva, la lectura informa d' availability.selectable: false i de l'avís inherited_candidate_unavailable, i els documents nous cauen al nivell següent. Treure-la sempre està permès.
• Editar la plantilla de la sèrie exigeix l'autoritat vigent de l'emissor sobre les sèries: un administrador o un usuari sense la restricció d'ajustos de sèries. Si no, 403 series_template_access_denied.

La precondició de lliurament

Tan bon punt un document surt de l'esborrany se'n conserva la presentació, i per això les operacions que l'emeten o el lliuren et demanen confirmar el que has vist: la precondició. Quan la presentació amb revisions està activa per a la teva empresa i la petició no porta precondició, l'operació respon 428 pdf_presentation_precondition_required i no passa res.

Què conté

Set camps, tots obligatoris alhora (dos admeten null, però mai no poden faltar):

Obtén l'artefacte amb una vista prèvia de l'esborrany desat: POST /v1/companies/{company}/pdf-template-previews amb source: { "kind": "persisted_draft", "document_id": "<uuid>" }. La vista prèvia no congela res: mostra el que seria el document ara mateix i retorna els valors que cal confirmar. Si l'esborrany canvia després (línies, client, sèrie, plantilla), aquests valors queden obsolets i el pas següent falla a propòsit.

On va

curl -X POST https://api.factuarea.com/v1/companies/$COMPANY_ID/quotes/0197c4b2-91de-7a40-b6c3-5e8f1d2a9c04/send \
  -H "Authorization: Bearer fact_test_3pXnR2VbY7TcA9eFmN5z8KqW" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "compras@cliente.example",
    "presentation_precondition": {
      "expected_selection_version": 2,
      "expected_source_token": "3b6a1f0d2c9e4b7a5d8c3f6e1a0b9d2c7e4f5a8b1c3d6e909f2c1b7e0a4d5c8e",
      "expected_preview_context_fingerprint": "5d8c3f6e1a0b9d2c7e4f5a8b1c3d6e909f2c1b7e0a4d5c8e3b6a1f0d2c9e4b7a",
      "expected_template_revision_id": "0197c4a1-02ab-7e08-8a14-3b7c9d5e2f40",
      "expected_commercial_identity_revision_id": null,
      "purpose": "complete",
      "format": "a4"
    }
  }'

Amb la presentació amb revisions no activa, aquests camps s'ignoren, igual que pdf_template_id i expected_selection_version en crear, actualitzar i duplicar: la petició es comporta exactament com abans de la funció i mai no respon pdf_presentation_not_ready per aquests camps. Quan és activa es validen.

Acceptar un pressupost o una proforma. L'objecte presentation_precondition només és obligatori a la primera captura: quan el document encara no té captura retinguda (no s'ha compartit mai) o el seu esborrany s'ha editat o ha canviat de plantilla després de capturar-se. Sense l'objecte, la petició respon 428 pdf_presentation_precondition_required abans d'escriure res. Un document que ja té captura retinguda (en una proforma, la d'un enviament com a esborrany) s'accepta sense l'objecte i aquesta captura segueix el número; cita-la amb el camp opcional expected_presentation_uuid, que respon 409 pdf_presentation_conflict si ja no és la vigent. Acceptar un esborrany el numera i captura el que s'ha revisat.

Les operacions de conversió (POST /v1/companies/{company}/quotes/{quote}/convert, POST /v1/companies/{company}/proformas/{proforma}/convert, POST /v1/companies/{company}/delivery-notes/{delivery_note}/convert) no porten precondició (tampoc POST /v1/companies/{company}/invoices/{invoice}/duplicate): enviar-la respon 422 quan la presentació amb revisions és activa i s'ignora en cas contrari. La factura que creen és un document nou la plantilla del qual es resol per precedència. L'acceptació d'un pressupost o una proforma i l'enviament d'un albarà també poden indicar la presentació que ha rebut el client amb expected_presentation_uuid (l'id de la presentació conservada); l'enviament d'un albarà admet a més expected_publication_id, la publicació que ha rebut el client. Al cos de l'enviament d'un albarà, template_id és la plantilla de correu heretada i no té res a veure amb pdf_template_id.

En un lot

Una operació massiva no falla en bloc. Cada document sense la seva entrada (o amb una d'obsoleta) s'informa a failures[] amb el seu propi error_code, aquí pdf_presentation_precondition_required o pdf_presentation_context_changed, i els altres continuen endavant. Consulta Operacions massives.

Revisa després d'emetre

Quan un document s'emet, es lliura o s'accepta, la seva presentació conservada ja no es pot editar. Per canviar l'aspecte del PDF afegeixes una revisió. Copia la presentació conservada anterior i canvia només el que demanis:

• La plantilla (template_id): omet-la per mantenir la del pare, null per heretar o un UUID.
• Opcionalment purpose i format. L'idioma és sempre el del pare.
• source_policy: captured conserva les dades legals exactament com es van conservar; current_legal actualitza els camps d'identificació de l'emissor i del destinatari amb les dades actuals. El legal_source_changed de l'estat et diu quan importa.

Una revisió mai no torna a emetre el document, mai no canvia numeració, imports ni el registre de VeriFactu, i mai no esborra una presentació anterior.

Com que crea evidència conservada, exigeix una prova que has mirat el resultat. Demana una vista prèvia amb source.kind: "presentation_revision", el mateix document_id, parent_id, template_id, source_policy i expected_version, i fes servir l'artefacte que retorni:

curl -X POST https://api.factuarea.com/v1/companies/$COMPANY_ID/invoices/0197c4a0-6b1e-7d52-8f3a-2c9d4e1b7a60/presentation-revisions \
  -H "Authorization: Bearer fact_test_3pXnR2VbY7TcA9eFmN5z8KqW" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "parent_id": "0197c4d4-3a21-7f16-9b8e-1c5d7a2e4f90",
    "expected_version": 1,
    "template_id": "0197c4a1-02aa-7c31-9e5b-6d2f8a4c1b73",
    "source_policy": "captured",
    "reason": "El cliente pide la plantilla corporativa para su archivo.",
    "expected_source_token": "3b6a1f0d2c9e4b7a5d8c3f6e1a0b9d2c7e4f5a8b1c3d6e909f2c1b7e0a4d5c8e",
    "expected_preview_context_fingerprint": "5d8c3f6e1a0b9d2c7e4f5a8b1c3d6e909f2c1b7e0a4d5c8e3b6a1f0d2c9e4b7a",
    "expected_template_revision_id": "0197c4a1-02ab-7e08-8a14-3b7c9d5e2f40",
    "expected_commercial_identity_revision_id": null
  }'

Respon 201 amb la nova presentació conservada i l'estat actualitzat:

{
  "data": {
    "presentation": {
      "id": "0197c4d5-8e02-7a63-8c1f-4b9d2e6a3f15",
      "number": 2,
      "parent_id": "0197c4d4-3a21-7f16-9b8e-1c5d7a2e4f90",
      "kind": "derived",
      "derivation_kind": "visual_revision",
      "created_at": "2026-10-14T09:42:17.000000Z",
      "reason": "El cliente pide la plantilla corporativa para su archivo.",
      "template_id": "0197c4a1-02aa-7c31-9e5b-6d2f8a4c1b73",
      "revision_id": "0197c4a1-02ab-7e08-8a14-3b7c9d5e2f40",
      "origin": "manual",
      "locale": "es",
      "purpose": "complete",
      "format": "a4",
      "source_kind": "captured",
      "availability": "captured",
      "unavailable_reason": null
    },
    "state": { "id": "0197c4d5-8e02-7a63-8c1f-4b9d2e6a3f15", "pointer_version": 2 }
  }
}

(state és l'objecte complet de l'estat; aquí apareix abreujat.)

L'historial llista els mateixos resums, amb meta.total:

curl "https://api.factuarea.com/v1/companies/$COMPANY_ID/invoices/0197c4a0-6b1e-7d52-8f3a-2c9d4e1b7a60/presentation-history?per_page=10" \
  -H "Authorization: Bearer fact_test_3pXnR2VbY7TcA9eFmN5z8KqW"

kind és original, derived o legacy_observed (un document anterior a les presentacions conservades: observat, mai inventat). derivation_kind indica com s'ha fet una derivada: visual_revision, legal_snapshot_refresh, legal_qr o signature_capture. availability és captured mentre la instantània es pot llegir; si les dades de la signatura d'un albarà s'han esborrat per privacitat, les metadades es conserven i availability passa a unavailable amb unavailable_reason: "privacy_erased". Revisar a partir d'aquesta presentació respon 410 pdf_signature_personal_data_forgotten.

Una revisió és evidència sobre la presentació; no vol dir que els bytes del PDF ja existeixin. La descàrrega i la generació de documents s'expliquen a Vistes prèvies de plantilles.

ETag, If-Match i recuperació

La presentació fa servir tres proteccions. Responen a preguntes diferents, així que el client ha de saber quina ha fallat:

Regles que valen per a tots els PATCH:

• L'etiqueta és l'ETag fort d'aquella mateixa URL (GET/PATCH de .../presentation o .../pdf-template), mai l'etiqueta del document, d'un PDF ni d'un altre recurs. Un validador feble (W/"...") no coincideix mai.
• Si envies totes dues, primer s'avalua l'etiqueta (412) i després la versió (409).
• L'operació de revisió no accepta If-Match; la seva protecció és expected_version al cos (422 si envies la capçalera).
• Els errors fan servir l'embolcall habitual. Ramifica segons code; param assenyala la protecció (if_match, expected_version, expected_preview_context_fingerprint). El conflicte de sèrie afegeix details.current_version i details.recovery: "reload_or_keep_local".

{
  "error": {
    "type": "conflict_error",
    "code": "pdf_presentation_conflict",
    "message": "La presentación documental ha cambiado. Actualiza los datos antes de volver a guardar.",
    "param": "expected_version",
    "request_id": "req_01JBVH7K9Y4N3CDQ2EHJB1AGSV",
    "doc_url": "https://docs.factuarea.com/guides/errors#pdf_presentation_conflict"
  }
}

Errors

Relacionat

• Plantilles de documents: construeix i gestiona les plantilles i les marques.
• Vistes prèvies de plantilles: la vista prèvia que produeix els valors d'una precondició.
• Dades de negoci de la factura: les dades estructurades que un document porta a cada presentació.
• Enviament de documents: correu, enllaços públics i la resta de canals de lliurament.
• Operacions massives i Idempotència.