Biblioteca de plantillas PDF y facturas estructuradas

19 de octubre de 2026 (provisional: la fecha definitiva es el día en que se publique esta release) — La API expone ahora la biblioteca de plantillas PDF de la app, la presentación que conserva cada documento, los artefactos PDF exactos y los datos de negocio estructurados de una factura. Cuatro guías explican el modelo completo: Biblioteca de plantillas PDF, Presentación de documentos, Vistas previas y artefactos PDF y Datos de negocio de la factura.

Todas las operaciones de esta release cuelgan del eje de empresa, /v1/companies/{company}/…, donde {company} es el id (UUID v7) del NIF con el que operas; alcanzar un NIF lo explica. Ninguna de las operaciones nuevas se publicó nunca en la raíz de /v1: son nuevas, no se han movido, así que no hay ninguna ruta antigua desde la que migrar.

Las operaciones se escriben como METHOD /path. Las tablas del final de esta página enlazan cada operación nueva y actualizada con su página de la API Reference.

Operaciones nuevas

Ninguna de estas operaciones está marcada con x-irreversible. Las 27 escrituras aceptan Idempotency-Key; es obligatoria en la vista previa, en la preparación y el renderizado de artefactos y en la subida de activos, y opcional en el resto.

• Biblioteca de plantillas (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 y /restore, GET /v1/companies/{company}/pdf-templates/{template}/impact y GET /v1/companies/{company}/pdf-templates/{template}/revisions/{revision}. Los valores por defecto de la empresa están en GET|PATCH /v1/companies/{company}/pdf-templates/defaults, los de cada contacto en GET|PATCH /v1/companies/{company}/pdf-templates/contact-defaults/{contact}/{document_type}/{purpose}, y los logotipos e imágenes en POST /v1/companies/{company}/pdf-templates/assets y GET /v1/companies/{company}/pdf-templates/assets/{asset} (16 en total). El listado usa page y per_page y responde { "items", "meta" }.
• Identidades comerciales (mismos scopes) — GET|POST /v1/companies/{company}/pdf-commercial-identities, GET|PATCH /v1/companies/{company}/pdf-commercial-identities/{identity}, POST .../{identity}/revisions, /archive y /restore, GET .../{identity}/impact y GET .../{identity}/revisions/{revision} (9 en total).
• Vista previa (pdfs:read y pdf_templates:read) — POST /v1/companies/{company}/pdf-template-previews renderiza una plantilla antes de usarla, a partir de un ejemplo, un formulario sin guardar, un borrador guardado, una revisión de presentación o una sustitución de factura (el campo source). Devuelve los metadatos de un artefacto de vista previa y responde 200, o 202 mientras el renderizado está en cola.
• Artefactos PDF (pdfs:read) — POST /v1/companies/{company}/pdf-artifacts prepara el PDF de una presentación conservada, POST /v1/companies/{company}/pdf-artifacts/{artifact}/render lo renderiza, GET /v1/companies/{company}/pdf-artifacts/{artifact} consulta su estado y GET /v1/companies/{company}/pdf-artifacts/{artifact}/download devuelve los bytes con ETag, 304 ante If-None-Match y 503 con Retry-After mientras está pendiente.
• Presentación de cada documento — en facturas, presupuestos, proformas y albaranes (scope {document}:read|write): GET|PATCH /v1/companies/{company}/{documents}/{id}/presentation, GET /v1/companies/{company}/{documents}/{id}/presentation-history (paginado con page y per_page) y POST /v1/companies/{company}/{documents}/{id}/presentation-revisions (16 en total).
• Plantilla de una serie (series:read|write) — GET|PATCH /v1/companies/{company}/series/{series}/pdf-template.
• Revisiones administrativas de una factura (invoices:read|write) — GET|POST /v1/companies/{company}/invoices/{invoice}/administrative-revisions revisan el encaminamiento DIR3 de una factura emitida o vencida con una comprobación de versión en el cuerpo.

Las nueve operaciones PATCH de esta lista (plantillas, identidades, valores por defecto de la empresa y de los contactos, las cuatro presentaciones de documento y la plantilla de serie) aceptan If-Match, y las operaciones que devuelven un solo recurso responden con un ETag.

Tools MCP

El servidor MCP publica 51 tools nuevas: una por cada una de estas operaciones y generate_recurring_invoice para la operación de generación ya existente. La empresa sale de la sesión MCP, así que las tools no llevan argumento company. Consulta el catálogo de tools.

• Reintentos. Las 14 escrituras de la biblioteca, assign_*_presentation, revise_*_presentation, assign_series_pdf_template, prepare_pdf_artifact, render_pdf_artifact, preview_pdf_template y generate_recurring_invoice aceptan idempotency_key: reutiliza la misma clave al reintentar una llamada para que no se aplique dos veces.
• Errores. Un rechazo que se produce mientras se ejecuta una de estas tools (por ejemplo pdf_presentation_not_ready, pdf_template_version_conflict o un 404) llega como un resultado normal con isError: true, y _meta["com.factuarea/error"] lleva el mismo http_status, code y param que el error REST. Decide por code; Errores MCP tiene la forma completa.
• Tools existentes. accept_quote y accept_proforma siguen la regla de aceptación de las operaciones REST (expected_presentation_uuid opcional, precondición solo en la primera captura), y get_invoice_pdf, get_quote_pdf, get_proforma_pdf y get_delivery_note_pdf vuelven a reclamar un renderizado fallido reintentable en lugar de devolver el fallo anterior. create_invoice y update_invoice describen la regla de due_on de las facturas con plazos, y toda tool que emite una factura responde invoice_due_date_not_last_instalment si no se cumple; también schedule_invoice y reschedule_invoice, y duplicate_invoice desplaza los plazos con la fecha de emisión.

Scopes

Dos scopes nuevos, pdf_templates:read y pdf_templates:write, cubren la biblioteca y las identidades. Ninguna macro de scopes los incluye. La vista previa necesita a la vez pdfs:read y pdf_templates:read. La presentación de los documentos reutiliza el scope de su documento. La biblioteca es el módulo pdf_templates y el editor avanzado necesita pdf_templates_editor; consulta Acceso. POST /v1/accounts/{account}/api-keys acepta los scopes nuevos en su lista scopes.

Cambios en operaciones existentes

Cambian de contrato 137 de las operaciones existentes. Están en las tablas del final de la página; estos son los grupos. Las operaciones de los documentos de control de transporte que también cambian están en su propia publicación.

• Plantilla al escribir — crear y actualizar de presupuestos, proformas y albaranes, crear, actualizar y rectificar de facturas, y POST /v1/companies/{company}/invoices/substitute-simplified aceptan pdf_template_id, con expected_selection_version donde hay una selección anterior con la que comparar (no en la rectificativa ni en substitute-simplified). Las series aceptan pdf_template_id al crear y actualizar, más pdf_template_expected_version al actualizar, y ahora devuelven pdf_template_id y pdf_template_version.
• Presentación en las respuestas — facturas, presupuestos, proformas y albaranes llevan presentation y pdf_output_state en toda respuesta que devuelve el documento (listado, consulta, creación, actualización, transiciones, búsquedas y duplicados).
• Presentación con revisiones inactiva o activa — con ella inactiva los campos de presentación (presentation_precondition, presentation_preconditions, pdf_template_uuid, expected_presentation_uuid, expected_selection_version y los demás expected_*) se ignoran y el comportamiento es el anterior a esta release. Con ella activa se validan, y una plantilla indicada sin expected_selection_version, o una entrega sin su precondición, responde 428. Los clientes que no usan plantillas no se ven afectados.
• Precondición de entrega — issue y send de facturas reciben planos los siete campos expected_*, purpose y format; send y accept de presupuestos, send y accept de proformas y send de albaranes reciben presentation_precondition; las operaciones bulk-send y bulk-status de los cuatro documentos reciben presentation_preconditions. Las operaciones de conversión declaran estos campos como no aceptados. Consulta la precondición de entrega.
• Aceptación de presupuestos y proformas — POST /v1/companies/{company}/quotes/{quote}/accept y POST /v1/companies/{company}/proformas/{proforma}/accept solo necesitan presentation_precondition en la primera captura: cuando el documento aún no tiene captura retenida o su borrador se editó o cambió de plantilla después de capturarse (sin él, 428 pdf_presentation_precondition_required y no se escribe nada). Un documento que ya tiene captura retenida se acepta sin el objeto; el campo opcional expected_presentation_uuid (nuevo en los presupuestos) cita esa captura y responde 409 pdf_presentation_conflict si ya no es la vigente. Aceptar un borrador lo numera, también una proforma, y captura lo que se revisó. Los ejemplos de la petición son first_capture y retained_capture.
• pdf_presentation_not_ready es 422 — es una regla de negocio, no un permiso. Decide por code.
• Conflictos (409) — ningún 409 de esta release cambia nada: vuelve a leer, revisa y repite. Las escrituras, transiciones, conversiones, duplicados, firmas y descargas de documentos declaran pdf_presentation_conflict (la presentación cambió desde que la leíste) y pdf_presentation_context_changed (lo que revisaste ya no coincide con el documento). Las operaciones de factura que entregan o registran un hecho fiscal (crear, issue, send, annul, void, corrective, substitute-simplified, mark-paid, mark-sent, los cobros y su reversión, send-reminder, el ZIP y el correo trimestrales, y la generación de una factura recurrente) declaran además pdf_legal_source_changed. En la biblioteca, las escrituras con expected_version declaran pdf_template_version_conflict (details.current_version y recovery: reload_or_keep_local), publicar y archivar declaran pdf_library_impact_conflict, la subida de activos pdf_template_asset_conflict y crear y duplicar resource_conflict. La plantilla de la serie, la política de presentación de una recurrente y el calendario de pagos declaran su propio conflicto de versión.
• Enlaces públicos — PATCH {document}/public-link acepta action: "publish" con publication_context (presentation_id y expected_binding_version), y tanto GET como PATCH devuelven un bloque publication. Abierta sin selector de versión, la url del enlace muestra ahora la última versión que compartiste con publish, no la vinculada a la presentación vigente; publication.public_url siempre nombra su versión exacta, y un selector desconocido o privado responde 404 en lugar de recurrir a otra versión. Consulta Envío de documentos.
• Firma del albarán — signed_at en POST /v1/companies/{company}/delivery-notes/{id}/sign está obsoleto y se ignora: la fecha la fija el servidor. signed_by admite hasta 120 caracteres. La operación también recibe los identificadores expected_* de la presentación que vio quien firma.
• Facturas — las respuestas llevan payment_terms (vencimientos), business_references de cabecera y de línea, legal_literals, el periodo de facturación y el encaminamiento administrative_*. Las escrituras los aceptan con la semántica omitir / null / [] de Datos de negocio de la factura, y expected_payment_terms_version protege el calendario de una factura existente. Con plazos, la factura vence el día de su último plazo: emitirla con un due_on ausente o distinto responde 422 invoice_due_date_not_last_instalment, un borrador conserva la fecha que envíes y una actualización que sustituye payment_terms sin due_on lo lleva al último plazo. Una rectificativa sin calendario vence 30 días después de emitirse. Programar o reprogramar una factura (POST /v1/companies/{company}/invoices/{invoice}/schedule y PATCH /v1/companies/{company}/invoices/{invoice}/reschedule) comprueba la misma regla y responde 422 invoice_due_date_not_last_instalment (param: due_on); la factura conserva su estado y su fecha. Duplicar una factura emite el borrador con fecha de hoy: cada plazo conserva su importe y se desplaza los días que hay entre las dos fechas de emisión, y due_on es el último plazo desplazado. El 422 de crear, actualizar, rectificar y emitir empieza por el texto general de la validación de facturas y detrás enumera los códigos de plazos. La factura ampliada también viaja dentro de GET /v1/companies/{company}/events, GET /v1/companies/{company}/events/{event} y las entregas de webhook (listado y consulta), así que cambian sus payloads. Con las plantillas revisionadas, el bloque pdf de POST /v1/companies/{company}/invoices es la salida retenida de la presentación capturada al emitir, en el papel de esa presentación (una simplificada puede ser un ticket de 80 mm), y mientras está pending su url responde 503 pdf_artifact_not_ready con Retry-After.
• Contactos — el perfil de cliente acepta y devuelve el dir3_proponent opcional (rol 04), así que cambia toda operación que devuelve un contacto.
• FacturaE y FACe — GET /v1/companies/{company}/invoices/{id}/facturae acepta submission_id, devuelve ETag y X-Facturae-Sha256 cuando el artefacto está conservado y rechaza con 422 una factura en borrador o programada. POST /v1/companies/{company}/invoices/{id}/face-submissions acepta submission_id y responde 201 (intento nuevo), 200 (continuación o repetición) o 409 (por ejemplo face_transmission_uncertain). POST /v1/companies/{company}/invoices/{id}/send recibe attach_facturae y submission_id. Consulta Facturación a FACe.
• Descargas y renderizado de PDF — GET /v1/companies/{company}/{documents}/{id}/pdf y GET /v1/companies/{company}/invoices/{id}/pdf-link pueden responder 202 mientras se prepara el PDF, y 409 o 410 cuando la fuente cambió o se borró. Un renderizado que falló pero se puede reintentar nunca se responde con ese fallo anterior: la descarga lo vuelve a reclamar y responde 202, así que reintentar avanza. Un renderizado que falló de forma definitiva responde 500 con su código (pdf_engine_profile_unavailable, pdf_payload_resource_unavailable, pdf_image_resource_unavailable) y no se encola nada. POST /v1/companies/{company}/pdf-artifacts/{artifact}/render y POST /v1/companies/{company}/pdf-template-previews solo responden 200 con un artefacto listo: uno que ningún renderizado puede completar responde 500 con su código. Consulta cómo responden las descargas. Las cuatro operaciones bulk-pdf declaran X-Bulk-Total, X-Bulk-Successful y X-Bulk-Failed, y POST /v1/companies/{company}/invoices/quarterly/download-zip declara sus cabeceras X-Quarterly-*.
• Recurrentes y rectificativas — una factura recurrente lleva una política de presentación (presentation_policy, presentation_policy_version, presentation_pause_reason) y payment_terms_template; una factura rectificativa hereda lo que lista Facturas rectificativas. Consulta también Facturas recurrentes.
• Otras declaraciones — GET /v1/tax-catalog declara If-None-Match; POST /v1/companies/{company}/employees y POST /v1/companies/{company}/employees/{employee}/reactivate declaran la cabecera de correlación X-Request-Id en su 503; POST /v1/companies/{company}/contacts/import y su vista previa declaran el límite del campo mapping; POST /v1/companies/{company}/contacts y el perfil de cliente declaran 409 idempotency_key_in_use (otra petición con la misma clave sigue en curso); PATCH /v1/companies/{company}/delivery-notes/{delivery_note} deja de declarar resource_conflict, porque editar un albarán no lo numera.

La marca sobre fondos oscuros y el tamaño de la marca

La revisión de una identidad comercial tiene cuatro claves más, que aceptan POST /v1/companies/{company}/pdf-commercial-identities y POST /v1/companies/{company}/pdf-commercial-identities/{identity}/revisions y que devuelve toda respuesta de identidad:

• logo_dark_asset_id y brand_image_dark_asset_id: versiones opcionales del logo y de la imagen de marca para fondos oscuros. Cada una necesita su imagen base.
• dark_background_fallback: silhouette (por defecto) o plate.
• brand_size: small, medium (por defecto) o large.

Una marca no tiene dirección: contact_address no forma parte de su configuración y el domicilio del emisor en el PDF es siempre el de la empresa. Tampoco hay un bloque aparte de contacto comercial: cuando la plantilla muestra el correo o el teléfono de la empresa, el contact_email o el contact_phone de la marca lo sustituye en la línea de contacto del emisor, y cuando la plantilla lo oculta no sale ninguno. Por eso la marca sin guardar de una vista previa lleva seis claves obligatorias.

Sobre un fondo oscuro (el marco del preajuste corporative, la banda de la cabecera del documento de control), la marca se pinta en este orden: su versión para fondo oscuro, si la tiene; la imagen tal cual, si se lee; si no, una silueta blanca, o la placa clara si la marca prefiere plate. Sobre un fondo claro, una imagen que desaparecería, como un logo blanco, se pinta como una silueta negra. En la práctica, sube el logo en color como base y el blanco como versión para fondo oscuro.

El configuration.branding.size de una plantilla admite además inherit, el valor de las plantillas nuevas, que toma el brand_size de su marca (medium si no la tiene). La vista previa acepta las cuatro claves en una marca sin guardar (commercial_identity con mode: draft), y también las aceptan las tools MCP create_pdf_commercial_identity, publish_pdf_commercial_identity_revision y preview_pdf_template. Los documentos capturados antes conservan su aspecto. Consulta los fondos oscuros y el tamaño de la marca.

Textos de sección por idioma

footer_text, conditions_text y commercial_register_text del bloque sections de PdfTemplateConfiguration pasan a ser objetos con un texto por idioma: { "es": "…", "en": "…", "ca": "…" }. Cada idioma es un texto o null, con los mismos límites de siempre por idioma (500, 5.000 y 5.000 caracteres), y un texto vacío se guarda como null.

• Lectura. Todas las respuestas devuelven siempre el objeto. Un texto guardado en la forma anterior, un string, se devuelve como { "es": texto, "en": null, "ca": null }. Las revisiones, capturas y artefactos ya publicados no se reescriben, así que su huella no cambia.
• Escritura. Crear y publicar aceptan un string o el objeto. Un string sustituye el texto de los tres idiomas por ese texto en es. Un objeto parcial solo cambia los idiomas que envíes. Una clave desconocida, como fr, devuelve 422 invalid_pdf_template_configuration con param configuration.sections.footer_text (o el campo que enviaste).
• Pintado. El PDF usa el texto del idioma del documento. Si está vacío, usa el español, y si este también está vacío, el bloque no se pinta. Un string se pinta igual en los tres idiomas.

Operaciones afectadas: POST /v1/companies/{company}/pdf-templates y POST /v1/companies/{company}/pdf-templates/{template}/revisions (aceptan ambas formas), y 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 y POST /v1/companies/{company}/pdf-template-previews (devuelven o reciben la configuración de la plantilla). Las tools MCP de la biblioteca siguen el mismo contrato.

sections.notes_mode conserva sus tres valores: auto imprime las notas del documento cuando las tiene, no las oculta y yes se sigue aceptando y se comporta exactamente como auto.

pdf_output_state en cada documento

Las respuestas de Invoice, Quote, Proforma y DeliveryNote incluyen pdf_output_state, un resumen de la salida PDF conservada que nunca expone snapshots, justificantes ni rutas de almacenamiento. GET /v1/companies/{company}/{documents}/{id}/pdf también responde 202 mientras se prepara el PDF.

La clave siempre está presente. El ejemplo del campo representa el estado en el que todos sus valores son 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 cómo leerlo y reintentar.

Códigos de error

61 códigos son nuevos; ninguno cambia el estado de un código existente. Los más relevantes:

idempotency_key_reused sigue siendo 422: reutilizar una Idempotency-Key con otro cuerpo, también en la vista previa y en las operaciones de artefactos, que comparan el cuerpo crudo byte a byte. Reenviar un cobro desatendido cuyo external_id ya se emitió con otro tipo o total es otro error, 409 unattended_replay_mismatch.

Decide por code, nunca por message. El catálogo de errores los recoge todos. Por MCP los mismos códigos llegan en _meta["com.factuarea/error"] de un resultado con isError: true.