Generar un PDF

POST /v1/render produce un PDF a partir de una plantilla y datos. Una generación correcta cuesta un crédito; una generación que falla no cuesta nada.

Hay dos formas de indicar qué generar, y cada una tiene su guía:

• Con una plantilla guardada: guardas la plantilla en tu cuenta y envías su id junto con los datos.
• Con HTML directo: envías el HTML y los datos en la misma petición, y no se guarda nada.

Esta página es la referencia de la petición y la respuesta, que son iguales en ambas.

Petición

{
  "template_id": "0194f2c0-…",
  "data": { "customer": "Ana Souza", "total": "1234.50" },
  "locale": "es-ES",
  "title": "Factura 2025-0042",
  "output": "pdf",
  "strict": false
}

Campo	Tipo	Significado
template_id	string	Una plantilla guardada en tu cuenta. Envía este o html.
html	string	HTML en línea, tratado como plantilla. Envía este o template_id.
data	objeto	Valores de la plantilla. Por defecto {}.
locale	string	Una etiqueta BCP 47, como es-ES. Por defecto, el idioma de la plantilla y después el de tu cuenta.
title	string	El título del documento guardado en el PDF.
output	"pdf" o "url"	pdf (por defecto) devuelve el archivo. url devuelve un JSON con un enlace firmado.
strict	booleano	Rechaza el documento si usa algo que el servicio no admite del todo.

Enviar template_id y html a la vez, o ninguno de los dos, es un 400.

Respuesta: el PDF

Con output: "pdf" el cuerpo es el PDF (Content-Type: application/pdf) y estas cabeceras lo describen:

Cabecera	Valor
X-Render-Id	Id de esta generación.
X-Pages	Número de páginas.
X-Credits-Remaining	Tu saldo después de esta generación.
X-Diagnostics	Número de elementos que el servicio no admitió del todo; consulta Validar.

Respuesta: un enlace

Con output: "url" el PDF se conserva un tiempo y recibes un JSON:

{
  "id": "0194f2c1-…",
  "url": "https://api.example.com/v1/files/0194f2c1-…?exp=1760000000&sig=…",
  "expires_at": 1760000000,
  "pages": 1,
  "bytes": 27003,
  "credits_remaining": 999,
  "diagnostics": []
}

El enlace funciona sin clave de API hasta expires_at, y después deja de funcionar. Cuánto tiempo se conservan los archivos depende de tu plan; consulta Planes y créditos. Comparte el enlace con tu cliente, o descarga el archivo una vez y guárdalo tú.

Modo estricto

Por defecto, una función no admitida se ignora y se informa. Con strict: true la petición falla con 422 strict_mode_rejected y lista todos los diagnósticos, sin usar crédito. Úsalo en las pruebas para asegurarte de que una plantilla sigue limpia.

Límites

Una generación se rechaza cuando la entrada, el HTML expandido, el número de páginas o el tiempo superan los límites de tu plan, y cuando el servicio está al límite de su capacidad. Consulta Errores y límites.