rustedf.cloud
Menú

Cómo generar un PDF desde HTML en Python

Publicado el 2 min de lectura

En Python, convertir HTML en PDF suele significar instalar una biblioteca de renderizado y sus dependencias del sistema, y luego mantenerlas funcionando en cada entorno. Con una API es una petición HTTP, que requests ya hace bien. Esta guía muestra una función pequeña y cómo usarla en Django y FastAPI, con la API de rustedf.cloud.

Una función que devuelve el PDF

import os
import requests
API = "https://api.rustedf.com/v1/render"
def render_pdf(template_id: str, data: dict, locale: str = "es-ES") -> bytes:
response = requests.post(
API,
headers={"Authorization": f"Bearer {os.environ['RUSTEDF_KEY']}"},
json={"template_id": template_id, "locale": locale, "data": data},
timeout=40,
)
if response.status_code != 200:
error = response.json().get("error", {})
raise RuntimeError(error.get("message", f"Error al generar ({response.status_code})"))
return response.content

json= fija la cabecera Content-Type por ti. Una respuesta correcta es el propio PDF, así que response.content son los bytes del archivo. En un fallo, el cuerpo es un JSON con un code estable y un message.

Guarda la clave en una variable de entorno. 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 el 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, nunca 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. Un bucle corto basta:

import time
def render_pdf_with_retry(template_id, data, locale="es-ES", attempts=3):
for attempt in range(attempts):
response = requests.post(
API,
headers={"Authorization": f"Bearer {os.environ['RUSTEDF_KEY']}"},
json={"template_id": template_id, "locale": locale, "data": data},
timeout=40,
)
if response.status_code in (429, 503) and attempt < attempts - 1:
try:
wait = int(response.headers.get("Retry-After", "2"))
except ValueError:
wait = 2
time.sleep(wait)
continue
break
if response.status_code != 200:
error = response.json().get("error", {})
raise RuntimeError(error.get("message", f"Error al generar ({response.status_code})"))
return response.content

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

En Django

from django.conf import settings
from django.http import HttpResponse
def factura_pdf(request, numero):
pdf = render_pdf(settings.RUSTEDF_INVOICE_TEMPLATE, construir_datos_de_factura(numero), "es-ES")
return HttpResponse(
pdf,
content_type="application/pdf",
headers={"Content-Disposition": f'inline; filename="factura-{numero}.pdf"'},
)

En FastAPI

from fastapi import FastAPI
from fastapi.responses import Response
app = FastAPI()
@app.get("/facturas/{numero}.pdf")
def factura_pdf(numero: str):
pdf = render_pdf(INVOICE_TEMPLATE, construir_datos_de_factura(numero), "es-ES")
return Response(content=pdf, media_type="application/pdf")

La función es un def normal, así que FastAPI la ejecuta en un hilo de trabajo y la llamada bloqueante no detiene el bucle de eventos.

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.

Antes de depender de una plantilla, ejecuta POST /v1/validate con el mismo cuerpo: 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