Crear una vista previa de plantilla de PDF

Genera un PDF ilustrativo o de borrador para probar una plantilla antes de usarla.

document_type y source eligen qué se previsualiza: datos de example, un unsaved_form, un persisted_draft, una presentation_revision o una invoice_substitution.
Devuelve los metadatos de un artefacto de vista previa; consúltalo y descárgalo con las operaciones de artefactos PDF.
Una vista previa nunca cambia un documento, la numeración ni la presentación conservada.
Consume del presupuesto de generación de PDF, así que se rechaza una petición sin Idempotency-Key.
Requiere pdfs:read y pdf_templates:read.

Authorization

AuthorizationBearer <token>

Tu API key como token Bearer: fact_live_… en producción, fact_test_… en sandbox. Consulta la guía de autenticación.

En: header

Parámetros de ruta

company*string

Identificador público (UUID v7) de la empresa. Obtenlo de GET /v1/me (data.scope[].id).

Formatouuid

Clave opaca generada por el cliente (hasta 255 caracteres; se recomienda UUID v7) que permite reintentos seguros: la primera respuesta se almacena y se reproduce en las repeticiones sin volver a ejecutar la mutación. Reutilizar una clave con un cuerpo distinto devuelve 422 idempotency_key_reused; los valores de los campos secretos (password, secret…) cuentan como parte del cuerpo, así que reintentar con un secreto corregido bajo la misma clave es una petición distinta, nunca la repetición de la respuesta anterior. Consulta la guía de idempotencia. Obligatoria en esta operación: repetirla produce un efecto irreversible (un email enviado, un archivo generado, una llamada a un tercero o un cargo), por lo que una petición sin esta cabecera se rechaza con 422 idempotency_key_required antes de ejecutar lógica de negocio.

Longitud1 <= length <= 255

Factuarea-Version?string

Fija la versión de la API (YYYY-MM-DD, versionado por fecha estilo Stripe) para esta petición; omítelo para usar la versión fijada de la clave, o la última si no hay ninguna. Versión no soportada → 400 unsupported_api_version; malformada → 400 parameter_invalid_format. La versión efectiva se refleja en la cabecera de respuesta Factuarea-Version. Consulta la guía de Versioning.

Formatodate

Cuerpo de la petición

application/json

La preparación o generación interna reversible usa la política de idempotencia existente; la misma clave con el mismo cuerpo crudo se repite, y otro cuerpo con esa clave se rechaza con 422 idempotency_key_reused antes de la admisión.

Definiciones de TypeScript

Usa el tipo request body en TypeScript.

document_type*string

Valor en"invoice" | "quote" | "proforma" | "delivery-note"

purpose*string

Valor en"complete" | "simplified" | "corrective" | "simplified_corrective"

format*string

Valor en"a4" | "ticket_80" | "ticket_58"

locale*string

Valor en"es" | "en" | "ca"

base_preset*string

Valor en"classic" | "modern" | "minimal" | "corporative" | "premium"

layout_version*string

configuration*

Configuración estructurada de la plantilla. Una revisión schema_version 1 lleva solo las claves originales; una revisión schema_version 2 añade header, table, legal_footer, page.density, typography.zone_scale, sections.privacy_text, sections.general_terms, sections.general_terms_placement, sections.section_titles, sections.show_generic_privacy_notice y legal_footer.notices_placement, además del tamaño de marca xl y la columna total_with_tax. Las claves nuevas no aparecen al leer una revisión schema_version 1. Solo texto plano; la columna de descripción sigue visible. El contenido fiscal lo impone el renderizador del documento.

source*

document_type*string

Valor en"invoice" | "quote" | "proforma" | "delivery-note"

purpose*string

Valor en"complete" | "simplified" | "corrective" | "simplified_corrective"

format*string

Valor en"a4" | "ticket_80" | "ticket_58"

locale*string

Valor en"es" | "en" | "ca"

base_preset*string

Valor en"classic" | "modern" | "minimal" | "corporative" | "premium"

layout_version*string

configuration*

source*

document_type?string

Valor en"invoice" | "quote" | "proforma" | "delivery-note"

purpose?string

Valor en"complete" | "simplified" | "corrective" | "simplified_corrective"

format?string

Valor en"a4" | "ticket_80" | "ticket_58"

locale?string

Valor en"es" | "en" | "ca"

base_preset*string

Valor en"classic" | "modern" | "minimal" | "corporative" | "premium"

layout_version*string

configuration*

source?

document_type*string

Valor en"invoice" | "quote" | "proforma" | "delivery-note"

purpose*string

Valor en"complete" | "simplified" | "corrective" | "simplified_corrective"

format*string

Valor en"a4" | "ticket_80" | "ticket_58"

locale*string

