Publish a PDF template revision

Append an immutable revision with the new compatibility, base preset, brand or configuration.

Returns 201 with the new revision. - First read the impact with action=publish, then send its expected_impact_fingerprint and the expected_version of the template; a changed impact returns 409. - Objects in configuration are merged deeply and lists replaced; the kind is fixed, so document_kind is rejected. - Earlier revisions and the documents issued with them are not modified.
Requires pdf_templates:write; supports Idempotency-Key.

Authorization

AuthorizationBearer <token>

Your API key as a bearer token: fact_live_… in production, fact_test_… in sandbox. See the authentication guide.

In: header

Path Parameters

company*string

Public identifier (UUID v7) of the company. Get it from GET /v1/me (data.scope[].id).

Formatuuid

template*string

Public identifier (UUID v7) of the PDF template.

Formatuuid

Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns 422 idempotency_key_reused; the values of secret fields (password, secret…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the Idempotency guide.

Length1 <= length <= 255

Factuarea-Version?string

Pin the API version (YYYY-MM-DD, Stripe-style date versioning) for this request; omit to use the key's pinned version, or the latest if none. Unsupported version → 400 unsupported_api_version; malformed → 400 parameter_invalid_format. The effective version is echoed in the Factuarea-Version response header. See the Versioning guide.

Formatdate

Request Body

application/json

Internal reversible write: idempotency follows the current policy; a supplied key is replayed before CAS. Unknown fields are rejected. Until the company is prepared for revisioned templates (tenant initialization pending or revisioned rendering off) every library write returns 422 pdf_presentation_not_ready before any precondition or effect; reads stay available and no Retry-After applies.

TypeScript Definitions

Use the request body type in TypeScript.

revision_id?string

Match^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$

Formatuuid

expected_version*integer

Range1 <= value

expected_impact_fingerprint*string

Match^[0-9a-f]{64}$

base_preset?string

Value in"classic" | "modern" | "minimal" | "corporative" | "premium"

configuration?

Partial structured template configuration: only the sections and fields to change, merged over the stored configuration. A write always stores the revision as schema_version 2: the new keys you omit take their default values (preset, separate, body, standard, m, empty texts, after_totals), which render exactly like a schema_version 1 configuration. Plain text only; description column remains visible. Fiscal content is enforced by the document renderer.

supported_types?array<>

Items1 <= items

supported_purposes?

supported_formats?array<>

Items1 <= items

commercial_identity_id?|null

Response Body

`application/json`

Request example

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-templates/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01/revisions", {  method: "POST",  headers: { Authorization: `Bearer ${apiKey}`, ...{"Accept":"application/json","Content-Type":"application/json","Idempotency-Key":"erp-2026-public-api-v1-pdf_templates-publish_revision"} },  body: JSON.stringify({  "expected_version": 1,  "expected_impact_fingerprint": "a3f1c0de5b7e49d28c6a1f0b9e3d4c5a7b8e2f1d0c9b8a7e6d5c4b3a2f1e0d9c"}),});if (!response.ok) throw new Error(await response.text());if (response.status !== 204) console.log(await response.json());

Response example

{
  "base_preset": "corporative",
  "commercial_identity_id": "019e1a2b-5a07-7c83-8d14-2f6a40c9b0d4",
  "configuration": {
    "branding": {
      "mode": "logo",
      "size": "medium"
    },
    "client_fields": {
      "address": true,
      "email": false,
      "name": true,
      "phone": false,
      "tax_id": true
    },
    "colors": {
      "alternate_row": "#f9fafb",
      "line": "#d1d5db",
      "primary": "#0f766e",
      "secondary": "#64748b",
      "table_border": "#e5e7eb",
      "table_header_bg": "#eff6ff",
      "text": "#1f2937"
    },
    "columns": [
      {
        "id": "description",
        "labels": {
          "ca": null,
          "en": null,
          "es": null
        },
        "visible": true
      },
      {
        "id": "sku",
        "labels": {
          "ca": null,
          "en": null,
          "es": null
        },
        "visible": true
      },
      {
        "id": "quantity",
        "labels": {
          "ca": null,
          "en": null,
          "es": null
        },
        "visible": true
      },
      {
        "id": "unit",
        "labels": {
          "ca": null,
          "en": null,
          "es": null
        },
        "visible": false
      },
      {
        "id": "unit_price",
        "labels": {
          "ca": null,
          "en": null,
          "es": null
        },
        "visible": true
      },
      {
        "id": "discount",
        "labels": {
          "ca": null,
          "en": null,
          "es": null
        },
        "visible": true
      },
      {
        "id": "tax",
        "labels": {
          "ca": null,
          "en": null,
          "es": null
        },
        "visible": true
      },
      {
        "id": "total",
        "labels": {
          "ca": null,
          "en": null,
          "es": null
        },
        "visible": true
      },
      {
        "id": "photo",
        "labels": {
          "ca": null,
          "en": null,
          "es": null
        },
        "visible": false
      },
      {
        "id": "variant",
        "labels": {
          "ca": null,
          "en": null,
          "es": null
        },
        "visible": false
      },
      {
        "id": "pack",
        "labels": {
          "ca": null,
          "en": null,
          "es": null
        },
        "visible": false
      },
      {
        "id": "batch",
        "labels": {
          "ca": null,
          "en": null,
          "es": null
        },
        "visible": false
      },
      {
        "id": "expiry",
        "labels": {
          "ca": null,
          "en": null,
          "es": null
        },
        "visible": false
      },
      {
        "id": "commercial_weight",
        "labels": {
          "ca": null,
          "en": null,
          "es": null
        },
        "visible": false
      }
    ],
    "company_fields": {
      "address": true,
      "email": true,
      "name": true,
      "phone": true,
      "tax_id": true,
      "website": false
    },
    "custom_field_definitions": [],
    "page": {
      "margins_mm": {
        "bottom": 15,
        "left": 15,
        "right": 15,
        "top": 15
      },
      "orientation": "portrait",
      "show_page_numbers": true
    },
    "sections": {
      "commercial_register_text": {
        "ca": null,
        "en": null,
        "es": null
      },
      "conditions_text": {
        "ca": null,
        "en": null,
        "es": null
      },
      "footer_text": {
        "ca": null,
        "en": null,
        "es": "Gracias por confiar en Servicios Ejemplo SL."
      },
      "notes_mode": "auto",
      "show_bank_details": true,
      "show_payment_info": true
    },
    "titles": {
      "corrective": {
        "ca": null,
        "en": null,
        "es": null
      },
      "delivery-note": {
        "ca": null,
        "en": null,
        "es": null
      },
      "f3": {
        "ca": null,
        "en": null,
        "es": null
      },
      "invoice": {
        "ca": "Factura",
        "en": "Invoice",
        "es": "Factura"
      },
      "proforma": {
        "ca": null,
        "en": null,
        "es": null
      },
      "quote": {
        "ca": null,
        "en": null,
        "es": null
      },
      "simplified": {
        "ca": null,
        "en": null,
        "es": null
      }
    },
    "typography": {
      "font_family": "inter",
      "font_size": 10
    },
    "watermark": {
      "enabled": false,
      "text": ""
    }
  },
  "id": "019e1a2b-8f21-7b35-a374-4c8e72b3d0b2",
  "layout_version": "1",
  "number": 2,
  "schema_version": 1,
  "supported_formats": [
    "a4"
  ],
  "supported_purposes": {
    "delivery-note": [
      "complete"
    ],
    "invoice": [
      "complete",
      "simplified",
      "corrective",
      "simplified_corrective"
    ],
    "proforma": [
      "complete"
    ],
    "quote": [
      "complete"
    ]
  },
  "supported_types": [
    "invoice",
    "quote",
    "proforma",
    "delivery-note"
  ],
  "template_id": "019e1a2b-7c10-7a41-8b52-3d9f60a1c001",
  "document_kind": "commercial"
}

Retired X-Active-Profile header sent

{
  "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"
  }
}

