API de escáner de documentos – Extraer documentos de fotos automáticamente

¿Recibe documentos como fotos en archivos adjuntos de correo electrónico? En el despacho de nuestros fundadores, este era un problema considerable que consumía tiempo de trabajo manual. Los clientes fotografían facturas, informes de accidentes y contratos en la mesa de la cocina y pulsan enviar. Se reciben JPGs distorsionados que deben recortarse, corregirse en perspectiva y convertirse a PDF antes de ser archivados.

Una API de aplicación de escáner de documentos que reconozca los límites del documento, corrija la perspectiva y genere un PDF limpio ahorraría horas. Suena sencillo, pero construirlo uno mismo rara vez lo es.

Por qué una aplicación de escáner de documentos propia lleva semanas

Quien desee construir internamente una solución de extracción de documentos recurre rápidamente a OpenCV para detección de bordes y transformaciones de perspectiva, Tesseract o un OCR en la nube para reconocimiento de texto, PyMuPDF o reportlab para generación de PDF y Pillow para procesamiento de imágenes. Quizás se añada un modelo de reconocimiento de documentos (p. ej., Layout-Transformer o segmentadores basados en SAM) para un reconocimiento robusto. Cada pieza funciona aisladamente; conectarlas en un pipeline fiable con manejo correcto de errores, antivirus y validación de formatos lleva semanas. Los modelos ML requieren infraestructura GPU, hosting de modelos y mantenimiento. La mayoría de desarrolladores se dan cuenta rápidamente de que se necesita más que un hack de fin de semana.

Cómo la API de escáner de documentos de MaraDocs lo resuelve en minutos

La API de procesamiento de documentos de MaraDocs convierte este flujo de trabajo en unas pocas llamadas a la API. La misma carga, validación y procesamiento encadenado, pero sin el esfuerzo de integración. Suba una foto, valídela (antivirus y comprobaciones de formato incluidas), reconozca documentos en la imagen, extraiga cada uno individualmente y corrija la perspectiva, y convierta a PDF; todo a través de una única API REST. Sin infraestructura ML, sin caos de dependencias de Python.

Flujo de trabajo del escáner de documentos: Subir, Validar, Extraer, Convertir

Cada flujo de trabajo de MaraDocs sigue el mismo patrón: subir un archivo, validar (antivirus + validación de formato), luego encadenar operaciones. La validación es obligatoria y se realiza antes de cualquier procesamiento. Si un archivo está infectado o dañado, se obtiene un mensaje de error claro: no se procesan datos no confiables.

Después de la validación, las operaciones se encadenan pasando handles (identificadores). Para un flujo de escáner de documentos: valide la imagen, llame a findDocuments para obtener coordenadas cuadriláteras, llame a extractQuadrilateral para cada documento detectado, luego convierta con toPdf o ocrToPdf para salida con búsqueda en PDF. Todo el pipeline permanece del lado del servidor; el mismo archivo nunca se vuelve a subir.

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

La mayoría de las APIs de documentos obligan a subir, descargar y volver a subir para cada paso de procesamiento. Esto significa viajes de ida y vuelta adicionales, más código para rastrear identidades de archivos y mayor latencia. MaraDocs utiliza en su lugar workspaces: su propio servidor crea un workspace con una clave secreta y obtiene un workspace_secret. El cliente (navegador o backend) usa este token para todas las operaciones. Los archivos permanecen del lado del servidor; los handles se pasan entre pasos. Se encadena validar → buscar → extraer → toPdf → descargar con handles fluidos: sin volver a subir, menos llamadas de red, código más simple.

A veces la automatización se encuentra con un caso especial: un ángulo difícil, varios documentos en una foto o un formato que debe ajustarse manualmente. Con MaraDocs se puede abrir app.maradocs.io para ver, reordenar y editar archivos directamente con el workspace-secret. Los usuarios obtienen control manual completo cuando el pipeline necesita intervención humana: una ventaja poco común frente a APIs que solo ofrecen acceso programático.

Todo el procesamiento se realiza en servidores en Alemania bajo el control de Maramia GmbH. Los datos están cifrados 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. Bajo solicitud, está disponible un contrato de procesamiento de datos. Para cargas de trabajo sensibles al RGPD y BDSG, esto es relevante.

Código TypeScript para extraer documentos de fotos

El SDK de TypeScript de MaraDocs se encarga del polling para trabajos asíncronos. Flujo completo con subida, validación, procesamiento y descarga.