Valor en"es" | "en" | "ca"

base_preset?string

Valor en"classic" | "modern" | "minimal" | "corporative" | "premium"

layout_version?string

configuration?

source*

document_type?string

Valor en"invoice" | "quote" | "proforma" | "delivery-note"

purpose?string

Valor en"complete" | "simplified" | "corrective" | "simplified_corrective"

format?string

Valor en"a4" | "ticket_80" | "ticket_58"

locale?string

Valor en"es" | "en" | "ca"

base_preset*string

Valor en"classic" | "modern" | "minimal" | "corporative" | "premium"

layout_version*string

configuration*

source?

Padre conservado exacto, UUID del propietario actual auténtico, destino anulable explícito, política captured/current_legal y CAS entero positivo. El token revision_precondition devuelto autoriza únicamente una revisión explícita; no puede autorizar emitir, enviar, aceptar ni firmar.

document_type*string

Valor en"invoice" | "quote" | "proforma" | "delivery-note"

purpose*string

Valor en"complete" | "simplified" | "corrective" | "simplified_corrective"

format*string

Valor en"a4" | "ticket_80" | "ticket_58"

locale*string

Valor en"es" | "en" | "ca"

base_preset?string

Valor en"classic" | "modern" | "minimal" | "corporative" | "premium"

layout_version?string

configuration?

source*

document_type*string

purpose*string

format*string

locale*string

Valor en"es" | "en" | "ca"

source*

Vista previa independiente de una sustitución de factura simplificada. Solo es válida con document_type: invoice, purpose: complete y format: a4; la tríada visual (base_preset, layout_version, configuration) debe omitirse por completo; si no, la petición devuelve 422 pdf_presentation_invalid. No se guarda ni se sustituye nada.

Cuerpo de la respuesta

`application/json`

Ejemplo de petición

const apiKey = process.env.FACTUAREA_API_KEY;if (!apiKey) throw new Error("Set FACTUAREA_API_KEY");const response = await fetch("https://api.factuarea.com/v1/companies/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01/pdf-template-previews", {  method: "POST",  headers: { Authorization: `Bearer ${apiKey}`, ...{"Accept":"application/json","Content-Type":"application/json","Idempotency-Key":"erp-2026-public-api-v1-pdf_template_previews-create"} },  body: JSON.stringify({  "document_type": "invoice",  "purpose": "complete",  "format": "a4",  "locale": "es",  "source": {    "kind": "example",    "scenario": "standard"  },  "base_preset": "classic",  "layout_version": "1",  "configuration": {    "branding": {      "mode": "logo",      "size": "small"    },    "typography": {      "font_family": "roboto",      "font_size": 10    },    "colors": {      "text": "#1f2937",      "line": "#e5e7eb",      "primary": "#1d4ed8",      "secondary": "#64748b",      "table_header_bg": "#f1f5f9",      "table_border": "#cbd5e1",      "alternate_row": "#f8fafc"    },    "page": {      "orientation": "portrait",      "margins_mm": {        "top": 15,        "right": 15,        "bottom": 15,        "left": 15      },      "show_page_numbers": true    },    "watermark": {      "enabled": true,      "text": "BORRADOR"    },    "titles": {      "invoice": {        "es": "Factura",        "en": "Invoice",        "ca": "Factura"      },      "simplified": {        "es": "Factura simplificada",        "en": "Simplified invoice",        "ca": "Factura simplificada"      },      "corrective": {        "es": "Factura rectificativa",        "en": "Corrective invoice",        "ca": "Factura rectificativa"      },      "f3": {        "es": "Factura sustitutiva",        "en": "Substitute invoice",        "ca": "Factura substitutiva"      },      "quote": {        "es": "Presupuesto",        "en": "Quote",        "ca": "Pressupost"      },      "proforma": {        "es": "Factura proforma",        "en": "Proforma invoice",        "ca": "Factura proforma"      },      "delivery-note": {        "es": "Albarán",        "en": "Delivery note",        "ca": "Albarà"      }    },    "columns": [      {        "id": "description",        "visible": true,        "labels": {          "es": "Descripción",          "en": "Description",          "ca": "Descripció"        }      }    ],    "company_fields": {      "name": true,      "tax_id": true,      "address": true,      "email": true,      "phone": true,      "website": true    },    "client_fields": {      "name": true,      "tax_id": true,      "address": true,      "email": true,      "phone": true    },    "custom_field_definitions": [      {        "key": "purchase_order",        "label": {          "es": "Pedido de compra",          "en": "Purchase order",          "ca": "Comanda de compra"        },        "visible": true      }    ],    "sections": {      "notes_mode": "yes",      "footer_text": {        "es": "Gracias por su confianza.",        "en": "Thank you for your business.",        "ca": "Gràcies per la vostra confiança."      },      "conditions_text": {        "es": "Pago a 30 días desde la fecha de emisión.",        "en": "Payment within 30 days of the issue date.",        "ca": "Pagament a 30 dies des de la data d'emissió."      },      "commercial_register_text": {        "es": "Inscrita en el Registro Mercantil de Madrid.",        "en": "Registered in the Madrid Commercial Register.",        "ca": "Inscrita al Registre Mercantil de Madrid."      },      "show_payment_info": true,      "show_bank_details": true    }  }}),});if (!response.ok) throw new Error(await response.text());if (response.status !== 204) console.log(await response.json());

