Vistas previas y artefactos PDF

Todo PDF que la API genera a partir de la biblioteca de plantillas es un artefacto: un PDF exacto e inmutable con su propio identificador, su estado y su suma de comprobación. Existen dos tipos.

Cuatro grupos de operaciones cubren el flujo. La gestión de la biblioteca, los valores por defecto y la precedencia están en la guía de la biblioteca de plantillas PDF.

Todas las rutas de esta guía cuelgan de /v1/companies/{company}/…: {company} es el id (UUID v7) del NIF con el que operas, y en los ejemplos curl es $COMPANY_ID. Alcanzar un NIF explica cómo resolverlo.

Los artefactos necesitan el rol admin o user y la sección de módulo de la familia del documento (invoices, quotes, proformas o delivery_notes). Los artefactos de vista previa siguen además el módulo pdf_templates y el scope pdf_templates:read, así que leer uno también exige ese scope. Generar un PDF consume el mismo presupuesto de renderizado que los demás endpoints de PDF: el trabajo nuevo puede devolver 429 pdf_generation_budget_exceeded con Retry-After, mientras que las repeticiones y los artefactos ya renderizados no cuestan nada más (véanse los límites de peticiones).

Previsualizar una plantilla

POST /v1/companies/{company}/pdf-template-previews genera un PDF sin guardar nada: no publica una plantilla, no cambia un valor por defecto ni toca un documento. El cuerpo tiene cinco campos obligatorios y un source cerrado:

Según el origen, otros tres campos describen el diseño que se genera: base_preset, layout_version (siempre "1") y configuration (la configuración normalizada completa, tal como la devuelve una revisión de plantilla).

Cuando un origen persistido omite el bloque visual, el servidor previsualiza la plantilla que se aplicaría hoy. Enviar solo uno o dos de los tres campos es un 422 pdf_presentation_invalid, con el que falta en param. El selector de marca draft exige el rol admin y activos que ya hayas subido.

Con document_type: invoice, source.form.document.exemption_reason es una causa de exención de cabecera opcional (catálogo en GET /v1/tax-catalog): su mención legal abre las menciones automáticas de la vista previa, igual que al guardar la factura. Omítelo o envía null para no usar causa. Una causa desconocida, o enviada en otro tipo de documento, se rechaza.

Una buena forma de previsualizar un diseño que estás editando es reutilizar la revisión que leíste:

curl -s https://api.factuarea.com/v1/companies/$COMPANY_ID/pdf-templates/0199f3a2-7c4e-7b1a-9d3e-5a2c8f1b6e40 \
  -H "Authorization: Bearer fact_test_3pXnR2VbY7TcA9eFmN5z8KqW" \
  | jq '{
      document_type: "invoice", purpose: "complete", format: "a4", locale: "en",
      base_preset: .current_revision.base_preset,
      layout_version: .current_revision.layout_version,
      configuration: .current_revision.configuration,
      source: { kind: "example", scenario: "standard" }
    }' > preview.json

curl -X POST https://api.factuarea.com/v1/companies/$COMPANY_ID/pdf-template-previews \
  -H "Authorization: Bearer fact_test_3pXnR2VbY7TcA9eFmN5z8KqW" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  --data-binary @preview.json

La respuesta es el artefacto, envuelto en data. Es 200 cuando el PDF está listo y 202 mientras está prepared, queued o processing; en este segundo caso consulta metadata_url como se describe en el bucle de reintento (abreviado):

{
  "data": {
    "id": "0199f405-91ab-7c42-8d6e-2a9f3b5c7e10",
    "purpose": "preview",
    "state": "ready",
    "source_kind": "example",
    "context_authority": "illustrative",
    "sha256": "7a265f5f003866f84e23c7e237301879b7d4a4ecc0ab80d2041a3c980b12310a",
    "size_bytes": 48210,
    "expires_at": "2026-10-15T09:20:00.000000Z",
    "geometry": { "format": "a4", "orientation": "portrait", "width_mm": 210, "height_mm": 297 },
    "metadata_url": "https://api.factuarea.com/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/pdf-artifacts/0199f405-91ab-7c42-8d6e-2a9f3b5c7e10",
    "download_url": "https://api.factuarea.com/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/pdf-artifacts/0199f405-91ab-7c42-8d6e-2a9f3b5c7e10/download",
    "retry_after": null,
    "error": null,
    "unavailable_reason": null
  }
}