Referencia de la API: workspace, data/upload, img/validate, img/find/documents, img/extract/quadrilateral, img/ocr/to/pdf, data/download/pdf

import { MaraDocsServer, MaraDocsClient } from "@maramia/maradocs-sdk-ts";
import { okImg } from "@maramia/maradocs-sdk-ts/models/img";

// Servidor: crear workspace
const server = new MaraDocsServer({ secretKey: process.env.MARADOCS_SECRET_KEY! });
const { workspace_secret } = await server.workspace.create({});

// Cliente: subir, validar, buscar documentos, extraer, OCR, descargar
const client = new MaraDocsClient({ workspaceSecret: workspace_secret });
const uploaded = await client.data.upload(imageFile);
const validated = await client.img.validate({
  unvalidated_file_handle: uploaded.unvalidated_file_handle,
});
const imgHandle = okImg(validated);

const docs = await client.img.findDocuments({ img_handle: imgHandle });
if (docs.documents.length > 0) {
  const extracted = await client.img.extractQuadrilateral({
    img_handle: imgHandle,
    quadrilateral: docs.documents[0].quadrilateral,
  });
  const pdf = await client.img.ocrToPdf({
    img_handle: extracted.img_handle,
  });
  const blob = await client.data.downloadPdf({ pdf_handle: pdf.pdf_handle });
}

O use flow.ocrImg para un pipeline completo (subir, validar, buscar, extraer, alinear, OCR, optimizar) en una sola llamada:

const pdfHandle = await client.flow.ocrImg(imageFile);
const blob = await client.data.downloadPdf({ pdf_handle: pdfHandle });

Código Python para extracción de documentos

Referencia de la API: data/upload, img/validate, img/find/documents, img/extract/quadrilateral, img/ocr/to/pdf, data/download/pdf

import requests
import time

API_URL = "https://api.maradocs.io/v1"
WORKSPACE_SECRET = "..."  # desde su propio servidor
headers = {"Authorization": f"Bearer {WORKSPACE_SECRET}"}

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

# 1. Subir
with open("photo.jpg", "rb") as f:
    upload = requests.post(f"{API_URL}/data/upload", headers=headers,
        files={"file": ("photo.jpg", f, "image/jpeg")}).json()
handle = upload["unvalidated_file_handle"]

# 2. Validar
val = requests.post(f"{API_URL}/img/validate", headers=headers,
    json={"unvalidated_file_handle": handle}).json()
img_handle = poll(f"{API_URL}/img/validate", val["job_id"])["img_handle"]

# 3. Buscar documentos, 4. Extraer, 5. OCR a PDF (simplificado; cada job se hace polling)
find_res = requests.post(f"{API_URL}/img/find/documents", headers=headers,
    json={"img_handle": img_handle}).json()
find_data = poll(f"{API_URL}/img/find/documents", find_res["job_id"])
if find_data.get("documents"):
    quad = find_data["documents"][0]["quadrilateral"]
    ext_res = requests.post(f"{API_URL}/img/extract/quadrilateral", headers=headers,
        json={"img_handle": img_handle, "quadrilateral": quad}).json()
    extracted = poll(f"{API_URL}/img/extract/quadrilateral", ext_res["job_id"])
    ocr_res = requests.post(f"{API_URL}/img/ocr/to/pdf", headers=headers,
        json={"img_handle": extracted["img_handle"]}).json()
    ocr_data = poll(f"{API_URL}/img/ocr/to/pdf", ocr_res["job_id"])
    pdf_handle = ocr_data["pdf_handle"]

    # 6. Descargar
    pdf_resp = requests.get(f"{API_URL}/data/download/pdf", headers=headers,
        params={"pdf_handle": pdf_handle})
    with open("output.pdf", "wb") as out:
        out.write(pdf_resp.content)

Resumen: API de escáner de documentos sin esfuerzo de integración

Una API de aplicación de escáner de documentos que extraiga documentos de fotos, corrija la perspectiva y genere PDFs está al alcance. Con MaraDocs se elimina la integración de semanas de OpenCV, Tesseract y modelos ML. Validación, workspaces, webview y almacenamiento de datos alemán se incluyen directamente.

Más casos de uso: Procesamiento de PDF – Combinar, Dividir, Rotar Automáticamente, Rotación automática y detección de orientación, Reconocimiento de texto (OCR) y Colocar imagen o PDF en página DIN A4 en blanco.

---

Pruébelo ahora: API de MaraDocs | SDK de TypeScript

---