Ejemplo de respuesta

{
  "data": {
    "id": "019e8a32-91ab-7c47-8d3e-2b6f1a9c4e07",
    "purpose": "preview",
    "state": "ready",
    "document_id": null,
    "source_kind": "example",
    "context_authority": "illustrative",
    "context_fingerprint": "f3c9ac83c234dd96b77e9405011ba3f7c60206a90d80a5a3cd1a60950ec3307e",
    "expected_preview_context_fingerprint": null,
    "source_token": null,
    "selection_version": null,
    "template_revision_id": null,
    "commercial_identity_revision_id": null,
    "artifact_fingerprint": "3ee3a67f32dedac38a70fe80e8abbca575dd522498c7b035babdb7765698b15a",
    "sha256": "d29bee4ddbe190e6b0810e8efa2f99296433917d2c90e6cf726a9546f8a7c710",
    "size_bytes": 48213,
    "expires_at": "2026-10-15T11:42:18.000000Z",
    "effective_font": {
      "requested_family": "inter",
      "effective_family": "Inter",
      "files": [
        {
          "name": "pdf/layouts/v1/fonts/Inter-variable.ttf",
          "sha256": "88e44d564deda3edaae388f942ac9a8432c7eeb6ad9e15fff58b8e4a9d7c33d6"
        },
        {
          "name": "pdf/layouts/v1/fonts/Inter-italic-variable.ttf",
          "sha256": "a30cf214781a103ef47f815863a8204127da09c08435c9254fe8a79ab0ca9086"
        },
        {
          "name": "pdf/layouts/v1/fonts/LiberationSans-Regular.ttf",
          "sha256": "4de25902c05149a8ac7d01103cb22b04512ca32c42c5e22ab6c8e25929fab717"
        },
        {
          "name": "pdf/layouts/v1/fonts/LiberationSans-Bold.ttf",
          "sha256": "56839678d77eb0608b7a91f69a59c6d7ef55a7ffe88740b1a56df0b2a4e0b51b"
        },
        {
          "name": "pdf/layouts/v1/fonts/LiberationSans-Italic.ttf",
          "sha256": "453e66623b5e5b2999759ef2192862e7a4326b3f9e527b40c1ad3bb1ee177829"
        },
        {
          "name": "pdf/layouts/v1/fonts/LiberationSans-BoldItalic.ttf",
          "sha256": "b8f4dc5fc85a11593d60696ac4d5fed9430bc419d6d2f209ab5e39d34dfd22e2"
        },
        {
          "name": "pdf/layouts/v1/fonts/JetBrainsMono-Regular.ttf",
          "sha256": "0c06ec9f2129b2bffee4bddaab40ae45c3026c8dfb050825edb2ee0179fda35e"
        },
        {
          "name": "pdf/layouts/v1/fonts/JetBrainsMono-Bold.ttf",
          "sha256": "3d8eafe83d407ba97e695900c148fce20c1da4e6f0e7c05ebc2f4acc0ac3ca63"
        },
        {
          "name": "pdf/layouts/v1/fonts/JetBrainsMono-Italic.ttf",
          "sha256": "c55d5c8aa80a1736ec78058bfd85fdd6e2fc7ce0248b527aa30a3f8d2d6bcf04"
        },
        {
          "name": "pdf/layouts/v1/fonts/JetBrainsMono-BoldItalic.ttf",
          "sha256": "249c6e7602c3b8aecec9850cb20b5c5bb059960d6dfef0edfefeabe395fa4890"
        }
      ],
      "reasons": []
    },
    "warnings": [],
    "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/019e8a32-91ab-7c47-8d3e-2b6f1a9c4e07",
    "download_url": "https://api.factuarea.com/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/pdf-artifacts/019e8a32-91ab-7c47-8d3e-2b6f1a9c4e07/download",
    "retry_after": null,
    "error": null,
    "unavailable_reason": null
  }
}

POST /v1/companies/{company}/pdf-template-previews · 202 prepared example preview

