Gotenberg como API

Gotenberg convierte HTML, Markdown, páginas web y documentos de Office en PDF, con Chromium y LibreOffice dentro, y une, divide, aplana, añade marcas de agua, cifra y convierte PDF a PDF/A o PDF/UA. Esta API ejecuta Gotenberg 8.38 y sirve sus propias rutas bajo una URL base:

https://api.pagespool.com/v1/gotenberg

Así, POST /forms/chromium/convert/html pasa a ser POST https://api.pagespool.com/v1/gotenberg/forms/chromium/convert/html, con los mismos campos de formulario, las mismas cabeceras Gotenberg-* (Gotenberg-Output-Filename, Gotenberg-Trace) y la misma salida.

Lo que cuesta

Cada solicitud a una ruta /forms/... cuesta 1 crédito, sea cual sea el número de páginas o la salida. GET /v1/gotenberg/health y GET /v1/gotenberg/version son gratis. Una solicitud que responde con un estado de error no cuesta nada.

Una cuenta gratuita recibe 100 créditos al mes y 10 más al día. Los planes de pago están en la página de precios, y un solo saldo cubre todos los motores de este sitio.

Límites

• 26 MB por solicitud. Un cuerpo más grande recibe un 413 payload_too_large.
• 55 segundos por solicitud. Una conversión más larga recibe un 504 engine_timeout. Divide los trabajos grandes en varias solicitudes.
• Sin webhooks ni downloadFrom. La respuesta siempre lleva el resultado. Una cabecera Gotenberg-Webhook-* recibe un 400 webhooks_unsupported, y un campo downloadFrom, un 400 download_from_unsupported.
• Solo URL públicas. Chromium no carga páginas ni recursos de redes privadas: /forms/chromium/convert/url con una URL así recibe un 403.
• Sin Factur-X. La ruta /forms/pdfengines/factur-x no se ofrece.

Los errores del propio Gotenberg vuelven con su estado y su mensaje, como un problema RFC 9457 (application/problem+json) cuyo code es engine_rejected. Cuando Gotenberg no está disponible, la respuesta es un 503 engine_unavailable con Retry-After: 30.

Tu clave de API

Cada ruta /forms/... necesita una clave de API. Crea una en tu cuenta tras registrarte y envíala de una de estas tres formas:

• la cabecera X-API-Key: <key>;
• la cabecera Authorization: Bearer <key>;
• HTTP Basic, con cualquier nombre de usuario y la clave como contraseña (-u x:<key> en curl, o https://x:<key>@… en un cliente que solo acepta una URL).

Los clientes de Gotenberg envían las credenciales con Basic, así que es la forma que usan los ejemplos de abajo. Una clave ausente o incorrecta recibe un 401.

Inicio rápido: curl

Convierte un archivo HTML (Gotenberg necesita que se llame index.html):

curl -u "x:$API_KEY" \
  -F files=@index.html \
  https://api.pagespool.com/v1/gotenberg/forms/chromium/convert/html \
  -o out.pdf

Convierte un documento de Word con LibreOffice:

curl -u "x:$API_KEY" \
  -F files=@report.docx \
  https://api.pagespool.com/v1/gotenberg/forms/libreoffice/convert \
  -o report.pdf

Une dos PDF:

curl -u "x:$API_KEY" \
  -F files=@a.pdf -F files=@b.pdf \
  https://api.pagespool.com/v1/gotenberg/forms/pdfengines/merge \
  -o merged.pdf

Inicio rápido: chromiumly (Node.js)

import { Chromiumly, HtmlConverter } from "chromiumly";

Chromiumly.configure({
  endpoint: "https://api.pagespool.com/v1/gotenberg",
  username: "x",
  password: process.env.API_KEY,
});

const pdf = await new HtmlConverter().convert({ html: "index.html" });

Inicio rápido: gotenberg-php

gotenberg-php construye una solicitud PSR-7, así que la clave se añade como cabecera:

use Gotenberg\Gotenberg;
use Gotenberg\Stream;

$request = Gotenberg::chromium('https://api.pagespool.com/v1/gotenberg')
    ->pdf()
    ->html(Stream::path('index.html'))
    ->withHeader('Authorization', 'Basic ' . base64_encode('x:' . getenv('API_KEY')));

$filename = Gotenberg::save($request, __DIR__);

Inicio rápido: gotenberg-client (Python)

import os
from pathlib import Path

from gotenberg_client import GotenbergClient

with GotenbergClient(
    "https://api.pagespool.com/v1/gotenberg", auth=("x", os.environ["API_KEY"]), timeout=60
) as client:
    with client.chromium.html_to_pdf() as route:
        response = route.index(Path("index.html")).run()
        response.to_file(Path("out.pdf"))

Servidor MCP

Los agentes de IA llegan a Gotenberg por su propio servidor MCP:

https://api.pagespool.com/mcp/gotenberg/

Tiene dos herramientas, html_to_pdf (Chromium) y office_to_pdf (LibreOffice). Cada una acepta un archivo de hasta 4 MB, en base64 o como enlace https público, cuesta 1 crédito y necesita una clave de API. El PDF vuelve como un enlace de descarga que funciona una hora. La página de conexión muestra cómo añadir el servidor a un cliente.

Alojarlo tú o esta API

Gotenberg es de código abierto y funciona en cualquier sitio como una sola imagen Docker, gotenberg/gotenberg. Esa imagen lleva Chromium y LibreOffice, así que necesita la memoria correspondiente (aquí funciona con 2 GB), y mantenerla segura en una red es cosa tuya: sus opciones que rechazan direcciones privadas, los límites de cuerpo y de tiempo, el tamaño de la cola y las actualizaciones.

Alójalo tú cuando conviertas muchos documentos al día, necesites webhooks o debas mantener los documentos dentro de tu propia red. Usa esta API cuando quieras Gotenberg sin mantenerlo: una clave de API y un saldo de créditos, compartidos con los demás motores de este sitio.

Pruébalo sin cuenta

La herramienta gratuita Word a PDF convierte un documento de hasta 4 MB con la misma ruta de LibreOffice, en el navegador.

Gotenberg es una marca de su titular; pagespool no está afiliado a él.

Preguntas frecuentes

¿Funciona mi cliente de Gotenberg con esta API?

Sí, si te permite fijar la URL base y credenciales HTTP Basic. Apúntalo a la URL base /v1/gotenberg de la API, con cualquier nombre de usuario y tu clave de API como contraseña. Las rutas y los campos de formulario son los de Gotenberg.

¿Puedo usar webhooks o downloadFrom?

No. Cada solicitud se responde de forma síncrona con el resultado, así que una cabecera Gotenberg-Webhook-* recibe un 400 webhooks_unsupported. Envía los archivos en el formulario: un campo downloadFrom recibe un 400 download_from_unsupported.

¿Cuánto cuesta una conversión fallida?

Nada. Cada solicitud que responde con un estado de error, incluidos los errores del propio Gotenberg, recupera su crédito.