Malformed Factuarea-Version header

{
  "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"
  }
}

Unsupported Factuarea-Version

{
  "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"
  }
}

Missing 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"
  }
}

Invalid API key format

{
  "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"
  }
}

Revoked API key

{
  "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"
  }
}

Expired API key

{
  "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"
  }
}

Request IP outside the API key allowlist

{
  "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"
  }
}

API key lacks required scope

{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_scope",
    "message": "Esta API key no tiene el scope requerido para esta operación.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#insufficient_scope",
    "request_id": "req_01HKQS5NBC3P8M1KX4V7SLNHQD"
  }
}

Plan upgrade required

{
  "error": {
    "type": "authorization_error",
    "code": "feature_not_available_in_plan",
    "message": "Esta funcionalidad requiere el plan empresario o superior. Actualiza tu suscripción para acceder.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#feature_not_available_in_plan",
    "request_id": "req_01HKQS5NCK4V9N2L7Y8X3WPMRE"
  }
}

Plan without public API access

{
  "error": {
    "type": "authorization_error",
    "code": "addon_not_active",
    "message": "Tu plan actual no incluye acceso a la API pública. Contrata o renueva un plan de Factuarea para usar la API.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#addon_not_active",
    "request_id": "req_01HKQS5NDP5W0Q3M8Z9A4BVSNF"
  }
}

Module not available with a test key