{
  "data": {
    "id": "019e8a32-91ab-7c47-8d3e-2b6f1a9c4e07",
    "purpose": "preview",
    "state": "prepared",
    "document_id": null,
    "source_kind": "example",
    "context_authority": "illustrative",
    "context_fingerprint": "f3c9ac83c234dd96b77e9405011ba3f7c60206a90d80a5a3cd1a60950ec3307e",
    "expected_preview_context_fingerprint": null,
    "source_token": null,
    "selection_version": null,
    "template_revision_id": null,
    "commercial_identity_revision_id": null,
    "artifact_fingerprint": "3ee3a67f32dedac38a70fe80e8abbca575dd522498c7b035babdb7765698b15a",
    "sha256": null,
    "size_bytes": null,
    "expires_at": "2026-10-15T11:42:18.000000Z",
    "effective_font": {
      "requested_family": "inter",
      "effective_family": "Inter",
      "files": [
        {
          "name": "pdf/layouts/v1/fonts/Inter-variable.ttf",
          "sha256": "88e44d564deda3edaae388f942ac9a8432c7eeb6ad9e15fff58b8e4a9d7c33d6"
        },
        {
          "name": "pdf/layouts/v1/fonts/Inter-italic-variable.ttf",
          "sha256": "a30cf214781a103ef47f815863a8204127da09c08435c9254fe8a79ab0ca9086"
        },
        {
          "name": "pdf/layouts/v1/fonts/LiberationSans-Regular.ttf",
          "sha256": "4de25902c05149a8ac7d01103cb22b04512ca32c42c5e22ab6c8e25929fab717"
        },
        {
          "name": "pdf/layouts/v1/fonts/LiberationSans-Bold.ttf",
          "sha256": "56839678d77eb0608b7a91f69a59c6d7ef55a7ffe88740b1a56df0b2a4e0b51b"
        },
        {
          "name": "pdf/layouts/v1/fonts/LiberationSans-Italic.ttf",
          "sha256": "453e66623b5e5b2999759ef2192862e7a4326b3f9e527b40c1ad3bb1ee177829"
        },
        {
          "name": "pdf/layouts/v1/fonts/LiberationSans-BoldItalic.ttf",
          "sha256": "b8f4dc5fc85a11593d60696ac4d5fed9430bc419d6d2f209ab5e39d34dfd22e2"
        },
        {
          "name": "pdf/layouts/v1/fonts/JetBrainsMono-Regular.ttf",
          "sha256": "0c06ec9f2129b2bffee4bddaab40ae45c3026c8dfb050825edb2ee0179fda35e"
        },
        {
          "name": "pdf/layouts/v1/fonts/JetBrainsMono-Bold.ttf",
          "sha256": "3d8eafe83d407ba97e695900c148fce20c1da4e6f0e7c05ebc2f4acc0ac3ca63"
        },
        {
          "name": "pdf/layouts/v1/fonts/JetBrainsMono-Italic.ttf",
          "sha256": "c55d5c8aa80a1736ec78058bfd85fdd6e2fc7ce0248b527aa30a3f8d2d6bcf04"
        },
        {
          "name": "pdf/layouts/v1/fonts/JetBrainsMono-BoldItalic.ttf",
          "sha256": "249c6e7602c3b8aecec9850cb20b5c5bb059960d6dfef0edfefeabe395fa4890"
        }
      ],
      "reasons": []
    },
    "warnings": [],
    "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/019e8a32-91ab-7c47-8d3e-2b6f1a9c4e07",
    "download_url": null,
    "retry_after": 1,
    "error": null,
    "unavailable_reason": null
  }
}

POST /v1/companies/{company}/pdf-template-previews · 202 prepared persisted draft preview