El artefacto también informa de effective_font y warnings del renderizado, de context_fingerprint, de artifact_fingerprint y de los tokens que se describen a continuación.

Autoridad: qué puede autorizar una vista previa

context_authority indica hasta dónde puedes fiarte de la vista previa.

Una vista previa nunca se convierte en el PDF oficial. Si después de previsualizar cambia el origen, la selección, la marca, la configuración o el entorno de renderizado, la precondición deja de coincidir y la acción responde 409; vuelve a previsualizar.

Vistas previas y el interruptor de la empresa

Las vistas previas nuevas y los artefactos de documento nuevos necesitan que la salida revisionada esté activa para tu empresa: el interruptor de la plataforma encendido y la inicialización de tu empresa terminada (el render_activation de solo lectura de los valores por defecto lo indica). Si no, la llamada devuelve 422 pdf_presentation_not_ready y no crea nada. No se pierde nada más: reintentar más tarde funciona, y las lecturas y el renderizado clásico siguen funcionando.

Preparar, renderizar y leer el PDF de un documento

El artefacto official de un documento se crea a partir de su presentación retenida: el id del bloque presentation que lleva el documento (véase Presentaciones de documento), junto con su tipo de documento, propósito y formato de papel.

curl -X POST https://api.factuarea.com/v1/companies/$COMPANY_ID/pdf-artifacts \
  -H "Authorization: Bearer fact_test_3pXnR2VbY7TcA9eFmN5z8KqW" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "document_type": "invoice",
    "document_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42",
    "presentation_id": "0199f401-33de-7a8c-9e15-b7c4d2a60f38",
    "purpose": "complete",
    "format": "a4",
    "variant": "official"
  }'

prepare y render responden 200 con el artefacto cuando ya está ready, y 202 mientras está prepared, queued o processing. state es uno de prepared, queued, processing, ready, failed, unavailable y corrupt. Un artefacto failed lleva error con el code (pdf_generation_failed, pdf_engine_profile_unavailable, pdf_image_resource_unavailable o pdf_payload_resource_unavailable), un indicador retryable y un correlation_id para dárselo a soporte. retry_after es el número de segundos que hay que esperar mientras está pendiente.

PDF originales y derivados

• La variante official es el original: el PDF de la presentación capturada con el documento, con una suma de comprobación inmutable. Es el que informa pdf_output_state. Cambiar después una plantilla, un valor por defecto o una marca nunca lo altera.
• Un aspecto distinto para un documento ya emitido es una presentación nueva: revisas el documento de forma explícita y eso crea una presentación derivada con su propio artefacto. El original sigue siendo legible.
• La variante alternative es otro artefacto de la misma presentación en un formato de papel autorizado. Nunca sustituye al original, nunca cambia lo que publica el documento y no es el que informa pdf_output_state. Un estilo distinto siempre necesita una presentación nueva.
• Si los bytes de un original se pierden o no superan su suma de comprobación, recibes 500 pdf_original_unavailable o 500 pdf_original_corrupt. Nada se regenera en silencio en su lugar.
• Una presentación derivada (una firma, el QR legal o los datos legales actualizados) conserva el diseño de su original. Si la versión actual ya no sirve ese diseño, prepararla responde 500 pdf_original_layout_unavailable: el original está íntegro y no se prepara nada. Contacta con soporte; una revisión explícita y autorizada crea otro artefacto sin sustituir el original.

Cómo responden las descargas

GET /v1/companies/{company}/invoices/{invoice}/pdf, GET /v1/companies/{company}/quotes/{quote}/pdf, GET /v1/companies/{company}/proformas/{proforma}/pdf y GET /v1/companies/{company}/delivery-notes/{delivery_note}/pdf, a nivel de documento, devuelven el mismo 200 con los bytes, el 304 con If-None-Match y el 202 anterior. Aceptan download=1 para una disposición de adjunto, y las facturas también format. Consulta la referencia de facturas, presupuestos, facturas proforma y albaranes. Cuando el original no se puede servir responden con un error en lugar de un 202: se aplican los estados anteriores, más 409 cuando la presentación conservada no se puede entregar como se pide: pdf_presentation_conflict (cambió desde que la leíste), pdf_presentation_context_changed (por ejemplo, el format solicitado no coincide con el conservado) y, en facturas, pdf_legal_source_changed (revísala con source_policy: "current_legal"). Vuelve a leer la presentación del documento antes de pedir el PDF. Mientras un documento no tiene presentación retenida, o tu empresa sigue renderizando con el flujo clásico, el PDF se sirve como antes.

