rustedf.cloud
Menú

Cómo generar un PDF desde HTML en Java y Spring Boot

Publicado el 2 min de lectura

En Java, convertir HTML en PDF suele significar meter una biblioteca de renderizado, sus fuentes y sus dependencias en el build y mantenerlas al día con el runtime. Con una API es una petición HTTP, y el JDK tiene un cliente HTTP desde la versión 11. Esta guía muestra un cliente pequeño y un controlador de Spring Boot que devuelve el archivo, con la API de rustedf.cloud.

Un cliente sobre el HttpClient estándar

import com.fasterxml.jackson.databind.ObjectMapper;
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.util.Map;
public final class PdfClient {
private static final URI RENDER = URI.create("https://api.rustedf.com/v1/render");
private final HttpClient http = HttpClient.newHttpClient();
private final ObjectMapper json = new ObjectMapper();
private final String key;
public PdfClient(String key) {
this.key = key;
}
public byte[] render(String templateId, Map<String, Object> data, String locale)
throws IOException, InterruptedException {
String body = json.writeValueAsString(
Map.of("template_id", templateId, "locale", locale, "data", data));
HttpRequest request = HttpRequest.newBuilder(RENDER)
.timeout(Duration.ofSeconds(40))
.header("Authorization", "Bearer " + key)
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(body))
.build();
HttpResponse<byte[]> response = http.send(request, HttpResponse.BodyHandlers.ofByteArray());
if (response.statusCode() != 200) {
String message = json.readTree(response.body()).path("error").path("message")
.asText("Error al generar (" + response.statusCode() + ")");
throw new IllegalStateException(message);
}
return response.body();
}
}

Una respuesta correcta es el propio PDF, así que los bytes son el archivo. En un fallo, el cuerpo es un JSON con un code estable y un message, que el cliente lee para construir su excepción.

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. Mantén la clave fuera del código fuente, en una variable de entorno o en un almacén de secretos.

Un controlador de Spring Boot

import java.util.Map;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;
@RestController
class FacturaController {
private final PdfClient pdf;
private final String templateId;
FacturaController(PdfClient pdf, @Value("${rustedf.invoice-template}") String templateId) {
this.pdf = pdf;
this.templateId = templateId;
}
@GetMapping("/facturas/{numero}/pdf")
ResponseEntity<byte[]> factura(@PathVariable String numero) throws Exception {
byte[] archivo = pdf.render(templateId, Map.of(
"number", numero,
"customer", Map.of("name", "Ana Souza"),
"total", "2040.50"), "es-ES");
return ResponseEntity.ok()
.contentType(MediaType.APPLICATION_PDF)
.header(HttpHeaders.CONTENT_DISPOSITION, "inline; filename=\"factura-" + numero + ".pdf\"")
.body(archivo);
}
}
@org.springframework.context.annotation.Configuration
class PdfConfig {
@Bean
PdfClient pdfClient(@Value("${rustedf.key}") String key) {
return new PdfClient(key);
}
}

Pon rustedf.key en application.properties como rustedf.key=${RUSTEDF_KEY}, para que el valor venga del entorno.

Para enviar HTML en lugar del id de una plantilla guardada, usa una entrada html en lugar de template_id. 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. Una generación que falla no gasta crédito, así que reintentar es seguro: lee response.headers().firstValue("Retry-After"), espera ese número de segundos y envía la petición de nuevo, un número limitado de veces.

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