{
  "data": {
    "id": "019e8a32-91ab-7c47-8d3e-2b6f1a9c4e07",
    "purpose": "preview",
    "state": "prepared",
    "document_id": "019e8a2f-17de-7a63-b5c2-8e4d0f6a3b19",
    "source_kind": "persisted_draft",
    "context_authority": "delivery_precondition",
    "context_fingerprint": "f3c9ac83c234dd96b77e9405011ba3f7c60206a90d80a5a3cd1a60950ec3307e",
    "expected_preview_context_fingerprint": "94fa19b5964a12ad723630ecbd82163fad26dfb651fd252fa3512ca2c55283d3",
    "source_token": "15dcaa3fb565dfd9b01e24ad81ffd47f4bfb1c280658083da79cb64eb1d5eacf",
    "selection_version": 3,
    "template_revision_id": "019e8a1c-0b3a-7e95-9c64-d27a8f1b5e30",
    "commercial_identity_revision_id": "019e8a1d-5e72-7f01-8b3a-4c9d6e2a1f58",
    "artifact_fingerprint": "3ee3a67f32dedac38a70fe80e8abbca575dd522498c7b035babdb7765698b15a",
    "sha256": null,
    "size_bytes": null,
    "expires_at": "2026-10-15T11:42:18.000000Z",
    "effective_font": {
      "requested_family": "inter",
      "effective_family": "Inter",
      "files": [
        {
          "name": "pdf/layouts/v1/fonts/Inter-variable.ttf",
          "sha256": "88e44d564deda3edaae388f942ac9a8432c7eeb6ad9e15fff58b8e4a9d7c33d6"
        },
        {
          "name": "pdf/layouts/v1/fonts/Inter-italic-variable.ttf",
          "sha256": "a30cf214781a103ef47f815863a8204127da09c08435c9254fe8a79ab0ca9086"
        },
        {
          "name": "pdf/layouts/v1/fonts/LiberationSans-Regular.ttf",
          "sha256": "4de25902c05149a8ac7d01103cb22b04512ca32c42c5e22ab6c8e25929fab717"
        },
        {
          "name": "pdf/layouts/v1/fonts/LiberationSans-Bold.ttf",
          "sha256": "56839678d77eb0608b7a91f69a59c6d7ef55a7ffe88740b1a56df0b2a4e0b51b"
        },
        {
          "name": "pdf/layouts/v1/fonts/LiberationSans-Italic.ttf",
          "sha256": "453e66623b5e5b2999759ef2192862e7a4326b3f9e527b40c1ad3bb1ee177829"
        },
        {
          "name": "pdf/layouts/v1/fonts/LiberationSans-BoldItalic.ttf",
          "sha256": "b8f4dc5fc85a11593d60696ac4d5fed9430bc419d6d2f209ab5e39d34dfd22e2"
        },
        {
          "name": "pdf/layouts/v1/fonts/JetBrainsMono-Regular.ttf",
          "sha256": "0c06ec9f2129b2bffee4bddaab40ae45c3026c8dfb050825edb2ee0179fda35e"
        },
        {
          "name": "pdf/layouts/v1/fonts/JetBrainsMono-Bold.ttf",
          "sha256": "3d8eafe83d407ba97e695900c148fce20c1da4e6f0e7c05ebc2f4acc0ac3ca63"
        },
        {
          "name": "pdf/layouts/v1/fonts/JetBrainsMono-Italic.ttf",
          "sha256": "c55d5c8aa80a1736ec78058bfd85fdd6e2fc7ce0248b527aa30a3f8d2d6bcf04"
        },
        {
          "name": "pdf/layouts/v1/fonts/JetBrainsMono-BoldItalic.ttf",
          "sha256": "249c6e7602c3b8aecec9850cb20b5c5bb059960d6dfef0edfefeabe395fa4890"
        }
      ],
      "reasons": [
        "policy_filtered"
      ]
    },
    "warnings": [
      {
        "path": "configuration.typography.font_family",
        "reason": "policy_filtered"
      }
    ],
    "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/019e8a32-91ab-7c47-8d3e-2b6f1a9c4e07",
    "download_url": null,
    "retry_after": 1,
    "error": null,
    "unavailable_reason": null
  }
}

Se envió la cabecera X-Active-Profile retirada

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_unknown",
    "subcode": "retired_active_profile_header",
    "message": "La cabecera 'X-Active-Profile' fue retirada de la API v1: la empresa efectiva se indica en el segmento de empresa de la ruta.",
    "param": "X-Active-Profile",
    "doc_url": "https://docs.factuarea.com/guides/errors#parameter_unknown",
    "request_id": "req_01J8Y3M2Q40000000000000001"
  }
}

Cabecera Factuarea-Version malformada

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid_format",
    "message": "El header 'Factuarea-Version' debe tener formato YYYY-MM-DD.",
    "param": "Factuarea-Version",
    "doc_url": "https://docs.factuarea.com/guides/errors#parameter_invalid_format",
    "request_id": "req_01J8Y3M2Q40000000000000002"
  }
}

Factuarea-Version no admitida

{
  "error": {
    "type": "invalid_request_error",
    "code": "unsupported_api_version",
    "message": "La versión de API '2020-01-01' no está soportada.",
    "param": "Factuarea-Version",
    "doc_url": "https://docs.factuarea.com/guides/errors#unsupported_api_version",
    "request_id": "req_01J8Y3M2Q40000000000000003"
  }
}

Falta la API key

{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "No se ha proporcionado una API key válida en el header Authorization.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#missing_api_key",
    "request_id": "req_01HKQS5N8VR7QXJ9K3T6BWPMZA"
  }
}

Formato de API key no válido

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "La API key no tiene el formato esperado (debe empezar por fact_live_ o fact_test_).",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#invalid_api_key",
    "request_id": "req_01HKQS5N9JTQM7HVTQP3FBN5XB"
  }
}

