API di Compressione PDF – Ridurre la Dimensione dei File PDF

I PDF di grandi dimensioni – fascicoli processuali, perizie, documenti scansionati – causano problemi con i limiti delle email, rallentano l'archiviazione e rendono lenta la gestione documentale. Nel nostro studio legale, una singola perizia poteva arrivare a 30 MB. Un'API di compressione PDF che riduce la dimensione del file preservando la leggibilità renderebbe molto più semplice la condivisione e l'archiviazione.

Perché sviluppare una soluzione di compressione PDF personalizzata richiede settimane

Chi vuole realizzarla autonomamente scopre rapidamente che Ghostscript, qpdf e pikepdf possono ridurre i PDF – ma bisogna scegliere i livelli di compressione, considerare diverse strutture PDF ed evitare perdite di qualità. Il downsampling delle immagini, l'incorporamento dei font e la compressione degli stream hanno ciascuno i propri compromessi. Costruire un'API di compressione PDF affidabile con risultati consistenti richiede sperimentazione.

Come l'API di Compressione PDF MaraDocs risolve il problema in pochi minuti

L'API MaraDocs offre pdf.optimize per la compressione intelligente. Carica un PDF, validalo, quindi ottimizzalo. Il risultato è tipicamente molto più piccolo mantenendo la qualità – l'API gestisce internamente il downsampling delle immagini, la compressione degli stream e l'incorporamento dei font. Nessun Ghostscript da installare, nessun parametro da regolare, nessun dubbio tra qualità e dimensione. Una chiamata e ottieni un handle ottimizzato, pronto per l'email, l'archiviazione o la fase di elaborazione successiva.

Workflow di Compressione PDF: Carica, Valida, Ottimizza

Carica il PDF, validalo per virus e formato, quindi chiama pdf.optimize. L'API applica la compressione intelligente – downsampling delle immagini, ottimizzazione degli stream – e restituisce un handle ottimizzato. Può essere scaricato o passato alla composizione, all'elaborazione degli allegati email o all'archiviazione. L'ottimizzazione si inserisce naturalmente come ultimo passaggio prima della consegna in qualsiasi pipeline. I file rimangono nel workspace; nessun nuovo caricamento tra validazione e ottimizzazione.

Cosa distingue MaraDocs: Workspace, Webview e normativa tedesca sulla privacy

La maggior parte delle API per documenti costringe a caricare, elaborare, scaricare e ricaricare per il passaggio successivo. Con MaraDocs i file rimangono nel workspace. Concatena con OCR, composizione o elaborazione email – l'handle del PDF ottimizzato fluisce direttamente all'operazione successiva. Nessun nuovo caricamento, meno round-trip.

Se la qualità della compressione deve essere verificata manualmente – o si desidera un confronto prima-dopo – è possibile aprire app.maradocs.io per il controllo manuale. Gli utenti ottengono il pieno controllo manuale quando l'automazione raggiunge i suoi limiti.

L'intera elaborazione avviene in Germania (Maramia GmbH), crittografata a riposo e in transito. I workspace scadono dopo 7 giorni. Nessun dato lascia l'UE. Per i flussi di lavoro documentali sensibili alla privacy, questo è rilevante.

Codice TypeScript per la Riduzione della Dimensione PDF

Riferimento 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 });

// Carica, valida, ottimizza, scarica
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 });

Codice Python per la Compressione PDF

Riferimento 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()

Riepilogo e Prossimi Passi

È disponibile un'API di compressione PDF che riduce la dimensione del file preservando la qualità. MaraDocs gestisce l'ottimizzazione come parte di un flusso di lavoro documentale più completo. Altri casi d'uso correlati: elaborazione PDF, elaborazione email e immagine su pagina bianca.

---

Prova ora: API MaraDocs | SDK TypeScript

---