rustedf.cloud
Menu

Como gerar PDF a partir de HTML em Node.js

Publicado em 2 min de leitura

Em Node.js, transformar HTML em PDF costuma significar embarcar um motor de renderização no seu contêiner e mantê-lo saudável. Com uma API, é uma requisição HTTP, e o Node já tem fetch. Este guia mostra uma função reutilizável e como servir o resultado do Express e de uma rota do Next.js, com a API do rustedf.cloud.

Uma função que devolve o PDF

const API = 'https://api.rustedf.com/v1/render';
export async function renderPdf(templateId, data, locale = 'pt-BR') {
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 ?? `Falha ao gerar (${response.status})`);
}
return Buffer.from(await response.arrayBuffer());
}

O fetch é nativo a partir do Node.js 18. O corpo de uma resposta bem-sucedida é o PDF, então arrayBuffer() entrega os bytes. Em uma falha, o corpo é um JSON com um code estável e uma message.

Guarde a chave em uma variável de ambiente no servidor. Defina o tempo limite acima do limite do seu plano, para que a sua requisição não desista antes do serviço.

Para enviar HTML em vez do id de um template salvo, use { html: '<h1>{{ name }}</h1>', data }. Passe tudo o que um usuário digitou por data, e não dentro da string de HTML: os valores em data são escapados, e o próprio HTML é lido como um template.

Tentar de novo quando o serviço está ocupado

Um 429 (limite de requisições) ou um 503 (ocupado) traz um cabeçalho 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 isso funcionar, faça o renderPdf anexar a espera ao erro que ele lança:

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

Uma geração que falha não custa crédito, então tentar de novo é seguro.

No Express

import express from 'express';
import { renderPdf } from './render-pdf.js';
const app = express();
app.get('/faturas/:numero.pdf', async (req, res) => {
try {
const pdf = await renderPdf(process.env.INVOICE_TEMPLATE_ID, await montarDadosDaFatura(req.params.numero));
res.type('application/pdf').set('Content-Disposition', `inline; filename="fatura-${req.params.numero}.pdf"`).send(pdf);
} catch (error) {
console.error(error);
res.status(502).json({ error: 'Não foi possível gerar a fatura.' });
}
});

Em uma rota do Next.js

app/api/fatura/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 montarDadosDaFatura(numero));
return new Response(pdf, {
headers: {
'Content-Type': 'application/pdf',
'Content-Disposition': `inline; filename="fatura-${numero}.pdf"`,
},
});
}

A chave nunca sai do servidor: o navegador chama a sua rota, e a sua rota chama a API.

Erros que vale tratar

Status code O que fazer
401 unauthorized A chave está ausente, errada ou revogada.
402 insufficient_credits Os créditos acabaram. Nada foi gerado.
422 invalid_template O template ou os dados falharam. Leia a message.
429 rate_limited Espere o Retry-After e tente de novo.
503 busy O serviço está ocupado. Espere o Retry-After e tente de novo.
504 render_timeout O documento levou mais do que o seu plano permite.

Rode POST /v1/validate com o mesmo corpo enquanto monta o template: ele lista tudo o que o serviço não suportou por completo, sem devolver o PDF nem usar crédito.

Leia Gerar um PDF, Autenticação e Erros e limites.

  • Código e integrações

    Gerar PDF no ASP.NET Core: MVC, Razor Pages e minimal APIs

    Transforme uma view Razor em PDF no ASP.NET Core com uma chamada de API: renderizador de views, view pronta para impressão, action MVC e handler do Razor Pages.

    3 min de leitura

  • Código e integrações

    Converter página web em PDF em C# sem navegador headless

    Busque uma página com HttpClient e transforme o HTML em PDF com uma chamada de API em C#. Quais páginas isso atende, quais não e como conferir antes de depender.

    3 min de leitura

  • Código e integrações

    Gerador de relatório PDF em C#: tabela paginada com totais

    Monte um relatório em PDF em C# a partir de uma lista de objetos: tabela com cabeçalho repetido em cada página, total, número de página e contagem de páginas.

    3 min de leitura

← Todos os posts