API key revocada

{
  "error": {
    "type": "authentication_error",
    "code": "api_key_revoked",
    "message": "Esta API key ha sido revocada y ya no es válida.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#api_key_revoked",
    "request_id": "req_01HKQS5NA8K7E2V9YDZWMT6RJC"
  }
}

API key caducada

{
  "error": {
    "type": "authentication_error",
    "code": "api_key_expired",
    "message": "Esta API key ha caducado.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#api_key_expired",
    "request_id": "req_01HKQS5NAPIKEYEXPIRED00008"
  }
}

IP de la petición fuera de la lista de acceso de la API key

{
  "error": {
    "type": "authentication_error",
    "code": "ip_not_allowed",
    "message": "La IP 203.0.113.10 no está autorizada para esta API key.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#ip_not_allowed",
    "request_id": "req_01HKQS5NIPNOTALLOWED000009"
  }
}

POST /v1/companies/{company}/pdf-template-previews · 403 insufficient_scope

{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_scope",
    "message": "Esta operación requiere el scope 'pdf_templates:read'. Tu API key solo tiene los scopes: pdfs:read, invoices:read.",
    "doc_url": "https://docs.factuarea.com/guides/errors#insufficient_scope",
    "request_id": "req_0d60719e68c05a960b628b572f"
  }
}

POST /v1/companies/{company}/pdf-template-previews · 403 pdf_template_access_denied

{
  "error": {
    "type": "authorization_error",
    "code": "pdf_template_access_denied",
    "message": "No tienes permisos para realizar esta operación en la biblioteca PDF.",
    "doc_url": "https://docs.factuarea.com/guides/errors#pdf_template_access_denied",
    "request_id": "req_82fe569ae72b27420234a66dbd"
  }
}

Empresa desactivada

{
  "error": {
    "type": "authorization_error",
    "code": "company_inactive",
    "message": "Esta empresa está desactivada. Actívala para operar.",
    "param": "company",
    "doc_url": "https://docs.factuarea.com/guides/errors#company_inactive",
    "request_id": "req_01J8Y3M2Q40000000000000005"
  }
}

POST /v1/companies/{company}/pdf-template-previews · 404 pdf_presentation_not_found

{
  "error": {
    "type": "not_found_error",
    "code": "pdf_presentation_not_found",
    "message": "Presentación documental no encontrada.",
    "param": "presentation_id",
    "doc_url": "https://docs.factuarea.com/guides/errors#pdf_presentation_not_found",
    "request_id": "req_4e5cbe850541070f0fb9d4149a"
  }
}

Empresa no encontrada o fuera del alcance de la API key

{
  "error": {
    "type": "not_found_error",
    "code": "profile_not_found",
    "message": "La empresa indicada no existe o no está en el ámbito de tu credencial.",
    "param": "company",
    "doc_url": "https://docs.factuarea.com/guides/errors#profile_not_found",
    "request_id": "req_01J8Y3M2Q40000000000000004"
  }
}

La presentación del documento ha cambiado

{
  "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",
    "doc_url": "https://docs.factuarea.com/guides/errors#pdf_presentation_conflict",
    "request_id": "req_01J8Y3M2Q4CF0000000000PPC1"
  }
}

El contexto de presentación revisado ha cambiado

{
  "error": {
    "type": "conflict_error",
    "code": "pdf_presentation_context_changed",
    "message": "El contexto de presentación ha cambiado. Actualiza la vista previa antes de continuar.",
    "param": "expected_preview_context_fingerprint",
    "doc_url": "https://docs.factuarea.com/guides/errors#pdf_presentation_context_changed",
    "request_id": "req_01J8Y3M2Q4CF0000000000PCC1"
  }
}

{
  "error": {
    "type": "not_found_error",
    "code": "pdf_signature_personal_data_forgotten",
    "message": "Los datos personales de la firma de esta presentación se han eliminado.",
    "param": "presentation_id",
    "doc_url": "https://docs.factuarea.com/guides/errors#pdf_signature_personal_data_forgotten",
    "request_id": "req_5b86554ae7ba1182b2c5ab0e86"
  }
}

POST /v1/companies/{company}/pdf-template-previews · 422 pdf_presentation_invalid

{
  "error": {
    "type": "invalid_request_error",
    "code": "pdf_presentation_invalid",
    "message": "La presentación documental no es válida.",
    "param": "source.kind",
    "details": {
      "field_errors": {
        "source.kind": [
          "La presentación documental no es válida."
        ]
      }
    },
    "doc_url": "https://docs.factuarea.com/guides/errors#pdf_presentation_invalid",
    "request_id": "req_d8802ab68b27b274a76bb7d210"
  }
}

