API przetwarzania PDF – łączenie, dzielenie i automatyczny obrót plików PDF

Czy trzeba połączyć wiele plików PDF, wybrać określone strony lub skorygować błędnie obrócone skany? W naszej kancelarii akta często docierały jako oddzielne pliki PDF – opinie biegłych, korespondencja z klientami, dokumenty sądowe – które należało połączyć i uporządkować na nowo. API do łączenia i dzielenia plików PDF, które również koryguje orientację, znacznie uprościłoby ten proces pracy.

Brzmi prosto – dopóki nie spróbuje się zintegrować PyMuPDF, pikepdf lub podobnych bibliotek w solidny pipeline ze skanowaniem antywirusowym i walidacją.

Dlaczego własne rozwiązanie do łączenia i dzielenia PDF zajmuje tygodnie

PyMuPDF, pikepdf, PyPDF2 i reportlab obejmują część możliwości manipulacji PDF. Łączenie działa – dopóki nie trafi się na zaszyfrowane pliki, uszkodzone strumienie lub nietypowe kodowania. Kto chce to zbudować samodzielnie, szybko odkrywa, że wykrywanie orientacji zazwyczaj wymaga OCR lub analizy układu – kolejne zależności, więcej infrastruktury. Generowanie miniatur oznacza renderowanie stron do obrazów, skalowanie i kodowanie. Zbudowanie niezawodnego, walidowanego API do manipulacji PDF wymaga czasu i ukrywa złożoność w nietypowych przypadkach.

Jak API MaraDocs do łączenia i dzielenia PDF rozwiązuje to w minuty

API MaraDocs oferuje przetwarzanie PDF jako usługę. Wgraj, waliduj (wirusy i format), następnie komponuj (łącz/dziel według stron), wykryj i skoryguj orientację, generuj miniatury, optymalizuj i OCR – wszystko przez jedno API. Żadnych przesyłań między krokami; pliki pozostają w obszarze roboczym. Określasz, które strony z których plików PDF połączyć, a API zwraca pojedynczy uchwyt skompletowanego dokumentu. Korekta orientacji wykorzystuje analizę tekstową, dzięki czemu obrócone skany są automatycznie korygowane.

Przepływ pracy przetwarzania dokumentów: wgrywanie, walidacja, komponowanie, wyrównywanie

Każdy przepływ pracy MaraDocs zaczyna się od wgrania i walidacji. Wgraj plik PDF (lub przejmij go z poprzedniego kroku), waliduj pod kątem wirusów i formatu, następnie łącz operacje w łańcuch. Endpoint Compose umożliwia łączenie wielu plików PDF i wybór określonych stron: np. { pdf_handle: p1, pages: [{ page_number: 0 }, { page_number: 2 }] } dla stron 1 i 3 pierwszego dokumentu, plus { pdf_handle: p2 } dla całego drugiego dokumentu. Wykrywanie orientacji wykorzystuje analizę tekstową do automatycznej korekty obróconych stron. Dla miniatur: renderuj stronę jako obraz, następnie utwórz miniaturę, potem konwertuj na JPEG – wszystko z wykorzystaniem uchwytów serwerowych, bez ponownego wgrywania.

Co wyróżnia MaraDocs: obszary robocze, webview i niemieckie prawo ochrony danych

Większość API do dokumentów wymusza wgrywanie, przetwarzanie, pobieranie i ponowne wgrywanie dla następnego kroku. W obszarach roboczych MaraDocs pliki pozostają po stronie serwera. Uchwyty są przekazywane między operacjami: waliduj → komponuj → wyrównaj → optymalizuj. Mniej przesyłań, prostszy kod, brak potrzeby śledzenia tożsamości plików między krokami.

Gdy automatyzacja napotka nietypowy przypadek – błędną kolejność stron, uszkodzony strumień lub nietypowe kodowanie – app.maradocs.io można otworzyć z sekretem obszaru roboczego do ręcznej kontroli i edycji. Użytkownicy otrzymują pełną kontrolę ręczną, gdy pipeline wymaga interwencji człowieka.

Całe przetwarzanie odbywa się w Niemczech (Maramia GmbH), z szyfrowaniem w spoczynku (SSE-C) i podczas przesyłania (TLS). Obszary robocze wygasają po 7 dniach. Żadne dane nie opuszczają UE. Dla obciążeń wrażliwych pod względem RODO i BDSG jest to istotne.

Kod TypeScript do łączenia i automatycznego obracania plików PDF

Dokumentacja API: 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 });

// Wgraj i waliduj oba pliki PDF
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);

// Połącz pliki PDF, wybierz określone strony
const composed = await client.pdf.compose({
  pdfs: [
    { pdf_handle: pdf1, pages: [{ page_number: 0 }, { page_number: 2 }] },
    { pdf_handle: pdf2 },
  ],
});

// Automatycznie wykryj i skoryguj orientację
const oriented = await client.pdf.orientation({
  pdf_handle: composed.pdf_handle,
});

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

// Opcjonalnie: miniatura (renderuj stronę jako obraz, następnie utwórz miniaturę)
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],
});

Kod Python do łączenia i wyrównywania plików PDF

Dokumentacja API: data/upload, pdf/validate, pdf/compose, pdf/orientation, data/download/pdf

# pip install python-decouple requests
"""Merge PDFs (with optional page selection) 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:
    paths = (
        [Path(p) for p in sys.argv[1:]]
        if len(sys.argv) > 1
        else [Path("doc1.pdf"), Path("doc2.pdf")]
    )
    auth = create_workspace()
    handles = [upload_file(p, auth) for p in paths]
    pdf_handles = [
        run_job("pdf/validate", {"unvalidated_file_handle": h}, auth)["response"][
            "pdf_handle"
        ]
        for h in handles
    ]
    if len(pdf_handles) == 2:
        compose_payload = {
            "pdfs": [
                {"pdf_handle": pdf_handles[0]},
                {
                    "pdf_handle": pdf_handles[1],
                    "pages": [{"page_number": 0}, {"page_number": 2}],
                },
            ]
        }
    else:
        compose_payload = {"pdfs": [{"pdf_handle": h} for h in pdf_handles]}
    composed = run_job("pdf/compose", compose_payload, auth)
    pdf_handle = composed.get("pdf_handle") or composed.get("response", {}).get(
        "pdf_handle"
    )
    oriented = run_job("pdf/orientation", {"pdf_handle": pdf_handle}, auth)
    rotated_handle = oriented["rotated_pdf_handle"]
    Path("merged.pdf").write_bytes(download_pdf(rotated_handle, auth))
    print("merged.pdf created")


if __name__ == "__main__":
    main()

Podsumowanie i kolejne kroki

API do łączenia i dzielenia plików PDF z korekcją orientacji i miniaturami jest gotowe do użycia. MaraDocs obsługuje walidację, komponowanie, wyrównywanie i optymalizację w jednym przepływie pracy. Więcej informacji: Skaner dokumentów, Automatyczny obrót, Kompresja PDF oraz Obraz na pustej stronie.

---

Wypróbuj teraz: API MaraDocs | SDK TypeScript

---