API de compresión de PDF – Reducir el tamaño de archivos PDF

Los PDF grandes – expedientes de investigación, peritajes, documentos escaneados – causan problemas con los límites de correo electrónico, ralentizan el almacenamiento y hacen que la gestión documental sea lenta. En nuestro despacho, un solo peritaje podía ocupar 30 MB. Una API de compresión de PDF que reduzca el tamaño de archivo preservando la legibilidad facilitaría considerablemente el compartir y archivar documentos.

Por qué desarrollar una solución propia de compresión de PDF lleva semanas

Quien quiera desarrollarlo por su cuenta descubre rápidamente que Ghostscript, qpdf y pikepdf pueden reducir PDF – pero hay que elegir niveles de compresión, considerar diferentes estructuras de PDF y evitar pérdidas de calidad. El submuestreo de imágenes, la incrustación de fuentes y la compresión de flujos tienen cada uno sus propias consideraciones. Construir una API de compresión de PDF confiable con resultados consistentes requiere experimentación.

Cómo la API de compresión de PDF de MaraDocs lo resuelve en minutos

La API de MaraDocs ofrece pdf.optimize para compresión inteligente. Cargar un PDF, validarlo y luego optimizarlo. El resultado es típicamente significativamente más pequeño preservando la calidad – la API se encarga internamente del submuestreo de imágenes, compresión de flujos e incrustación de fuentes. No hay que instalar Ghostscript, ajustar parámetros ni adivinar entre calidad vs. tamaño. Una llamada y se obtiene un identificador optimizado listo para correo electrónico, archivado o el siguiente paso de procesamiento.

Flujo de trabajo de compresión de PDF: Cargar, validar, optimizar

Cargar el PDF, validar virus y formato, luego llamar a pdf.optimize. La API aplica compresión inteligente – submuestreo de imágenes, optimización de flujos – y devuelve un identificador optimizado. Puede descargarse o pasarse a composición, procesamiento de adjuntos de correo o archivado. La optimización encaja naturalmente como último paso antes de la entrega en cualquier pipeline. Los archivos permanecen en el workspace; no es necesario volver a cargarlos entre validación y optimización.

Lo que diferencia a MaraDocs: Workspaces, vista web y normativa alemana de protección de datos

La mayoría de las API de documentos obligan a cargar, procesar, descargar y volver a cargar para el siguiente paso. En MaraDocs, los archivos permanecen en el workspace. Encadenar con OCR, composición o procesamiento de correo – el identificador de PDF optimizado fluye directamente a la siguiente operación. Sin necesidad de volver a cargar, menos viajes de ida y vuelta.

Si la calidad de compresión debe verificarse manualmente – o se desea una comparación antes-después – puede abrirse app.maradocs.io para revisión manual. Los usuarios obtienen control manual completo cuando la automatización alcanza sus límites.

Todo el procesamiento se realiza en Alemania (Maramia GmbH), cifrado en reposo y durante la transmisión. Los workspaces expiran después de 7 días. Ningún dato sale de la UE. Para flujos de trabajo documentales sensibles en materia de protección de datos, esto es relevante.

Código TypeScript para reducir el tamaño de PDF

Referencia de API: data/upload, pdf/validate, pdf/optimize, data/download/pdf

import { MaraDocsClient } from "@maramia/maradocs-sdk-ts";
import { okPdf } from "@maramia/maradocs-sdk-ts/models/pdf";

const client = new MaraDocsClient({ workspaceSecret: workspace_secret });

// Cargar, validar, optimizar, descargar
const uploaded = await client.data.upload(pdfFile);
const validated = await client.pdf.validate({
  unvalidated_file_handle: uploaded.unvalidated_file_handle,
});
const pdfHandle = okPdf(validated);

const optimized = await client.pdf.optimize({ pdf_handle: pdfHandle });

const blob = await client.data.downloadPdf({ pdf_handle: optimized.pdf_handle });

Código Python para compresión de PDF

Referencia de API: data/upload, pdf/validate, pdf/optimize, data/download/pdf

# pip install python-decouple requests
"""Compress a PDF using MaraDocs. Set ACCOUNT_SECRET in .env or environment."""

import sys
import time
from pathlib import Path

import requests
from decouple import config

API_URL = "https://api.maradocs.io/v1"


def create_workspace() -> dict:
    """Create a workspace and return auth headers."""
    r = requests.post(
        f"{API_URL}/workspace",
        headers={"Authorization": f"Bearer {config('ACCOUNT_SECRET')}"},
        json={"subaccount": None},
    )
    ws = r.json()
    return {"Authorization": f"Bearer {ws['workspace_secret']}"}


def upload_file(path: Path, auth: dict) -> dict:
    """Upload a file via two-step flow (signed URL + S3 POST). Returns unvalidated_file_handle."""
    data = path.read_bytes()
    resp = requests.post(
        f"{API_URL}/data/upload",
        headers={**auth, "Content-Type": "application/json"},
        json={"name": path.name, "size": len(data)},
    ).json()
    requests.post(
        resp["post_url"],
        data=resp.get("post_header", {}),
        files={"file": (path.name, data, "application/pdf")},
    )
    return resp["unvalidated_file_handle"]


def run_job(path: str, payload: dict, auth: dict, timeout: int = 60) -> dict:
    """Run a job and poll until complete. Returns the result (unwraps response if present)."""
    url = f"{API_URL}/{path}"
    r = requests.post(url, headers=auth, json=payload).json()
    job_id = r["job_id"]
    start = time.time()
    while time.time() - start < timeout:
        poll_r = requests.get(f"{url}/{job_id}", headers=auth)
        if poll_r.status_code == 200:
            return poll_r.json()
    raise TimeoutError(f"Job {path} timed out")


def download_pdf(pdf_handle: str, auth: dict) -> bytes:
    """Request signed URL and fetch PDF bytes."""
    r = requests.post(
        f"{API_URL}/data/download/pdf",
        headers=auth,
        json={"pdf_handle": pdf_handle},
    )
    info = r.json()
    dl = requests.get(info["url"], headers=info.get("headers", {}))
    return dl.content


def main() -> None:
    pdf_path = Path(sys.argv[1]) if len(sys.argv) > 1 else Path("input.pdf")
    auth = create_workspace()
    handle = upload_file(pdf_path, auth)
    validate = run_job("pdf/validate", {"unvalidated_file_handle": handle}, auth)
    pdf_handle = validate["response"]["pdf_handle"]
    optimized = run_job("pdf/optimize", {"pdf_handle": pdf_handle}, auth)
    compressed_handle = optimized.get("response", optimized).get("pdf_handle")
    Path("compressed.pdf").write_bytes(download_pdf(compressed_handle, auth))
    print("compressed.pdf created")


if __name__ == "__main__":
    main()

Resumen y próximos pasos

Una API de compresión de PDF que reduce el tamaño de archivo preservando la calidad está disponible. MaraDocs se encarga de la optimización como parte de un flujo de trabajo documental más amplio. Otros casos de uso relacionados: Procesamiento de PDF, Procesamiento de correo electrónico e Imagen en página en blanco.

---

Pruébalo ahora: API de MaraDocs | SDK de TypeScript

---