POST /v1/companies/{company}/pdf-template-previews · 422 pdf_presentation_not_ready

{
  "error": {
    "type": "invalid_request_error",
    "code": "pdf_presentation_not_ready",
    "message": "La presentación revisionada aún no está disponible para esta empresa.",
    "param": "presentation",
    "doc_url": "https://docs.factuarea.com/guides/errors#pdf_presentation_not_ready",
    "request_id": "req_27570e3dee7cb853be46040ec0"
  }
}

POST /v1/companies/{company}/pdf-template-previews · 422 idempotency_key_required

{
  "error": {
    "type": "invalid_request_error",
    "code": "idempotency_key_required",
    "message": "La operación «public-api.v1.pdf_template_previews.create» exige la cabecera Idempotency-Key desde el 2026-12-01. Envía una clave única por operación (un UUID sirve) y, si reintenta, repite exactamente la misma clave para que la operación no se ejecute dos veces.",
    "param": "Idempotency-Key",
    "doc_url": "https://docs.factuarea.com/guides/errors#idempotency_key_required",
    "request_id": "req_5848fe276c1713986882882d97"
  }
}

Idempotency key reutilizada con un payload distinto

{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_key_reused",
    "message": "La Idempotency-Key 'order-2026-0001' ya se usó con un payload distinto.",
    "param": "Idempotency-Key",
    "doc_url": "https://docs.factuarea.com/guides/errors#idempotency_key_reused",
    "request_id": "req_01J8Y3M2Q40000000000000007"
  }
}

Formato de Idempotency-Key no válido

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_param_format",
    "message": "La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.",
    "param": "Idempotency-Key",
    "doc_url": "https://docs.factuarea.com/guides/errors#invalid_param_format",
    "request_id": "req_01J8Y3M2Q40000000000000008"
  }
}

Límite de peticiones superado

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Has excedido el rate limit de 60 peticiones por minuto. Reintenta tras 30 segundos.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#rate_limit_exceeded",
    "request_id": "req_01HKQS5NKW1C6W9T4G5H0JBZVL"
  }
}

Demasiados fallos de autenticación (bloqueo temporal)

{
  "error": {
    "type": "authentication_error",
    "code": "too_many_auth_failures",
    "message": "Has alcanzado el número máximo de intentos de autenticación fallidos. La API key queda bloqueada temporalmente. Reintenta tras el tiempo indicado en `Retry-After`.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#too_many_auth_failures",
    "request_id": "req_01HKQS5NKW1C6W9T4G5H0JBZVM"
  }
}

Demasiadas subidas simultáneas en curso

{
  "error": {
    "type": "rate_limit_error",
    "code": "upload_in_flight_budget_exceeded",
    "message": "Tu empresa tiene demasiadas subidas en curso a la vez: este archivo ocupa 10 MB y el margen simultáneo es de 120 MB. Espera a que terminen las subidas en marcha y vuelve a intentarlo dentro de 45 segundos.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#upload_in_flight_budget_exceeded",
    "request_id": "req_01HKQS5NUPLOADINFLIGHT005"
  }
}

Límite de peticiones de toda la empresa superado (todas las claves combinadas)

{
  "error": {
    "type": "rate_limit_error",
    "code": "company_rate_limit_exceeded",
    "message": "Tu empresa ha superado su límite conjunto de 900 peticiones por minuto, contando a la vez todas sus credenciales. Es un techo de la empresa, así que repartir el tráfico no lo eleva. Reintenta en 12 segundos, o solicita una ampliación de plan si necesitas más capacidad.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#company_rate_limit_exceeded",
    "request_id": "req_01HKQS5NCOMPANYRATELIMIT06"
  }
}

Cuota mensual de toda la empresa agotada (todas las claves combinadas)

{
  "error": {
    "type": "rate_limit_error",
    "code": "company_monthly_quota_exceeded",
    "message": "Tu empresa ha agotado su cuota conjunta de 150000 peticiones de este mes, contando a la vez todas sus credenciales. Es un techo de la empresa, así que repartir el tráfico no lo eleva. El contador se reinicia el día 1 del mes siguiente; solicita una ampliación de plan si necesitas más volumen antes.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#company_monthly_quota_exceeded",
    "request_id": "req_01HKQS5NCOMPANYMONTHLY0007"
  }
}

Cuota mensual de la API key agotada

{
  "error": {
    "type": "rate_limit_error",
    "code": "monthly_quota_exceeded",
    "message": "Has agotado tu cuota mensual de 100000 requests. Mejora tu plan para obtener una cuota superior.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#monthly_quota_exceeded",
    "request_id": "req_01HKQS5NMONTHLYQUOTA000011"
  }
}

Límite de peticiones de la cartera superado (todos los NIF de la cuenta juntos)

