Rotación automática de PDF – API para alinear páginas PDF e imágenes

Los documentos escaneados o fotografiados llegan frecuentemente al revés o girados lateralmente. La rotación manual no escala cuando se procesan cientos de documentos. Una API de rotación automática de PDF que detecta la orientación basándose en el contenido real —no solo en datos EXIF— y la corrige, eliminaría un paso tedioso del pipeline de procesamiento.

Quien procesa expedientes, escaneos o fotos en grandes volúmenes lo sabe: la orientación incorrecta consume tiempo.

Por qué desarrollar una solución propia de orientación automática de páginas PDF e imágenes lleva semanas

Quien quiera construirlo internamente descubre rápidamente que la detección de orientación suele significar: ejecutar OCR, analizar la dirección del texto, derivar la rotación. Tesseract, EasyOCR o servicios OCR en la nube pueden ayudar, pero hay que integrarlos, considerar diferentes idiomas y mapear los resultados a rotaciones de 0°/90°/180°/270°. Los PDF requieren procesamiento página por página. Construir una API confiable de detección de orientación de documentos cuesta tiempo de integración y ajustes finos.

Cómo la API de MaraDocs para rotación automática de PDF lo resuelve en minutos

La API de MaraDocs ofrece pdf.orientation e img.orientation. Ambas utilizan análisis basado en texto para determinar la orientación correcta, más fiable que EXIF, que frecuentemente es incorrecto o está ausente. En PDF se analiza cada página; en imágenes, la imagen completa. La API devuelve el resultado rotado junto con los ángulos por página con valores de confianza. Sin pipeline OCR que mantener, sin hosting de modelos, sin configuración de idiomas. Una llamada API y obtienes un handle corregido para el siguiente paso.

Flujo de trabajo de orientación de documentos: Validar, Alinear, Encadenar

Sube el PDF o imagen, valida virus y formato, luego llama a orientation. La API analiza cada página (o la imagen completa en entradas de una sola página) y devuelve un handle rotado. Este handle se puede pasar directamente a OCR, composición u optimización: la orientación se integra como un paso en cualquier pipeline. El archivo no necesita subirse nuevamente entre pasos; el resultado rotado permanece en el workspace.

Qué diferencia a MaraDocs: Workspaces, Webview y legislación alemana de protección de datos

La mayoría de las API de documentos obligan a subir, procesar, descargar y volver a subir para el siguiente paso. En MaraDocs, los archivos permanecen en el workspace. Después de la detección de orientación, el handle rotado se pasa directamente a OCR, composición u optimización, sin volver a subir. Los handles fluyen; los datos permanecen del lado del servidor.

Cuando la detección de orientación es incierta —escaneos de bajo contraste, notas manuscritas o idiomas mixtos— se puede abrir app.maradocs.io para revisión y correcció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 en tránsito. Los workspaces caducan después de 7 días. Ningún dato sale de la UE. Para procesamiento de documentos sensibles en términos de protección de datos, esto es relevante.

Código TypeScript para rotación automática de PDF

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

// Subir y validar
const uploaded = await client.data.upload(pdfOrImageFile);
const pdfVal = await client.pdf.validate({ unvalidated_file_handle: uploaded.unvalidated_file_handle });
const pdfHandle = okPdf(pdfVal);

// Orientación PDF
const oriented = await client.pdf.orientation({ pdf_handle: pdfHandle });

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

// Para imágenes: usar client.img.validate + client.img.orientation

Código Python para detección de orientación de documentos

Referencia API: data/upload, pdf/validate, pdf/orientation, img/orientation, data/download/pdf

# pip install python-decouple requests
"""Fix PDF page orientation 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"]
    oriented = run_job("pdf/orientation", {"pdf_handle": pdf_handle}, auth)
    rotated_handle = oriented["response"]["rotated_pdf_handle"]
    Path("rotated.pdf").write_bytes(download_pdf(rotated_handle, auth))
    print("rotated.pdf created")


if __name__ == "__main__":
    main()

Resumen y próximos pasos

Una API para rotación automática de PDF y detección de orientación de documentos está disponible. MaraDocs procesa imágenes y PDF con análisis basado en texto. Otros flujos de trabajo relacionados: Escáner de documentos, Procesamiento de PDF y Reconocimiento de texto.

---

Pruébalo ahora: API de MaraDocs | SDK TypeScript

---