PDF template library and structured invoices

19 October 2026 (provisional: the final date is the day this release is published) — The API now exposes the PDF template library of the app, the presentation each document retains, the exact PDF artifacts, and the structured business data of an invoice. Four guides explain the whole model: PDF template library, Document presentations, PDF previews and artifacts and Invoice business data.

Every operation of this release hangs off the company axis, /v1/companies/{company}/…, where {company} is the id (UUID v7) of the tax ID you operate on; reach a tax ID explains it. None of the new operations was ever published at the root of /v1: they are new, not moved, so there is no old path to migrate from.

Operations are written as METHOD /path. The tables at the end of this page link every new and updated operation to its API Reference page.

New operations

None of these operations is marked x-irreversible. All 27 writes accept Idempotency-Key; it is required on the preview, the artifact preparation, the artifact render and the asset upload, and optional on the rest.

• Template library (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 and /restore, GET /v1/companies/{company}/pdf-templates/{template}/impact and GET /v1/companies/{company}/pdf-templates/{template}/revisions/{revision}. Company defaults live in GET|PATCH /v1/companies/{company}/pdf-templates/defaults, per-contact defaults in GET|PATCH /v1/companies/{company}/pdf-templates/contact-defaults/{contact}/{document_type}/{purpose}, and logos and images in POST /v1/companies/{company}/pdf-templates/assets and GET /v1/companies/{company}/pdf-templates/assets/{asset} (16 in all). The list uses page and per_page and answers { "items", "meta" }.
• Commercial identities (same scopes) — GET|POST /v1/companies/{company}/pdf-commercial-identities, GET|PATCH /v1/companies/{company}/pdf-commercial-identities/{identity}, POST .../{identity}/revisions, /archive and /restore, GET .../{identity}/impact and GET .../{identity}/revisions/{revision} (9 in all).
• Preview (pdfs:read and pdf_templates:read) — POST /v1/companies/{company}/pdf-template-previews renders a template before you use it, from an example, an unsaved form, a saved draft, a presentation revision or an invoice substitution (the source field). It returns the metadata of a preview artifact and answers 200, or 202 while the render is queued.
• PDF artifacts (pdfs:read) — POST /v1/companies/{company}/pdf-artifacts prepares the PDF of a retained presentation, POST /v1/companies/{company}/pdf-artifacts/{artifact}/render renders it, GET /v1/companies/{company}/pdf-artifacts/{artifact} reads its state and GET /v1/companies/{company}/pdf-artifacts/{artifact}/download returns the bytes with ETag, 304 for If-None-Match and 503 with Retry-After while it is pending.
• Presentation of each document — for invoices, quotes, proformas and delivery notes (scope {document}:read|write): GET|PATCH /v1/companies/{company}/{documents}/{id}/presentation, GET /v1/companies/{company}/{documents}/{id}/presentation-history (paginated with page and per_page) and POST /v1/companies/{company}/{documents}/{id}/presentation-revisions (16 in all).
• Template of a series (series:read|write) — GET|PATCH /v1/companies/{company}/series/{series}/pdf-template.
• Administrative revisions of an invoice (invoices:read|write) — GET|POST /v1/companies/{company}/invoices/{invoice}/administrative-revisions revise the DIR3 routing of an issued or overdue invoice with a version check in the body.

The nine PATCH operations of this list (templates, identities, company defaults, contact defaults, the four document presentations and the series template) accept If-Match, and the operations that return a single resource answer with an ETag.

MCP tools

The MCP server publishes 51 new tools: one for each of these operations and generate_recurring_invoice for the existing generate operation. The company comes from the MCP session, so the tools take no company argument. See the tool catalog.

• Retries. The 14 library writes, assign_*_presentation, revise_*_presentation, assign_series_pdf_template, prepare_pdf_artifact, render_pdf_artifact, preview_pdf_template and generate_recurring_invoice accept idempotency_key: reuse the same key when you retry a call so that it is not applied twice.
• Errors. A rejection raised while one of these tools runs (for example pdf_presentation_not_ready, pdf_template_version_conflict or a 404) comes back as a normal result with isError: true, and _meta["com.factuarea/error"] carries the same http_status, code and param as the REST error. Branch on code; MCP errors has the full shape.
• Existing tools. accept_quote and accept_proforma follow the acceptance rule of the REST operations (optional expected_presentation_uuid, precondition only for the first capture), and get_invoice_pdf, get_quote_pdf, get_proforma_pdf and get_delivery_note_pdf claim a retryable failed render again instead of returning the earlier failure. create_invoice and update_invoice describe the due_on rule of invoices with a payment schedule, and every tool that issues an invoice answers invoice_due_date_not_last_instalment when it is not met; so do schedule_invoice and reschedule_invoice, and duplicate_invoice moves the instalments with the issue date.

Scopes

Two new scopes, pdf_templates:read and pdf_templates:write, cover the library and the identities. No scope macro includes them. The preview needs both pdfs:read and pdf_templates:read. Document presentations reuse the scope of their document. The library is the pdf_templates module and the advanced editor needs pdf_templates_editor; see Access. POST /v1/accounts/{account}/api-keys accepts the new scopes in its scopes list.

Changes to existing operations

137 existing operations change their contract. They are listed in the tables at the end of the page; these are the groups. The transport control document operations that also change are listed in their own release.

• Template on write — create and update of quotes, proformas and delivery notes, create, update and corrective of invoices, and POST /v1/companies/{company}/invoices/substitute-simplified accept pdf_template_id, with expected_selection_version wherever there is an earlier selection to compare (not on corrective or substitute-simplified). Series accept pdf_template_id on create and update, plus pdf_template_expected_version on update, and now return pdf_template_id and pdf_template_version.
• Presentation in responses — invoices, quotes, proformas and delivery notes carry presentation and pdf_output_state in every response that returns the document (list, show, create, update, transitions, lookups and duplicates).
• Revisioned presentation inactive or active — with it inactive the presentation fields (presentation_precondition, presentation_preconditions, pdf_template_uuid, expected_presentation_uuid, expected_selection_version and the other expected_*) are ignored and the behaviour is the one before this release. With it active they are validated, and a template named without expected_selection_version, or a delivery without its precondition, answers 428. Clients that do not use templates are not affected.
• Delivery precondition — invoice issue and send take the seven expected_*, purpose and format fields flat; quote send and accept, proforma send and accept, and delivery note send take presentation_precondition; the bulk-send and bulk-status operations of the four documents take presentation_preconditions. The conversion operations declare these fields as not accepted. See the delivery precondition.
• Accepting quotes and pro-formas — POST /v1/companies/{company}/quotes/{quote}/accept and POST /v1/companies/{company}/proformas/{proforma}/accept need presentation_precondition only for the first capture: when the document has no retained capture yet or its draft was edited or re-templated after it was captured (without it, 428 pdf_presentation_precondition_required and nothing is written). A document that already has a retained capture is accepted without the object; the optional expected_presentation_uuid (new on quotes) cites that capture and answers 409 pdf_presentation_conflict if it is no longer the current one. Accepting a draft numbers it, also a pro-forma, and captures what was reviewed. The request examples are first_capture and retained_capture.
• pdf_presentation_not_ready is 422 — it is a business rule, not a permission. Branch on code.
• Conflicts (409) — every 409 of this release changes nothing: read again, review and repeat. Document writes, transitions, conversions, duplicates, signatures and downloads declare pdf_presentation_conflict (the presentation changed since you read it) and pdf_presentation_context_changed (what you reviewed no longer matches the document). Invoice operations that deliver or register a fiscal fact (create, issue, send, annul, void, corrective, substitute-simplified, mark-paid, mark-sent, payments and their reversal, send-reminder, the quarterly ZIP and email, and the generation of a recurring invoice) also declare pdf_legal_source_changed. In the library, the writes with expected_version declare pdf_template_version_conflict (details.current_version and recovery: reload_or_keep_local), publishing and archiving declare pdf_library_impact_conflict, the asset upload pdf_template_asset_conflict and create and duplicate resource_conflict. The series template, the presentation policy of a recurring invoice and the payment schedule declare their own version conflict.
• Public links — PATCH {document}/public-link accepts action: "publish" with publication_context (presentation_id and expected_binding_version), and both GET and PATCH return a publication block. Opened without a version selector, the url of the link now shows the last version you shared with publish, not the one bound to the current presentation; publication.public_url always names its exact version, and an unknown or private selector answers 404 instead of falling back to another version. See Sending documents.
• Delivery note signature — signed_at in POST /v1/companies/{company}/delivery-notes/{id}/sign is deprecated and ignored: the server sets the date. signed_by accepts up to 120 characters. The operation also takes the expected_* identifiers of the presentation the signer saw.
• Invoices — responses carry payment_terms (instalments), header and line business_references, legal_literals, the invoicing period and the administrative_* routing. Writes accept them with the omit / null / [] semantics of Invoice business data, and expected_payment_terms_version protects the schedule of an existing invoice. With a schedule, the invoice falls due on the day of its last instalment: issuing it with a missing or different due_on answers 422 invoice_due_date_not_last_instalment, a draft keeps the date you send, and an update that replaces payment_terms without due_on moves it to the last instalment. A corrective without a schedule falls due 30 days after it is issued. Scheduling or rescheduling an invoice (POST /v1/companies/{company}/invoices/{invoice}/schedule and PATCH /v1/companies/{company}/invoices/{invoice}/reschedule) checks the same rule and answers 422 invoice_due_date_not_last_instalment (param: due_on), with the invoice keeping its status and date. Duplicating an invoice issues the draft today: each instalment keeps its amount and moves by the days between both issue dates, and due_on is the last moved instalment. The 422 of create, update, corrective and issue starts with the general text of invoice validation and lists the schedule codes after it. The extended invoice also travels inside GET /v1/companies/{company}/events, GET /v1/companies/{company}/events/{event} and the webhook deliveries (list and show), so their payloads change. With revisioned templates, the pdf block of POST /v1/companies/{company}/invoices is the output retained for the presentation captured at issuance, in that presentation's paper (a simplified invoice may be an 80 mm ticket), and while it is pending its url answers 503 pdf_artifact_not_ready with Retry-After.
• Contacts — the customer profile accepts and returns the optional dir3_proponent (role 04), so every operation that returns a contact changes.
• FacturaE and FACe — GET /v1/companies/{company}/invoices/{id}/facturae accepts submission_id, returns ETag and X-Facturae-Sha256 when the artifact is retained, and rejects a draft or scheduled invoice with 422. POST /v1/companies/{company}/invoices/{id}/face-submissions accepts submission_id and answers 201 (new attempt), 200 (continuation or replay) or 409 (for example face_transmission_uncertain). POST /v1/companies/{company}/invoices/{id}/send takes attach_facturae and submission_id. See FACe invoicing.
• PDF downloads and render — GET /v1/companies/{company}/{documents}/{id}/pdf and GET /v1/companies/{company}/invoices/{id}/pdf-link can answer 202 while the PDF is being prepared, and 409 or 410 when the source changed or was erased. A render that failed but can be retried is never answered with that earlier failure: the download claims it again and answers 202, so retrying makes progress. A render that failed terminally answers 500 with its code (pdf_engine_profile_unavailable, pdf_payload_resource_unavailable, pdf_image_resource_unavailable) and nothing is enqueued. POST /v1/companies/{company}/pdf-artifacts/{artifact}/render and POST /v1/companies/{company}/pdf-template-previews answer 200 only with a ready artifact: one that no render can complete answers 500 with its code. See how downloads answer. The four bulk-pdf operations declare X-Bulk-Total, X-Bulk-Successful and X-Bulk-Failed, and POST /v1/companies/{company}/invoices/quarterly/download-zip declares its X-Quarterly-* headers.
• Recurring and correctives — a recurring invoice carries a presentation policy (presentation_policy, presentation_policy_version, presentation_pause_reason) and payment_terms_template; a corrective invoice inherits what Corrective invoices lists. See also Recurring invoices.
• Other declarations — GET /v1/tax-catalog declares If-None-Match; POST /v1/companies/{company}/employees and POST /v1/companies/{company}/employees/{employee}/reactivate declare the correlation header X-Request-Id on their 503; POST /v1/companies/{company}/contacts/import and its preview declare the limit of the mapping field; POST /v1/companies/{company}/contacts and the customer profile declare 409 idempotency_key_in_use (a request with the same key is still running); PATCH /v1/companies/{company}/delivery-notes/{delivery_note} no longer declares resource_conflict, because editing a delivery note does not number it.

Brand on dark backgrounds and brand size

A commercial identity revision has four more keys, which POST /v1/companies/{company}/pdf-commercial-identities and POST /v1/companies/{company}/pdf-commercial-identities/{identity}/revisions accept and every identity response returns:

• logo_dark_asset_id and brand_image_dark_asset_id: optional versions of the logo and of the brand image for dark backgrounds. Each needs its base image.
• dark_background_fallback: silhouette (default) or plate.
• brand_size: small, medium (default) or large.

A brand has no address: contact_address is not part of its configuration, and the issuer address on the PDF is always the company's. There is no separate commercial contact block either: when the template shows the company's email or phone, the brand's contact_email or contact_phone replaces it in the issuer's contact line, and when the template hides it, neither is printed. The unsaved brand of a preview therefore takes six required keys.

On a dark background (the frame of the corporative preset, the header band of the control document), the brand is painted in this order: its dark version, if it has one; the image as it is, if it reads; otherwise a white silhouette, or the light plate if the brand prefers plate. On a light background, an image that would disappear, such as a white logo, is painted as a black silhouette. In practice, upload the colour logo as the base and the white one as the dark version.

A template's configuration.branding.size also accepts inherit, the value of new templates, which takes the brand_size of its brand (medium without one). The preview accepts the four keys in an unsaved brand (commercial_identity with mode: draft), and the MCP tools create_pdf_commercial_identity, publish_pdf_commercial_identity_revision and preview_pdf_template take them as well. Documents captured before keep their look. See dark backgrounds and brand size.

Section texts per language

footer_text, conditions_text and commercial_register_text of the sections block of PdfTemplateConfiguration are now objects with one text per language: { "es": "…", "en": "…", "ca": "…" }. Each language is a string or null, with the same limits as before for each one (500, 5,000 and 5,000 characters), and an empty string is stored as null.

• Reading. Every response returns the object, always. A text stored in the earlier form, a plain string, is returned as { "es": text, "en": null, "ca": null }. Published revisions, captures and artifacts are not rewritten, so their fingerprint does not change.
• Writing. Create and publish accept a plain string or the object. A string replaces the text of all three languages with that text under es. A partial object only changes the languages you send. An unknown key, such as fr, returns 422 invalid_pdf_template_configuration with param configuration.sections.footer_text (or the field you sent).
• Rendering. The PDF uses the text in the language of the document. If it is empty, it uses the Spanish one, and if that is empty too, the block is not printed. A plain string is printed the same in the three languages.

Operations affected: POST /v1/companies/{company}/pdf-templates and POST /v1/companies/{company}/pdf-templates/{template}/revisions (they accept both forms), and 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 and POST /v1/companies/{company}/pdf-template-previews (they return or take the template configuration). The MCP tools of the library follow the same contract.

sections.notes_mode keeps its three values: auto prints the notes of the document when it has them, no hides them, and yes is still accepted and behaves exactly like auto.

pdf_output_state on every document

Invoice, Quote, Proforma and DeliveryNote responses include pdf_output_state, a summary of the retained PDF output that never exposes snapshots, proofs or storage paths. GET /v1/companies/{company}/{documents}/{id}/pdf also answers 202 while the PDF is being prepared.

The key is always present. The example of the field is the all-null state:

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

See how to read it and retry.

Error codes

61 codes are new; none changes the status of an existing code. The most relevant ones:

idempotency_key_reused is still 422: reusing an Idempotency-Key with another body, also on the preview and on the artifact operations, which compare the raw body byte for byte. Resending an unattended checkout whose external_id was already issued with another type or total is a different error, 409 unattended_replay_mismatch.

Branch on code, never on message. The error catalog has all of them. Over MCP the same codes arrive in _meta["com.factuarea/error"] of a result with isError: true.