API de procesamiento de PDF – Combinar, dividir y rotar PDFs automáticamente

¿Necesita combinar varios PDFs, seleccionar páginas específicas o corregir escaneos mal rotados? En nuestro despacho, los expedientes llegaban a menudo como PDFs separados – informes periciales, cartas de clientes, documentos judiciales – que debían combinarse y reorganizarse. Una API para combinar y dividir PDFs que también corrija la orientación simplificaría significativamente este flujo de trabajo.

Suena sencillo – hasta que intenta integrar PyMuPDF, pikepdf o bibliotecas similares en una pipeline robusta con antivirus y validación.

Por qué construir una solución propia para combinar y dividir PDFs lleva semanas

PyMuPDF, pikepdf, PyPDF2 y reportlab cubren cada uno partes de la manipulación de PDF. Combinar funciona – hasta que se encuentra con archivos encriptados, streams dañados o codificaciones inusuales. Quien quiera construirlo por su cuenta descubre rápidamente que el reconocimiento de orientación típicamente requiere OCR o análisis de diseño – más dependencias, más infraestructura. Generar imágenes de vista previa significa renderizar páginas en imágenes, escalar y codificar. Construir una API de manipulación de PDF confiable y validada cuesta tiempo y oculta complejidad en casos especiales.

Cómo la API de MaraDocs para combinar y dividir PDFs lo resuelve en minutos

La API de MaraDocs ofrece procesamiento de PDF como servicio. Cargar, validar (virus y formato), luego componer (combinar/dividir por página), detectar y corregir orientación, generar vistas previas, optimizar y OCR – todo a través de una sola API. Sin cargas entre pasos; los archivos permanecen en el Workspace. Se especifica qué páginas de qué PDFs deben combinarse, y la API devuelve un único handle compuesto. La corrección de orientación utiliza análisis basado en texto, de modo que los escaneos rotados se corrigen automáticamente.

Flujo de trabajo de procesamiento de documentos: Cargar, validar, componer, orientar

Cada flujo de trabajo de MaraDocs comienza con carga y validación. Cargar un PDF (o tomar uno de un paso anterior), validar virus y formato, luego encadenar operaciones. El endpoint Compose permite combinar múltiples PDFs y seleccionar páginas específicas: p. ej. { pdf_handle: p1, pages: [{ page_number: 0 }, { page_number: 2 }] } para las páginas 1 y 3 del primer documento, más { pdf_handle: p2 } para el segundo documento completo. La detección de orientación utiliza análisis basado en texto para corregir automáticamente páginas rotadas. Para vistas previas: renderizar una página como imagen, luego crear miniatura, luego convertir a JPEG – todo con handles del lado del servidor, sin recargar.

Lo que distingue a MaraDocs: Workspaces, Webview y legislación alemana de protección de datos

La mayoría de las APIs de documentos obligan a cargar, procesar, descargar y volver a cargar para el siguiente paso. Con los Workspaces de MaraDocs, los archivos permanecen en el servidor. Los handles se pasan entre operaciones: validar → componer → orientar → optimizar. Menos roundtrips, código más simple, sin necesidad de rastrear identidades de archivos entre pasos.

Cuando la automatización se encuentra con un caso especial – orden de páginas incorrecto, un stream dañado o una codificación inusual – app.maradocs.io puede abrirse con el Workspace Secret para revisión y edición manual. Los usuarios obtienen control manual completo cuando la pipeline necesita intervención humana.

Todo el procesamiento se realiza en Alemania (Maramia GmbH), con cifrado en reposo (SSE-C) y durante la transmisión (TLS). Los Workspaces expiran después de 7 días. Ningún dato sale de la UE. Para cargas de trabajo sensibles al RGPD y BDSG, esto es relevante.

Código TypeScript para combinar y rotar automáticamente PDFs

Referencia de 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 });

// Cargar y validar ambos PDFs
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);

// Combinar PDFs, seleccionar páginas específicas
const composed = await client.pdf.compose({
  pdfs: [
    { pdf_handle: pdf1, pages: [{ page_number: 0 }, { page_number: 2 }] },
    { pdf_handle: pdf2 },
  ],
});

// Detectar y corregir orientación automáticamente
const oriented = await client.pdf.orientation({
  pdf_handle: composed.pdf_handle,
});

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

// Opcional: Vista previa (renderizar página como imagen, luego crear miniatura)
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],
});

Código Python para combinar y orientar PDFs

Referencia de API: data/upload, pdf/validate, pdf/compose, pdf/orientation, data/download/pdf

# pip install python-decouple requests
"""Combinar PDFs (con selección opcional de páginas) usando MaraDocs. Configure ACCOUNT_SECRET en .env o en el entorno."""

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:
    """Crear un workspace y devolver headers de autenticación."""
    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:
    """Cargar un archivo mediante flujo de dos pasos (URL firmada + S3 POST). Devuelve 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:
    """Ejecutar un trabajo y hacer polling hasta completar. Devuelve el resultado (desenvuelve response si está presente)."""
    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} expiró")


def download_pdf(pdf_handle: str, auth: dict) -> bytes:
    """Solicitar URL firmada y obtener bytes del PDF."""
    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 creado")


if __name__ == "__main__":
    main()

Resumen y próximos pasos

Una API para combinar y dividir PDFs con corrección de orientación y vistas previas está lista para usar. MaraDocs se encarga de validación, composición, orientación y optimización en un solo flujo de trabajo. Más información: Escáner de documentos, Rotación automática, Compresión de PDF e Imagen en página en blanco.

---

Pruébalo ahora: API de MaraDocs | SDK TypeScript

---