PDF-Verarbeitungs-API – PDFs zusammenführen, trennen und automatisch drehen

Müssen mehrere PDFs zusammengeführt, bestimmte Seiten ausgewählt oder falsch gedrehte Scans korrigiert werden? In unserer Kanzlei kamen Akten oft als separate PDFs an – Gutachten, Mandantenbriefe, Gerichtsdokumente – die zusammengeführt und neu geordnet werden mussten. Eine API zum Zusammenführen und Trennen von PDFs, die auch die Ausrichtung korrigiert, würde diesen Workflow erheblich vereinfachen.

Das klingt einfach – bis man versucht, PyMuPDF, pikepdf oder ähnliche Bibliotheken in eine robuste Pipeline mit Virenscan und Validierung einzubinden.

Warum eine eigene Lösung zum Zusammenführen und Trennen von PDFs Wochen dauert

PyMuPDF, pikepdf, PyPDF2 und reportlab decken jeweils Teile der PDF-Manipulation ab. Zusammenführen funktioniert – bis man auf verschlüsselte Dateien, beschädigte Streams oder ungewöhnliche Kodierungen stößt. Wer das selbst aufbauen möchte, stellt schnell fest, dass die Ausrichtungserkennung typischerweise OCR oder Layout-Analyse erfordert – weitere Abhängigkeiten, mehr Infrastruktur. Vorschaubilder zu generieren bedeutet, Seiten in Bilder zu rendern, zu skalieren und zu kodieren. Eine zuverlässige, validierte PDF-Manipulations-API zu bauen kostet Zeit und verbirgt Komplexität in Sonderfällen.

Wie die MaraDocs API zum Zusammenführen und Trennen von PDFs das in Minuten löst

Die MaraDocs API bietet PDF-Verarbeitung als Dienst. Hochladen, validieren (Viren und Format), dann zusammensetzen (zusammenführen/trennen nach Seite), Ausrichtung erkennen und korrigieren, Vorschaubilder generieren, optimieren und OCR – alles über eine einzige API. Keine Uploads zwischen den Schritten; Dateien bleiben im Workspace. Man gibt an, welche Seiten aus welchen PDFs kombiniert werden sollen, und die API gibt ein einzelnes zusammengesetztes Handle zurück. Die Ausrichtungskorrektur nutzt textbasierte Analyse, sodass gedrehte Scans automatisch korrigiert werden.

Workflow zur Dokumentenverarbeitung: Hochladen, Validieren, Zusammensetzen, Ausrichten

Jeder MaraDocs-Workflow beginnt mit Hochladen und Validierung. Ein PDF hochladen (oder eines aus einem vorherigen Schritt übernehmen), auf Viren und Format validieren, dann Operationen verketten. Der Compose-Endpunkt ermöglicht das Zusammenführen mehrerer PDFs und die Auswahl bestimmter Seiten: z. B. { pdf_handle: p1, pages: [{ page_number: 0 }, { page_number: 2 }] } für Seiten 1 und 3 des ersten Dokuments, plus { pdf_handle: p2 } für das gesamte zweite Dokument. Die Ausrichtungserkennung nutzt textbasierte Analyse, um gedrehte Seiten automatisch zu korrigieren. Für Vorschaubilder: eine Seite als Bild rendern, dann Vorschaubild erstellen, dann als JPEG konvertieren – alles mit serverseitigen Handles, kein erneutes Hochladen.

Was MaraDocs unterscheidet: Workspaces, Webview und deutsches Datenschutzrecht

Die meisten Dokumenten-APIs zwingen zum Hochladen, Verarbeiten, Herunterladen und erneuten Hochladen für den nächsten Schritt. Mit MaraDocs Workspaces bleiben Dateien serverseitig. Handles werden zwischen Operationen übergeben: validieren → zusammensetzen → ausrichten → optimieren. Weniger Roundtrips, einfacherer Code, keine Notwendigkeit, Dateiidentitäten über Schritte hinweg zu verfolgen.

Wenn die Automatisierung an einen Sonderfall stößt – falsche Seitenreihenfolge, ein beschädigter Stream oder eine ungewöhnliche Kodierung – kann app.maradocs.io mit dem Workspace-Secret für manuelle Prüfung und Bearbeitung geöffnet werden. Nutzer erhalten volle manuelle Kontrolle, wenn die Pipeline menschliches Eingreifen benötigt.

Die gesamte Verarbeitung erfolgt in Deutschland (Maramia GmbH), mit Verschlüsselung im Ruhezustand (SSE-C) und während der Übertragung (TLS). Workspaces verfallen nach 7 Tagen. Keine Daten verlassen die EU. Für DSGVO- und BDSG-sensible Workloads ist das relevant.

