rustedf.cloud
Menú

Cómo generar un PDF desde HTML en Node.js

Publicado el 2 min de lectura

En Node.js, convertir HTML en PDF suele significar incluir un motor de renderizado en tu contenedor y mantenerlo sano. Con una API es una petición HTTP, y Node ya tiene fetch. Esta guía muestra una función reutilizable y cómo servir el resultado desde Express y desde una ruta de Next.js, con la API de rustedf.cloud.

Una función que devuelve el PDF

const API = 'https://api.rustedf.com/v1/render';
export async function renderPdf(templateId, data, locale = 'es-ES') {
const response = await fetch(API, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.RUSTEDF_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ template_id: templateId, locale, data }),
signal: AbortSignal.timeout(40_000),
});
if (!response.ok) {
const { error } = await response.json().catch(() => ({}));
throw new Error(error?.message ?? `Error al generar (${response.status})`);
}
return Buffer.from(await response.arrayBuffer());
}

fetch es nativo desde Node.js 18. El cuerpo de una respuesta correcta es el PDF, así que arrayBuffer() te da los bytes. En un fallo, el cuerpo es un JSON con un code estable y un message.

Guarda la clave en una variable de entorno en el servidor. Fija el tiempo límite por encima del límite de tu plan, para que tu petición no se rinda antes que el servicio.

Para enviar HTML en lugar del id de una plantilla guardada, usa { html: '<h1>{{ name }}</h1>', data }. Pasa todo lo que haya escrito un usuario por data, y no dentro de la cadena de HTML: los valores de data se escapan, y el propio HTML se lee como una plantilla.

Reintentar cuando el servicio está ocupado

Un 429 (límite de peticiones) o un 503 (ocupado) trae una cabecera Retry-After.

export async function renderPdfWithRetry(templateId, data, locale, attempts = 3) {
for (let attempt = 1; ; attempt++) {
try {
return await renderPdf(templateId, data, locale);
} catch (error) {
if (attempt >= attempts || !error.retryAfter) throw error;
await new Promise(resolve => setTimeout(resolve, error.retryAfter * 1000));
}
}
}

Para que funcione, haz que renderPdf adjunte la espera al error que lanza:

if (!response.ok) {
const { error } = await response.json().catch(() => ({}));
const failure = new Error(error?.message ?? `Error al generar (${response.status})`);
if ([429, 503].includes(response.status)) {
failure.retryAfter = Number(response.headers.get('Retry-After')) || 2;
}
throw failure;
}

Una generación que falla no gasta crédito, así que reintentar es seguro.

Desde Express

import express from 'express';
import { renderPdf } from './render-pdf.js';
const app = express();
app.get('/facturas/:numero.pdf', async (req, res) => {
try {
const pdf = await renderPdf(process.env.INVOICE_TEMPLATE_ID, await construirDatosDeFactura(req.params.numero));
res.type('application/pdf').set('Content-Disposition', `inline; filename="factura-${req.params.numero}.pdf"`).send(pdf);
} catch (error) {
console.error(error);
res.status(502).json({ error: 'No se pudo generar la factura.' });
}
});

Desde una ruta de Next.js

app/api/factura/route.ts
import { renderPdf } from '@/lib/render-pdf';
export async function GET(request: Request) {
const numero = new URL(request.url).searchParams.get('numero') ?? '';
const pdf = await renderPdf(process.env.INVOICE_TEMPLATE_ID!, await construirDatosDeFactura(numero));
return new Response(pdf, {
headers: {
'Content-Type': 'application/pdf',
'Content-Disposition': `inline; filename="factura-${numero}.pdf"`,
},
});
}

La clave nunca sale del servidor: el navegador llama a tu ruta, y tu ruta llama a la API.

Errores que conviene tratar

Estado code Qué hacer
401 unauthorized La clave falta, es incorrecta o está revocada.
402 insufficient_credits Se acabaron los créditos. No se generó nada.
422 invalid_template La plantilla o los datos fallaron. Lee el message.
429 rate_limited Espera el Retry-After y reintenta.
503 busy El servicio está ocupado. Espera el Retry-After y reintenta.
504 render_timeout El documento tardó más de lo que permite tu plan.

Ejecuta POST /v1/validate con el mismo cuerpo mientras construyes la plantilla: enumera todo lo que el servicio no admitió por completo, sin devolver el PDF ni gastar crédito.

Consulta Generar un PDF, Autenticación y Errores y límites.

← Todos los artículos