El bloque pdf_output_state

Las facturas, los presupuestos, las facturas proforma y los albaranes llevan un objeto pdf_output_state de solo lectura que resume su PDF original. Nunca prepara ni renderiza nada.

{
  "state": "processing",
  "presentation_id": "0199f401-33de-7a8c-9e15-b7c4d2a60f38",
  "artifact_id": "0199f405-91ab-7c42-8d6e-2a9f3b5c7e10",
  "format": "a4",
  "variant": "official",
  "unavailable_reason": null,
  "error": null,
  "retry_after": 1,
  "download_url": null
}

Todas las claves están siempre presentes; un documento sin original capturado las tiene todas a null. Un borrado por privacidad se muestra como state: unavailable con error.code: pdf_signature_personal_data_forgotten, sin retry_after y sin download_url.

Un bucle de reintento correcto

Consulta la lectura barata, espera lo que pide el servidor, limita los intentos y para ante las respuestas terminales. No regeneres para "ir más rápido".

async function downloadOriginal(companyId, artifactId, key) {
  const base = 'https://api.factuarea.com/v1/companies/' + companyId + '/pdf-artifacts/' + artifactId;
  const headers = { Authorization: 'Bearer ' + key };

  for (let attempt = 1; attempt <= 12; attempt++) {
    const res = await fetch(base + '/download', { headers });

    if (res.status === 200) return Buffer.from(await res.arrayBuffer());
    if (res.status === 503) {
      const wait = Number(res.headers.get('Retry-After')) || 2 * attempt;
      await new Promise((r) => setTimeout(r, wait * 1000));
      continue;
    }
    const { error } = await res.json();
    // 410 is terminal, 500 needs support, 404 means it expired or never existed.
    throw new Error(error.code + ' (' + res.status + ') ' + error.request_id);
  }
  throw new Error('The PDF is still not ready; check the artifact metadata later.');
}

• Respeta Retry-After y el campo retry_after. Son segundos. Añade un pequeño incremento entre intentos y un tope en el número de intentos.
• Consulta, no vuelvas a crear. Repite el mismo GET. Llamar a prepare o render en cada consulta solo añade ruido: ya devuelven el mismo artefacto.
• Reintenta un fallo a propósito. Cuando state es failed y error.retryable es true, llama de nuevo a render con una Idempotency-Key nueva (la misma clave repetiría el fallo guardado). Si retryable es false, cambia antes la causa: el activo, la cantidad de datos o la configuración.
• Una clave nueva es una intención nueva. Reutiliza la misma clave solo para reintentar la misma petición tras un timeout.
• Para ante un 410. No va a cambiar.
• Usa caché con el ETag. Envía If-None-Match para obtener un 304 gratis.

Idempotencia

preview, prepare y render necesitan Idempotency-Key. En estas tres la huella se calcula sobre el cuerpo crudo, así que la misma clave con un cuerpo que difiere en un solo byte (también el orden de las claves o los espacios) devuelve 422 idempotency_key_reused. Una repetición devuelve la respuesta guardada, con Idempotent-Replayed: true, antes de hacer ningún trabajo y aunque los datos vivos hayan cambiado desde entonces; la autorización de quien llama se comprueba antes. Dos claves con cuerpos equivalentes llevan al mismo artefacto. Consulta Idempotencia.

Errores

Ramifica según code, no según message. Consulta el modelo de errores.

MCP

Las cinco operaciones de artefacto son las tools preview_pdf_template, prepare_pdf_artifact, render_pdf_artifact, get_pdf_artifact y read_pdf_artifact, que devuelve un enlace de descarga autorizado en lugar de los bytes. Usan los mismos scopes, aceptan idempotency_key y siguen los mismos estados. Consulta las tools MCP.