API skanera dokumentów – automatyczne wyodrębnianie dokumentów ze zdjęć

Czy otrzymują Państwo dokumenty jako zdjęcia w załącznikach e-mail? W kancelarii naszych założycieli był to niemały problem, który pochłaniał czas pracy manualnej. Klienci fotografują faktury, raporty z wypadków i umowy na kuchennym stole i naciskają wysyłanie. Otrzymuje się zniekształcone pliki JPG, które przed archiwizacją muszą zostać przycięte, skorygowane perspektywicznie i przekonwertowane na PDF.

API aplikacji skanera dokumentów, które rozpoznaje granice dokumentu, koryguje perspektywę i generuje czysty PDF, zaoszczędziłoby godziny pracy. Brzmi to prosto – ale samodzielne zbudowanie rzadko takie jest.

Dlaczego własna aplikacja skanera dokumentów trwa tygodnie

Kto chce zbudować wewnętrzne rozwiązanie do wyodrębniania dokumentów, szybko sięga po OpenCV do wykrywania krawędzi i transformacji perspektywy, Tesseract lub OCR w chmurze do rozpoznawania tekstu, PyMuPDF lub reportlab do generowania PDF oraz Pillow do przetwarzania obrazów. Być może dochodzi jeszcze model rozpoznawania dokumentów (np. Layout-Transformer lub segmentatory oparte na SAM) dla niezawodnego rozpoznawania. Każdy element działa osobno; połączenie ich w niezawodny pipeline z prawidłową obsługą błędów, skanowaniem antywirusowym i walidacją formatów trwa tygodnie. Modele ML wymagają infrastruktury GPU, hostingu modeli i konserwacji. Większość programistów szybko zauważa, że potrzeba czegoś więcej niż weekendowego projektu.

Jak API skanera dokumentów MaraDocs rozwiązuje to w minuty

API przetwarzania dokumentów MaraDocs przekształca ten workflow w kilka wywołań API. To samo przesyłanie, walidacja i łańcuchowe przetwarzanie – ale bez nakładu integracyjnego. Prześlij zdjęcie, zwaliduj je (skanowanie antywirusowe i kontrole formatów w zestawie), rozpoznaj dokumenty na obrazie, wyodrębnij każdy z osobna i skoryguj perspektywę, konwertuj na PDF – wszystko przez jedno REST API. Bez infrastruktury ML, bez chaosu zależności Pythona.

Workflow skanera dokumentów: przesyłanie, walidacja, wyodrębnianie, konwersja

Każdy workflow MaraDocs podąża za tym samym wzorcem: prześlij plik, zwaliduj (skan antywirusowy + walidacja formatu), a następnie łańcuch operacji. Walidacja jest obowiązkowa i następuje przed każdym przetwarzaniem. Jeśli plik jest zainfekowany lub uszkodzony, otrzymuje się jasny komunikat o błędzie – żadne przetwarzanie niezaufanych danych.

Po walidacji operacje są łączone przez przekazywanie uchwytów. Dla przepływu skanera dokumentów: zwaliduj obraz, wywołaj findDocuments, aby uzyskać współrzędne czworokątów, wywołaj extractQuadrilateral dla każdego rozpoznanego dokumentu, następnie konwertuj za pomocą toPdf lub ocrToPdf dla przeszukiwalnego wyniku w PDF. Cały pipeline pozostaje po stronie serwera; ten sam plik nigdy nie jest ponownie przesyłany.

Co wyróżnia MaraDocs: przestrzenie robocze, webview i niemieckie prawo o ochronie danych

Większość API dokumentów zmusza do przesyłania, pobierania i ponownego przesyłania przy każdym kroku przetwarzania. Oznacza to dodatkowe przejścia, więcej kodu do śledzenia tożsamości plików i większe opóźnienia. MaraDocs zamiast tego wykorzystuje przestrzenie robocze: Państwa serwer tworzy workspace z tajnym kluczem i otrzymuje workspace_secret. Klient (przeglądarka lub backend) używa tego tokena do wszystkich operacji. Pliki pozostają po stronie serwera; uchwyty są przekazywane między krokami. Łączy się walidacja → wyszukiwanie → wyodrębnianie → toPdf → pobieranie z płynnymi uchwytami – bez ponownego przesyłania, mniej wywołań sieciowych, prostszy kod.

Czasami automatyzacja napotyka szczególny przypadek: trudny kąt, wiele dokumentów na jednym zdjęciu lub format wymagający ręcznej korekty. Z MaraDocs można otworzyć app.maradocs.io, aby za pomocą workspace-secret bezpośrednio przeglądać, przestawiać i edytować pliki. Użytkownicy otrzymują pełną ręczną kontrolę, gdy pipeline wymaga ludzkiej interwencji – rzadka zaleta w porównaniu z API oferującymi tylko dostęp programatyczny.

Całe przetwarzanie odbywa się na serwerach w Niemczech pod kontrolą Maramia GmbH. Dane są szyfrowane w spoczynku (SSE-C) i podczas transmisji (TLS). Przestrzenie robocze wygasają po 7 dniach. Żadne dane nie opuszczają UE. Na życzenie dostępna jest umowa o powierzenie przetwarzania danych. Jest to istotne dla workloadów wrażliwych na RODO i niemiecką ustawę o ochronie danych.

Kod TypeScript do wyodrębniania dokumentów ze zdjęć

MaraDocs TypeScript SDK obsługuje polling dla zadań asynchronicznych. Pełny przepływ z przesyłaniem, walidacją, przetwarzaniem i pobieraniem.

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

// Serwer: utwórz workspace
const server = new MaraDocsServer({ secretKey: process.env.MARADOCS_SECRET_KEY! });
const { workspace_secret } = await server.workspace.create({});

// Klient: prześlij, waliduj, znajdź dokumenty, wyodrębnij, OCR, pobierz
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 });
}

Lub użyj flow.ocrImg dla pełnego pipeline'u (prześlij, waliduj, wyszukaj, wyodrębnij, wyrównaj, OCR, optymalizuj) w jednym wywołaniu:

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

Kod Python do wyodrębniania dokumentów

Dokumentacja 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 = "..."  # z własnego serwera
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. Prześlij
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. Waliduj
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. Znajdź dokumenty, 4. Wyodrębnij, 5. OCR do PDF (uproszczone; każde zadanie jest pollowane)
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. Pobierz
    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)

Podsumowanie: API skanera dokumentów bez nakładu integracyjnego

API aplikacji skanera dokumentów, które wyodrębnia dokumenty ze zdjęć, koryguje perspektywę i generuje PDF-y, jest w zasięgu ręki. Z MaraDocs odpada tygodniowa integracja OpenCV, Tesseract i modeli ML. Walidacja, przestrzenie robocze, webview i niemiecka lokalizacja danych są dostępne od razu.

Kolejne przypadki użycia: Przetwarzanie PDF – łączenie, dzielenie, automatyczne obracanie, Automatyczne obracanie i wykrywanie orientacji, Rozpoznawanie tekstu (OCR) oraz Umieszczanie obrazu lub PDF na pustej stronie DIN A4.

---

Wypróbuj teraz: MaraDocs API | TypeScript SDK

---