{
  "error": {
    "type": "rate_limit_error",
    "code": "portfolio_rate_limit_exceeded",
    "message": "La cartera de tu cuenta ha superado su límite conjunto de 1800 peticiones por minuto, contando a la vez todos sus NIF. Es un techo de la cartera, así que repartir el tráfico entre NIF no lo eleva. Reintenta en 12 segundos, o solicita una ampliación de plan si necesitas más capacidad.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#portfolio_rate_limit_exceeded",
    "request_id": "req_01HKQS5NPORTFOLIORATE00012"
  }
}

Cuota mensual de la cartera agotada (todos los NIF de la cuenta juntos)

{
  "error": {
    "type": "rate_limit_error",
    "code": "portfolio_monthly_quota_exceeded",
    "message": "La cartera de tu cuenta ha agotado su cuota conjunta de 300000 peticiones de este mes, contando a la vez todos sus NIF. Es un techo de la cartera, así que repartir el tráfico entre NIF no lo eleva. El contador se reinicia el día 1 del mes siguiente; solicita una ampliación de plan si necesitas más volumen antes.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#portfolio_monthly_quota_exceeded",
    "request_id": "req_01HKQS5NPORTFOLIOMONTH0013"
  }
}

POST /v1/companies/{company}/pdf-template-previews · 500 pdf_payload_resource_unavailable

{
  "error": {
    "type": "api_error",
    "code": "pdf_payload_resource_unavailable",
    "message": "Los recursos necesarios para preparar el PDF no están disponibles.",
    "doc_url": "https://docs.factuarea.com/guides/errors#pdf_payload_resource_unavailable",
    "request_id": "req_0bd96c24d54214198c35a3b8b8"
  }
}

POST /v1/companies/{company}/pdf-template-previews · 500 pdf_engine_profile_unavailable

{
  "error": {
    "type": "api_error",
    "code": "pdf_engine_profile_unavailable",
    "message": "El perfil de generación PDF no está disponible.",
    "doc_url": "https://docs.factuarea.com/guides/errors#pdf_engine_profile_unavailable",
    "request_id": "req_7d2a5e9c41b0f6e38c1d4a2b95"
  }
}

POST /v1/companies/{company}/pdf-template-previews · 500 pdf_original_layout_unavailable

{
  "error": {
    "type": "api_error",
    "code": "pdf_original_layout_unavailable",
    "message": "El diseño con el que se generó el PDF original ya no está disponible en esta versión de Factuarea.",
    "doc_url": "https://docs.factuarea.com/guides/errors#pdf_original_layout_unavailable",
    "request_id": "req_12066565a264a793d6f41f1b75"
  }
}

POST /v1/companies/{company}/pdf-template-previews · 500 pdf_original_unavailable

{
  "error": {
    "type": "api_error",
    "code": "pdf_original_unavailable",
    "message": "El PDF original no está disponible.",
    "doc_url": "https://docs.factuarea.com/guides/errors#pdf_original_unavailable",
    "request_id": "req_ee96b519c02bb0af3e297767cd"
  }
}

POST /v1/companies/{company}/pdf-template-previews · 500 pdf_original_corrupt

{
  "error": {
    "type": "api_error",
    "code": "pdf_original_corrupt",
    "message": "No se puede verificar la integridad del PDF original.",
    "doc_url": "https://docs.factuarea.com/guides/errors#pdf_original_corrupt",
    "request_id": "req_d9153a22d973586f6bdd642e54"
  }
}

POST /v1/companies/{company}/pdf-template-previews · 503 pdf_artifact_not_ready

{
  "error": {
    "type": "service_unavailable_error",
    "code": "pdf_artifact_not_ready",
    "message": "El artefacto PDF todavía no está preparado.",
    "doc_url": "https://docs.factuarea.com/guides/errors#pdf_artifact_not_ready",
    "request_id": "req_01K7F4EFRY5NFBSGYCN89SK2XQ"
  }
}

POST /v1/companies/{company}/pdf-template-previews · 503 pdf_engine_unreachable

{
  "error": {
    "type": "service_unavailable_error",
    "code": "pdf_engine_unreachable",
    "message": "El motor de generación PDF no está disponible en este momento. Inténtalo de nuevo en unos instantes.",
    "doc_url": "https://docs.factuarea.com/guides/errors#pdf_engine_unreachable",
    "request_id": "req_e7a134b9d2c05f86031e9a7b4d"
  }
}

Crear una vista previa de plantilla de PDF

Authorization

Parámetros de ruta

Headers

Cuerpo de la petición

Cuerpo de la respuesta

200application/json

202application/json

400application/json

401application/json

403application/json

404application/json

409application/json

410application/json

422application/json

429application/json

500application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`