TypeScript-Code zum Zusammenführen und automatischen Drehen von PDFs

API-Referenz: data/upload, pdf/validate, pdf/compose, pdf/orientation, pdf/to/img, img/thumbnail, 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 });

// Beide PDFs hochladen und validieren
const up1 = await client.data.upload(pdf1File);
const up2 = await client.data.upload(pdf2File);
const val1 = await client.pdf.validate({ unvalidated_file_handle: up1.unvalidated_file_handle });
const val2 = await client.pdf.validate({ unvalidated_file_handle: up2.unvalidated_file_handle });
const pdf1 = okPdf(val1);
const pdf2 = okPdf(val2);

// PDFs zusammenführen, bestimmte Seiten auswählen
const composed = await client.pdf.compose({
  pdfs: [
    { pdf_handle: pdf1, pages: [{ page_number: 0 }, { page_number: 2 }] },
    { pdf_handle: pdf2 },
  ],
});

// Ausrichtung automatisch erkennen und korrigieren
const oriented = await client.pdf.orientation({
  pdf_handle: composed.pdf_handle,
});

// Ergebnis herunterladen
const blob = await client.data.downloadPdf({ pdf_handle: oriented.rotated_pdf_handle });

// Optional: Vorschaubild (Seite als Bild rendern, dann Vorschaubild erstellen)
const imgResult = await client.pdf.toImg({
  pdf_handle: oriented.rotated_pdf_handle,
  pages: [0],
});
const thumb = await client.img.thumbnail({
  img_handle: imgResult.img_handles[0],
});

Python-Code zum PDF-Zusammenführen und Ausrichten

API-Referenz: data/upload, pdf/validate, pdf/compose, pdf/orientation, data/download/pdf

import requests
import time

API_URL = "https://api.maradocs.io/v1"
headers = {"Authorization": f"Bearer {WORKSPACE_SECRET}"}

def poll(url, job_id):
    while True:
        r = requests.get(f"{url}/{job_id}", headers=headers).json()
        if r["status"] == "complete":
            return r["response"]["response"]
        time.sleep(1)

# 1. Beide PDFs hochladen und validieren
with open("doc1.pdf", "rb") as f1, open("doc2.pdf", "rb") as f2:
    up1 = requests.post(f"{API_URL}/data/upload", headers=headers, files={"file": f1}).json()
    up2 = requests.post(f"{API_URL}/data/upload", headers=headers, files={"file": f2}).json()
v1 = requests.post(f"{API_URL}/pdf/validate", headers=headers,
    json={"unvalidated_file_handle": up1["unvalidated_file_handle"]}).json()
v2 = requests.post(f"{API_URL}/pdf/validate", headers=headers,
    json={"unvalidated_file_handle": up2["unvalidated_file_handle"]}).json()
pdf1 = poll(f"{API_URL}/pdf/validate", v1["job_id"])["pdf_handle"]
pdf2 = poll(f"{API_URL}/pdf/validate", v2["job_id"])["pdf_handle"]

# 2. Zusammensetzen (zusammenführen/trennen)
compose = requests.post(f"{API_URL}/pdf/compose", headers=headers,
    json={"pdfs": [{"pdf_handle": pdf1, "pages": [{"page_number": 0}, {"page_number": 2}]}, {"pdf_handle": pdf2}]}).json()
composed = poll(f"{API_URL}/pdf/compose", compose["job_id"])

# 3. Ausrichtung, 4. Herunterladen
orient = requests.post(f"{API_URL}/pdf/orientation", headers=headers,
    json={"pdf_handle": composed["pdf_handle"]}).json()
oriented = poll(f"{API_URL}/pdf/orientation", orient["job_id"])
pdf_resp = requests.get(f"{API_URL}/data/download/pdf", headers=headers,
    params={"pdf_handle": oriented["rotated_pdf_handle"]})
with open("merged.pdf", "wb") as out:
    out.write(pdf_resp.content)

Zusammenfassung und nächste Schritte

Eine API zum Zusammenführen und Trennen von PDFs mit Ausrichtungskorrektur und Vorschaubildern ist einsatzbereit. MaraDocs übernimmt Validierung, Komposition, Ausrichtung und Optimierung in einem Workflow. Weitere Informationen: Dokumentenscanner, Automatisches Drehen, PDF-Komprimierung und Bild auf leere Seite.

---

Jetzt ausprobieren: MaraDocs API | TypeScript SDK

---