API Scanner Documenti – Estrarre automaticamente documenti da foto

Ricevete documenti come foto negli allegati email? Nello studio legale dei nostri fondatori questo era un problema non indifferente che richiedeva tempo di lavoro manuale. I clienti fotografano fatture, referti di incidenti e contratti sul tavolo della cucina e premono invio. Si ricevono JPG distorti che devono essere ritagliati, corretti prospetticamente e convertiti in PDF prima dell'archiviazione.

Un'API per app scanner documenti che riconosce i bordi del documento, corregge la prospettiva e produce un PDF pulito farebbe risparmiare ore. Sembra semplice – ma costruirla internamente raramente lo è.

Perché un'app scanner documenti personalizzata richiede settimane

Chi vuole costruire internamente una soluzione di estrazione documenti ricorre rapidamente a OpenCV per il rilevamento dei bordi e le trasformazioni prospettiche, Tesseract o un OCR cloud per il riconoscimento del testo, PyMuPDF o reportlab per la generazione PDF e Pillow per l'elaborazione delle immagini. Forse si aggiunge anche un modello di riconoscimento documenti (ad es. Layout-Transformer o segmentatori basati su SAM) per un riconoscimento robusto. Ogni componente funziona in isolamento; collegarli in una pipeline affidabile con corretta gestione degli errori, scansione virus e validazione dei formati richiede settimane. I modelli ML richiedono infrastruttura GPU, hosting dei modelli e manutenzione. La maggior parte degli sviluppatori si rende presto conto che serve più di un progetto per il weekend.

Come l'API Scanner Documenti MaraDocs risolve tutto in minuti

L'API di elaborazione documenti MaraDocs trasforma questo workflow in poche chiamate API. Stesso caricamento, validazione ed elaborazione concatenata – ma senza lo sforzo di integrazione. Caricare una foto, validarla (scansione virus e controlli formato inclusi), riconoscere documenti nell'immagine, estrarre ciascuno singolarmente e correggerlo prospetticamente, e convertire in PDF – tutto tramite una singola REST API. Nessuna infrastruttura ML, nessun caos di dipendenze Python.

Workflow Scanner Documenti: Caricare, Validare, Estrarre, Convertire

Ogni workflow MaraDocs segue lo stesso schema: caricare un file, validarlo (scansione virus + validazione formato), quindi concatenare le operazioni. La validazione è obbligatoria e avviene prima di ogni elaborazione. Se un file è infetto o corrotto, si riceve un messaggio di errore chiaro – nessuna elaborazione di dati non attendibili.

Dopo la validazione, le operazioni vengono concatenate passando gli handle. Per un flusso scanner documenti: validare l'immagine, chiamare findDocuments per ottenere le coordinate quadrilaterali, chiamare extractQuadrilateral per ogni documento rilevato, quindi convertire in PDF con toPdf o ocrToPdf per output ricercabile. L'intera pipeline rimane lato server; lo stesso file non viene mai ricaricato.

Cosa distingue MaraDocs: Workspace, Webview e normativa tedesca sulla privacy

La maggior parte delle API documenti obbliga a caricare, scaricare e ricaricare per ogni fase di elaborazione. Ciò significa roundtrip aggiuntivi, più codice per tracciare le identità dei file e latenza maggiore. MaraDocs invece utilizza workspace: il proprio server crea un workspace con una chiave segreta e riceve un workspace_secret. Il client (browser o backend) utilizza questo token per tutte le operazioni. I file rimangono lato server; gli handle vengono passati tra le fasi. Si concatena validare → cercare → estrarre → toPdf → scaricare con handle fluidi – nessun ricaricamento, meno chiamate di rete, codice più semplice.

A volte l'automazione incontra un caso particolare: un'angolazione difficile, più documenti in una foto o un formato che richiede regolazioni manuali. Con MaraDocs è possibile aprire app.maradocs.io per visualizzare, riordinare e modificare i file direttamente utilizzando il workspace secret. Gli utenti ottengono pieno controllo manuale quando la pipeline richiede intervento umano – un vantaggio raro rispetto alle API che offrono solo accesso programmatico.

Tutta l'elaborazione avviene su server in Germania sotto il controllo di Maramia GmbH. I dati sono crittografati a riposo (SSE-C) e in transito (TLS). I workspace scadono dopo 7 giorni. Nessun dato lascia l'UE. Su richiesta è disponibile un contratto di trattamento dati. Per workload sensibili al GDPR e BDSG questo è rilevante.

Codice TypeScript per estrarre documenti da foto

L'SDK TypeScript MaraDocs gestisce il polling per i job asincroni. Flusso completo con caricamento, validazione, elaborazione e download.

Riferimento 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";

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

// Client: caricare, validare, cercare documenti, estrarre, OCR, scaricare
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 });
}

Oppure utilizzare flow.ocrImg per una pipeline completa (caricare, validare, cercare, estrarre, allineare, OCR, ottimizzare) in una chiamata:

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

Codice Python per l'estrazione documenti

Riferimento 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 = "..."  # dal proprio server
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. Caricare
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. Validare
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. Cercare documenti, 4. Estrarre, 5. OCR a PDF (semplificato; ogni job viene sottoposto a 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. Scaricare
    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)

Riepilogo: API Scanner Documenti senza sforzo di integrazione

Un'API per app scanner documenti che estrae documenti da foto, corregge la prospettiva e produce PDF è a portata di mano. Con MaraDocs si evitano settimane di integrazione di OpenCV, Tesseract e modelli ML. Validazione, workspace, webview e archiviazione dati in Germania sono inclusi direttamente.

Altri casi d'uso: Elaborazione PDF – Unire, Dividere, Ruotare Automaticamente, Rotazione Automatica e Rilevamento Orientamento, Riconoscimento Testo (OCR) e Posizionare immagine o PDF su pagina A4 bianca.

---

Prova ora: API MaraDocs | SDK TypeScript

---