Dokumentenscanner in die Web-App einbauen mit dem ScanKit SDK

Ihre Nutzer fotografieren Dokumente. Ihre App braucht Scans. Dazwischen liegt der Schritt, der über den Rest der Kette entscheidet: aus einem Handyfoto eine flache, lesbare Seite machen, mit gefundenen Kanten und korrigierter Perspektive.

Das ScanKit SDK ist genau dieser Schritt als fertiges Widget: Kamera- und Dateiauswahl, Kantenerkennung während des Ausrichtens, eine Zuschneide-Oberfläche für Korrekturen, Filter, Drehung und ein sauberes Bild, das der Nutzer behalten kann. Es ist unabhängig vom Framework, braucht keinen Build-Schritt und besteht aus einem Stylesheet und einem Skript.

Was das Widget übernimmt

Der Aufwand bei der Dokumentenerfassung steckt selten in der Kamera, sondern in allem danach:

• Eingabe — Kamera auf dem Smartphone, Dateiauswahl am Desktop, das Bild wählt der Nutzer.
• Kantenerkennung — die Seite wird im Sucher gefunden, während der Nutzer das Gerät noch hält. Er kann die Position korrigieren, statt das Problem erst später zu entdecken.
• Manuelles Zuschneiden — greift die Erkennung die falschen Ecken, zieht der Nutzer sie in der Zuschneide-Oberfläche zurecht. Das ist der Unterschied zwischen einem unbrauchbaren Foto und einem verwertbaren Scan.
• Drehung und Filter — Original, Flach oder Weiß, je nach Dokument. Die Drehung wirkt auch auf die exportierte Datei, nicht nur auf die Vorschau.
• Ein sauberes Ergebnis — der Export ist die begradigte, zugeschnittene Seite, nicht das ursprüngliche Foto mit Schreibtisch darauf.

Die Bildverarbeitung läuft in der ScanKit-API, gehostet in der EU. Uploads werden nicht gespeichert: das Bild wird nach der Verarbeitung gelöscht.

In eine Seite einbauen

Zwei Tags und ein paar Zeilen genügen für einen funktionierenden Scanner:

<link rel="stylesheet" href="https://www.scankit.io/sdk/scankit-sdk.css">
<script src="https://www.scankit.io/sdk/scankit-sdk.min.js"></script>

<div id="scan-area"></div>

<script>
  const scanner = new ScanKit({
    target: '#scan-area',
    apiKey: 'your-api-key',           // aus Ihrem Dashboard
    buttonText: 'Dokument scannen',
    onScanComplete: (result) => {
      // result.image ist ein Blob mit dem gescannten Dokument
      console.log(result.image);
    },
    onScanCancel: () => console.log('abgebrochen')
  });
  scanner.init();
</script>

Die Optionen, die Sie am ehesten anfassen:

• target — CSS-Selektor oder Element, in dem der Scan-Knopf sitzt. Standard ist body.
• apiKey — wird als X-API-Key-Header gesendet. Ohne Schlüssel antwortet die API mit 401 Missing API Key, mit einem Schlüssel, der nicht zu einem aktiven Konto gehört, mit 401 Invalid API Key. So unterscheiden Sie einen Konfigurationsfehler von einem falschen Wert.
• buttonText / buttonClass — Beschriftung und Styling des Startknopfs, damit er sich Ihrem Design anpasst und nicht umgekehrt.
• inputSource — 'photo' für den normalen Aufnahmeweg.
• segmentCount — wie fein die Seite für die Perspektivkorrektur unterteilt wird. Der Standardwert 9 ist ein guter Ausgangspunkt.
• onScanComplete — bekommt das Ergebnis, inklusive des Bildes als Blob.
• onScanCancel — feuert, wenn der Nutzer abbricht. Genau dort stoppen Sie in der Regel einen Ladeindikator.

Das Ergebnis ans Backend geben

result.image ist ein Blob und geht direkt in einen FormData-Upload:

onScanComplete: async (result) => {
  const form = new FormData();
  form.append('file', result.image, 'scan.jpg');
  await fetch('/api/documents', { method: 'POST', body: form });
}

Denselben Blob können Sie sofort als Vorschaubild zeigen, mit URL.createObjectURL(result.image) — der Nutzer sieht seinen Scan, bevor der Upload fertig ist.

Wenn im Foto kein Dokument gefunden wird

Ein Foto von einem leeren Schreibtisch ist kein Fehler, den die API durch Raten beheben könnte. Auf dem Bildpfad trägt die Antwort den Header X-ScanKit-Detected mit true oder false, die JSON-Endpunkte liefern ein Feld document_detected. Behandeln Sie false als Signal, nicht als Fehlschlag: öffnen Sie Ihre eigene Zuschneide-Ansicht und lassen Sie den Nutzer die Ecken setzen. Das ist der Unterschied zwischen Sackgasse und zweitem Versuch.

Bevor Sie es auf eine öffentliche Seite stellen

• Über HTTPS ausliefern. Browser geben Kamerazugriff nur auf sicheren Ursprüngen, über einfaches HTTP funktioniert das Widget nicht.
• Denken Sie daran, dass der Schlüssel sichtbar ist. Ein API-Schlüssel im Browser ist für jeden lesbar, der die Entwicklerwerkzeuge öffnet. Für ein internes Werkzeug ist das in Ordnung, für eine öffentliche Seite nicht. Nutzen Sie dort einen gehosteten Scanner, der den Schlüssel auf dem Server behält, oder leiten Sie den Upload über Ihr eigenes Backend und lassen den Schlüssel dort.
• Nicht sammeln, was Sie nicht brauchen. Wenn Ihr Anwendungsfall nur die ausgelesenen Werte benötigt, behalten Sie die Werte und lassen das Bild gehen.
• Fangen Sie im kostenlosen Kontingent an. 50 Credits, keine Kreditkarte — genug, um den Ablauf mit echten Dokumenten aus Ihrem Team durchzuspielen, bevor Sie ihn produktiv einbinden.

Der Punkt des Widgets ist, dass nichts davon eine Entscheidung über Ihren Frontend-Stack verlangt. Es läuft dort, wo der Knopf sitzt, und der Rest Ihrer App arbeitet weiter wie bisher.