{
  "error": {
    "type": "authorization_error",
    "code": "module_not_available_in_sandbox",
    "message": "El módulo \"verifactu\" no está disponible en modo de pruebas. Usa una clave fact_live_ para operar sobre este recurso.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#module_not_available_in_sandbox",
    "request_id": "req_01HKQS5NMODULESANDBOX00010"
  }
}

Account provider privilege not granted

{
  "error": {
    "type": "authorization_error",
    "code": "privileged_scope_required",
    "message": "Esta operación exige el privilegio de proveedor de cuentas (accounts:*) y la persona que emitió la clave debe ser propietaria o administradora de la cuenta",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#privileged_scope_required",
    "request_id": "req_01HKQS5NPRIVILEGEDSCOPE001"
  }
}

Operation of the owning account on a tax ID reached through a relation

{
  "error": {
    "type": "authorization_error",
    "code": "forbidden_action",
    "message": "Esta operación solo la puede hacer la cuenta dueña del NIF: con un acceso por relación entre cuentas no está disponible.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#forbidden_action",
    "request_id": "req_01HKQS5NRELATIONNIFOWNER01"
  }
}

Company deactivated

{
  "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"
  }
}

Resource not found

{
  "error": {
    "type": "not_found_error",
    "code": "resource_not_found",
    "message": "El recurso solicitado no existe o pertenece a otra empresa.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#resource_not_found",
    "request_id": "req_01HKQS5NEQ6X1R4N9B0C5DWTPG"
  }
}

Company not found or outside the API key scope

{
  "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"
  }
}

The template or commercial identity changed since you read it

{
  "error": {
    "type": "conflict_error",
    "code": "pdf_template_version_conflict",
    "message": "La plantilla PDF ha cambiado. Actualiza los datos antes de volver a guardar.",
    "param": "expected_version",
    "details": {
      "current_version": 4,
      "recovery": "reload_or_keep_local"
    },
    "doc_url": "https://docs.factuarea.com/guides/errors#pdf_template_version_conflict",
    "request_id": "req_01J8Y3M2Q4CF0000000000PTV1"
  }
}

The reviewed impact changed

{
  "error": {
    "type": "conflict_error",
    "code": "pdf_library_impact_conflict",
    "message": "El impacto de la operación ha cambiado. Revísalo antes de confirmar.",
    "param": "expected_impact_fingerprint",
    "doc_url": "https://docs.factuarea.com/guides/errors#pdf_library_impact_conflict",
    "request_id": "req_01J8Y3M2Q4CF0000000000PLI1"
  }
}

pdf_commercial_identity_required

{
  "error": {
    "type": "invalid_request_error",
    "code": "pdf_commercial_identity_required",
    "message": "El modo de marca de la plantilla requiere una identidad comercial disponible; elige una o define la de la empresa.",
    "param": "commercial_identity_id",
    "doc_url": "https://docs.factuarea.com/guides/errors#pdf_commercial_identity_required",
    "request_id": "req_01KFPD3T5MPL8A2B4C6D8E0FGH"
  }
}

invalid_pdf_template_configuration

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_pdf_template_configuration",
    "message": "El tipo de plantilla no se puede cambiar al publicar una revisión.",
    "param": "document_kind",
    "doc_url": "https://docs.factuarea.com/guides/errors#invalid_pdf_template_configuration",
    "request_id": "req_01KFPD3T5MPL8A2B4C6D8E0FGH"
  }
}

Parameter failed validation

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "El campo `name` es obligatorio y no puede estar vacío.",
    "param": "name",
    "doc_url": "https://docs.factuarea.com/guides/errors#parameter_invalid",
    "request_id": "req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"
  }
}

Invalid Idempotency-Key format

{
  "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_01HKQS5NIDEMPKEYFORMAT0007"
  }
}

Idempotency key reused with different body

{
  "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_01HKQS5NHT9A4U7R2E3F8GZWTJ"
  }
}

Rate limit exceeded

{
  "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"
  }
}

Too many authentication failures (temporary lockout)

{
  "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"
  }
}

Too many concurrent uploads in flight

{
  "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"
  }
}

Company-wide rate limit exceeded (all keys combined)

{
  "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"
  }
}

Company-wide monthly quota exhausted (all keys combined)

{
  "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"
  }
}

Monthly quota of the API key exhausted

{
  "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"
  }
}

Portfolio rate limit exceeded (all tax IDs of the account combined)

{
  "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"
  }
}

Portfolio monthly quota exhausted (all tax IDs of the account combined)

{
  "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"
  }
}

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Ha ocurrido un error inesperado. Si persiste, contacta con soporte adjuntando el request_id.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#internal_error",
    "request_id": "req_01HKQS5NLX2D7X0U5H6J1KCAWM"
  }
}

Publish a PDF template revision

Authorization

Path Parameters

Headers

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

404application/json

409application/json

422application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`