Worum es in dieser Anleitung geht
Die API-Dokumentation beschreibt jeden einzelnen Endpunkt vollständig — was diese Anleitung zusätzlich liefert, ist die Reihenfolge, in der ein Team, das eine bestehende Buchhaltungs- oder Kanzleisoftware um Belegerkennung erweitert, diese Endpunkte tatsächlich sinnvoll zusammensetzt. Zehn Schritte, von einem leeren API-Schlüssel bis zu einer laufenden Integration, die echte Kundenbelege verarbeitet und nach DATEV exportiert.
Was Sie vorher klären sollten
Bevor der erste Aufruf passiert, lohnt sich eine kurze, ehrliche Bestandsaufnahme: Welche Belegtypen kommen bei Ihren Kunden tatsächlich vor — nur Eingangsrechnungen, oder auch Kontoauszüge und Kassenbelege? Wie unterschiedlich sind die Lieferantenlayouts in Ihrem Kundenstamm? Und, entscheidend für Schritt 5: Wie viel manuelle Bestätigung ist Ihren Nutzern zumutbar, bevor die Integration für sie wie zusätzliche Arbeit wirkt statt wie eine Ersparnis? Diese drei Antworten bestimmen mehr über die konkrete Umsetzung als die eigentliche API-Dokumentation.
Eine vierte Frage lohnt sich zusätzlich, wenn Ihr Kundenstamm international ist: Kommen Belege in mehreren Sprachen vor? Die Erkennung selbst braucht dafür keine gesonderte Konfiguration — sie liest deutsche, englische, französische und weitere Belege gleichermaßen —, aber Ihre eigene Prüfoberfläche sollte darauf vorbereitet sein, dass ein Feldname wie "Description" oder "Cantidad" auf ein anderssprachiges Original verweist, falls Sie den Originalausschnitt für die manuelle Prüfung anzeigen.
1. API-Schlüssel anlegen
Kostenloses Konto, erster Schlüssel
2. Mit /validate den Datenvertrag testen
Kostenlos die erwartete Struktur prüfen
POST /validateprüft ein von Ihnen selbst zusammengestelltes Beispielobjekt gegen das erwartete Schema, ohne dass dafür ein Beleg oder eine Seite berechnet wird.curl -X POST https://flowparse.io/api/v1/validate \
-H "Authorization: Bearer pf_live_xxx" \
-H "Content-Type: application/json" \
-d '{ "type": "invoice", "data": { "supplier_name": "Test GmbH",
"invoice_number": "T-1", "total": 100.00, "currency": "EUR" } }'
# → { "valid": true, "issues": [] }3. Den ersten echten Beleg extrahieren
Ein reales Dokument, kein Beispiel-PDF
curl -X POST https://flowparse.io/api/v1/extract \
-H "Authorization: Bearer pf_live_xxx" \
-H "Content-Type: application/json" \
-d '{ "file": "JVBERi0xLjcK...", "filename": "kundenbeleg-01.pdf" }'Die Antwort im Detail: was jedes Feld bedeutet
Bevor Sie mit dem Mapping in Schritt 4 beginnen, lohnt sich ein genauer Blick auf die einzelnen Teile der Antwort, weil ihre Bedeutung nicht immer selbsterklärend ist:
{
"type": "invoice", // erkannter Dokumenttyp, ohne dass Sie ihn angeben mussten
"pages": 2, // tatsächliche Seitenzahl des PDFs
"billedPages": 2, // abgerechnete Seiten — meist identisch mit "pages"
"price": { // was genau dieser eine Aufruf gekostet hat
"eur": 0.07,
"perPageEur": 0.035,
"complexity": "standard" // informativ, wirkt sich nicht auf den Preis aus
},
"data": {
"type": "invoice",
"data": { // die eigentlichen, typisierten Belegfelder
"supplier_name": "Muster GmbH",
"invoice_number": "RE-1024",
"line_items": [ /* Positionen, je mit eigenem Konfidenzwert */ ]
}
}
}Ein Detail, das bei der Fehlerbehandlung in Schritt 7 wichtig wird: pages und billedPages können auseinanderfallen, wenn einzelne Seiten eines Dokuments nicht auswertbar waren — ein Signal, das sich lohnt, separat zu protokollieren, statt es stillschweigend zu ignorieren.
4. Die Antwortstruktur in Ihr Datenmodell mappen
Ein Mapping, kein Umbau Ihres Schemas
Ein praktischer Kniff dabei: Behalten Sie die Original-Feldnamen der Antwort bei, statt sie beim Mapping in eigene Bezeichnungen zu übersetzen. Das erspart bei jeder künftigen API-Änderung einen Übersetzungsschritt und macht Support-Anfragen leichter nachvollziehbar, weil ein Blick in Ihre eigene Datenbank direkt der Struktur aus der API-Dokumentation entspricht.
5. Einen Konfidenz-Schwellenwert festlegen
Eine erste, bewusst grobe Schwelle
Eine einzelne globale Schwelle ist der richtige Startpunkt, aber selten die endgültige Lösung. Nach den ersten hundert echten Belegen zeigt sich meist ein Muster: Kopfdaten wie Lieferant und Rechnungsnummer liegen fast immer deutlich über der Schwelle, während einzelne Positionsfelder — etwa ein ungewöhnlich formatierter Rabatt — regelmäßiger darunter liegen. Eine feldspezifische Schwelle, die für Positionsfelder etwas strenger ist als für Kopfdaten, spiegelt diese reale Verteilung oft besser wider als ein einzelner Wert für alles.
6. Eine Prüfoberfläche für unsichere Felder bauen
Nur die markierten Felder zeigen, nicht das ganze Dokument
Ein praktisches Detail, das oft übersehen wird: Zeigen Sie den Originalausschnitt genau an der Position, an der das Feld auf dem Beleg tatsächlich stand, nicht nur den erkannten Text isoliert. Ein Nutzer, der ein markiertes Feld gegen den Originalbeleg prüft, braucht dafür Sekunden — muss er stattdessen erst den ganzen Beleg durchsuchen, um die passende Stelle zu finden, verlieren Sie einen guten Teil des Zeitgewinns, den die feldgenaue Markierung eigentlich verspricht.
7. Fehler- und Rate-Limit-Behandlung einbauen
Explizit, nicht als Sonderfall vergessen
Ein häufiger, teurer Fehler: eine fehlgeschlagene Antwort wird stillschweigend wie ein leeres, aber korrektes Ergebnis behandelt — ein Beleg "verschwindet" dann für den Nutzer, ohne dass irgendwo ein Fehler sichtbar wird.
8. Export nach DATEV oder in Ihr Zielformat anbinden
Export ist ein eigener Aufruf, keine erneute Extraktion
POST /exportmit dem gewünschten Format auf — DATEV-EXTF, Excel oder CSV — statt den Beleg für den Export erneut zu extrahieren.curl -X POST https://flowparse.io/api/v1/export \
-H "Authorization: Bearer pf_live_xxx" \
-H "Content-Type: application/json" \
-d '{ "format": "datev", "type": "invoice", "data": { ... } }'Wenn Ihre Software mehrere Zielsysteme parallel bedienen muss, lohnt es sich, den Export als eigenen, austauschbaren Schritt zu behandeln, statt ihn fest an einen bestimmten Kunden zu koppeln — derselbe geprüfte Datensatz lässt sich mit demselben Aufruf, nur einem anderenformat-Parameter, sowohl nach DATEV als auch nach Excel oder CSV exportieren.
9. Mit echten Kundendokumenten testen, nicht mit Beispieldaten
Layoutvielfalt lässt sich nicht simulieren
Eine gute Faustregel für die Auswahl: mindestens ein Beleg pro tatsächlich vorkommendem Belegtyp, mindestens ein mehrseitiger Beleg mit einer langen Positionstabelle, und mindestens ein Beleg, der in der Vergangenheit bei einer anderen Lösung bereits Probleme gemacht hat. Diese drei Kategorien zusammen decken die meisten Randfälle ab, die in der Praxis tatsächlich auftreten, ohne dass Sie Dutzende Testbelege sammeln müssten.
10. Auf einen bezahlten Plan wechseln
Eine Konfigurationsänderung, keine erneute Integration
Ein sinnvoller Zeitpunkt für den Wechsel ist nicht ein fester Kalendertag, sondern der Moment, an dem das kostenlose Seitenkontingent regelmäßig ausgeschöpft wird, bevor der Monat endet — ein verlässliches Signal, dass die Integration bereits echten Nutzen stiftet, nicht nur getestet wird.
Ein vollständiges Beispiel von Anfang bis Ende
Eine Kanzleisoftware bindet die Erkennung für eingehende Mandantenbelege an. Ein Mandant lädt eine zweiseitige Rechnung hoch; das Backend ruft /extractauf und erhält nach rund drei Sekunden das vollständige Ergebnis mit acht Positionen. Sieben Positionen liegen über der Schwelle von 0,90 und werden automatisch übernommen; eine Position mit einer ungewöhnlich formatierten Mengenangabe liegt darunter und erscheint in der Prüfoberfläche der Kanzlei. Nach einer Bestätigung mit einem Klick exportiert die Software die Daten per /exportals DATEV-Buchungsstapel für den jeweiligen Mandanten. Gesamtdauer vom Upload bis zur fertigen DATEV-Datei: unter einer Minute, davon der größte Teil die Bestätigung der einen markierten Position.
SKR03 gegen SKR04 — worauf es beim Export ankommt
Ein Detail, das bei der Export-Anbindung leicht übersehen wird: Nicht jeder Mandant oder Kunde bucht nach demselben Kontenrahmen. SKR03 ist der in Deutschland verbreitetere, prozessorientierte Kontenrahmen; SKR04 ist abschlussorientiert aufgebaut und bei größeren Unternehmen und Kapitalgesellschaften häufiger im Einsatz. Die API selbst trifft keine Annahme darüber, welchen Kontenrahmen ein bestimmter Mandant nutzt — sie liefert sichere SKR03-Standardwerte als Ausgangspunkt, die sich beim Export überschreiben lassen.
Für eine Kanzleisoftware mit Mandanten in beiden Kontenrahmen bedeutet das: Die Zuordnung von Konto und Gegenkonto sollte als eigene, pro Mandant konfigurierbare Ebene zwischen der Erkennung und dem eigentlichen DATEV-Export sitzen — nicht fest im Erkennungsschritt selbst verankert. Auf diese Weise lässt sich derselbe erkannte Beleg für einen SKR03-Mandanten und einen SKR04-Mandanten unterschiedlich kontieren, ohne die Erkennung selbst anzufassen.
| Merkmal | SKR03 | SKR04 |
|---|---|---|
| Aufbau | Prozessorientiert | Abschlussorientiert (an der Bilanzgliederung) |
| Typische Nutzer | Kleinere Betriebe, viele Kanzlei-Mandanten | Größere Unternehmen, Kapitalgesellschaften |
| Rolle der API | Liefert Standardwerte, überschreibbar | Gleiche Rolle, andere Zielkonten |
| Wo die Zuordnung sitzt | In einer eigenen Konfigurationsebene, nicht in der Erkennung | Ebenso |
Eine Fehlerdiagnose in der Praxis
Ein konkreter, häufig wiederkehrender Fall zeigt, wie sich ein scheinbares Erkennungsproblem in der Praxis auf die eigene Integration statt auf die API zurückführen lässt. Ein Kunde meldet: "Der Bruttobetrag stimmt nicht." Der erste Schritt ist nicht, die Erkennung zu misstrauen, sondern den Konfidenzwert des betroffenen Felds in der ursprünglich gespeicherten Antwort nachzuschlagen — Sie speichern diesen Wert ja bereits aus Schritt 4.
War der Konfidenzwert niedrig und lag unterhalb Ihrer Schwelle, sollte das Feld ohnehin in der Prüfoberfläche markiert gewesen sein — die eigentliche Frage ist dann, warum der Nutzer den markierten Wert trotzdem unverändert bestätigt hat, nicht, warum die Erkennung falsch lag. War der Konfidenzwert hingegen hoch, lohnt sich ein Blick auf das Original: In der überwiegenden Mehrheit solcher Fälle liegt die Ursache nicht in der Erkennung selbst, sondern in einem Rundungsfehler beim eigenen Mapping — etwa wenn ein Bruttobetrag lokal aus Netto- und Steuerbetrag neu berechnet statt aus dem bereits gelieferten Bruttofeld übernommen wird.
Eine einfache Diagnoseregel, die sich in der Praxis bewährt: Zuerst den gespeicherten Konfidenzwert prüfen, dann das eigene Mapping, erst danach — falls beides unauffällig ist — den Originalbeleg selbst. In dieser Reihenfolge lässt sich die eigentliche Ursache meist in wenigen Minuten finden, statt tagelang zwischen allen drei Möglichkeiten zu raten.
Häufige Fehler bei der Integration
Die folgenden vier Fehler tauchen in Integrationsprojekten immer wieder auf, unabhängig von der Größe des Teams oder der Komplexität des Produkts. Alle vier haben eines gemeinsam: Sie sind erst im laufenden Produktivbetrieb sichtbar, nicht im Test mit sauberen Beispieldaten — ein weiterer Grund, warum Schritt 9 in dieser Anleitung so viel Gewicht bekommt.
Der Konfidenz-Schwellenwert wird ignoriert
Alle Felder werden ungeprüft automatisch übernommen — der erste falsch gebuchte Beleg untergräbt dann das Vertrauen in die gesamte Integration, nicht nur in ein Feld.
Fehlerantworten werden wie leere Erfolge behandelt
Ein nicht konvertierbares Dokument wird stillschweigend übersprungen, statt dem Nutzer sichtbar zu melden, dass hier eine manuelle Erfassung nötig ist.
Nur mit sauberen Beispieldaten getestet
Die Integration funktioniert im Test einwandfrei und zeigt erst mit echten, unterschiedlichen Kundenbelegen ihre eigentlichen Randfälle.
Export und Extraktion vermischt
Für jeden Export wird der Beleg erneut extrahiert, statt die bereits vorliegenden, geprüften Daten wiederzuverwenden — das kostet unnötig Seiten und Zeit.
Wer im Team wofür zuständig ist
Auch bei einer kleinen Integration lohnt sich eine kurze, explizite Klärung der Zuständigkeiten, bevor der erste Code geschrieben wird. Die Anbindung der Endpunkte selbst — Schritte 1 bis 4 — ist reine Backend-Arbeit und lässt sich meist von einer einzelnen Person in wenigen Tagen umsetzen. Die Prüfoberfläche aus Schritt 6 dagegen betrifft direkt die Nutzererfahrung und profitiert davon, früh mit jemandem aus Produkt oder Design abgestimmt zu werden — eine Oberfläche, die technisch korrekt, aber umständlich zu bedienen ist, untergräbt den ganzen Sinn der automatischen Erkennung.
Für die Festlegung des Konfidenz-Schwellenwerts aus Schritt 5 ist reines Entwicklerurteil selten ausreichend — hier lohnt sich die Einbindung von jemandem, der die tatsächlichen Kundenbelege und deren Fehlertoleranz kennt, etwa aus dem Support oder dem Kundenerfolgsteam. Diese Person sieht oft am schnellsten, ob ein bestimmter automatisch übernommener Wert in der Praxis zu Beschwerden führt, lange bevor sich das in einer Kennzahl niederschlägt.
Bewährte Praxis
Getrennte API-Schlüssel für Test und Produktivbetrieb
Jeder Schlüssel lässt sich unabhängig widerrufen und in GET /usage getrennt auswerten.
Schwellenwert je Kunde statt global
Ein Kunde mit stark standardisierten Belegen verträgt eine niedrigere Prüfschwelle als einer mit vielen unterschiedlichen Lieferanten.
Originalausschnitt neben dem markierten Feld anzeigen
Die Prüfung eines Felds dauert Sekunden, wenn der Nutzer den Originalbeleg direkt daneben sieht, statt zwischen zwei Fenstern zu wechseln.
Preis pro Seite in die eigene Kundenkalkulation einrechnen
Der feste Satz von 0,035 € pro Seite lässt sich direkt in eine eigene Preisgestaltung übernehmen, statt als schwankende Infrastrukturkostenzeile zu erscheinen.
Wie lange die Integration realistisch dauert
| Schritt | Typischer Aufwand |
|---|---|
| Schritte 1–3: erster Aufruf | Wenige Stunden |
| Schritt 4: Mapping ins eigene Datenmodell | Ein bis zwei Tage |
| Schritte 5–6: Schwellenwert und Prüfoberfläche | Drei bis fünf Tage |
| Schritt 7: Fehlerbehandlung | Ein Tag |
| Schritt 8: Export-Anbindung | Ein bis zwei Tage |
| Schritt 9: Test mit echten Belegen | Fortlaufend, parallel zur Entwicklung |
Rollback und Absicherung beim Livegang
Auch eine sorgfältig getestete Integration verdient einen einfachen Rückweg für die ersten Produktivwochen. Der unkomplizierteste Ansatz: Beide Erkennungspfade — die alte Lösung, falls vorhanden, und die neue API — bleiben für eine begrenzte Zeit parallel aktiv, gesteuert über eine einfache Feature-Flag-Prüfung pro Kunde. Zeigt sich bei einem bestimmten Kunden ein unerwartetes Muster, lässt sich dessen Verkehr mit einer einzigen Konfigurationsänderung zurück auf den alten Pfad schalten, ohne einen Notfall-Deploy auszulösen.
Ebenso hilfreich ist ein einfaches Monitoring auf die Verteilung der Konfidenzwerte selbst, nicht nur auf Fehlerraten: Ein plötzlicher, breiter Rückgang der durchschnittlichen Konfidenz über viele Belege hinweg — statt eines einzelnen Ausreißers — ist ein früheres und verlässlicheres Warnsignal für ein echtes Problem in der Integration selbst, etwa ein Fehler im eigenen Mapping nach einem Deploy, als einzelne Kundenbeschwerden es wären.
Zusammenfassung der zehn Schritte
Von der ersten Anmeldung bis zum produktiven DATEV-Export sind es zehn klar abgrenzbare Schritte, die sich in dieser Reihenfolge selten überspringen lassen, ohne später doppelte Arbeit zu verursachen: Schlüssel anlegen, den Datenvertrag kostenlos testen, echte Belege extrahieren, das Ergebnis mappen, eine Schwelle festlegen, eine Prüfoberfläche bauen, Fehlerfälle behandeln, den Export anbinden, mit echten Kundendokumenten testen und schließlich auf einen bezahlten Plan wechseln. Jeder einzelne Schritt für sich ist überschaubar — die Summe ergibt eine vollständige, produktionsreife Integration, typischerweise innerhalb von ein bis drei Wochen, abhängig davon, wie viel Zeit in die eigene Prüfoberfläche fließt.
Checkliste vor dem Livegang
Bevor die Integration für echte Kunden freigeschaltet wird, lohnt sich ein letzter, kurzer Durchgang durch die Punkte, die im laufenden Betrieb am schwersten nachträglich zu korrigieren sind:
Ist der API-Schlüssel serverseitig gespeichert?
Ein Schlüssel im Frontend-Code, auch nur temporär zum Testen, ist ein Sicherheitsrisiko, das leicht übersehen wird und schwer rückgängig zu machen ist, sobald der Code einmal ausgeliefert wurde.
Reagiert die Software korrekt auf einen Fehlercode?
Ein simulierter Fehlerfall — etwa ein absichtlich beschädigtes Test-PDF — sollte sichtbar in Ihrer eigenen Oberfläche landen, nicht stillschweigend verschwinden.
Ist die Konfidenz-Schwelle an echten Belegen kalibriert?
Eine Schwelle, die nur gegen Beispieldaten getestet wurde, verhält sich bei echten, vielfältigeren Kundenbelegen oft anders als erwartet.
Ist der Export-Pfad für alle relevanten Zielformate getestet?
Ein Export, der nur für ein einzelnes Zielformat getestet wurde, kann bei einem anderen — etwa DATEV statt Excel — Randfälle zeigen, die vorher nicht sichtbar waren.
Ist GET /usage in Ihre eigene Kostenübersicht eingebunden?
Ohne eine eigene Sichtbarkeit auf den Verbrauch ist ein unerwarteter Kostenanstieg erst am Monatsende erkennbar, statt frühzeitig.
Welche Kennzahlen sich zu beobachten lohnen
Nach dem Livegang lohnt sich ein kleines, festes Set an Kennzahlen, statt die Integration nur punktuell bei Beschwerden zu betrachten. Der Anteil der Belege, die vollständig automatisch — ohne eine einzige manuelle Bestätigung — durchlaufen, ist die direkteste Messgröße für den tatsächlichen Automatisierungsgewinn. Die durchschnittliche Anzahl markierter Felder je Beleg zeigt, ob die Schwellenwert-Kalibrierung noch zum aktuellen Beleg-Mix passt oder nachjustiert werden sollte. Und die Zeit zwischen Upload und abgeschlossener Freigabe verrät, ob die Prüfoberfläche tatsächlich die versprochene Zeitersparnis liefert oder selbst zu einem Engpass geworden ist.
Keine dieser drei Kennzahlen erfordert eigene Infrastruktur — alle drei lassen sich direkt aus den Daten ableiten, die Sie ohnehin schon aus Schritt 4 in Ihrer eigenen Datenbank speichern, kombiniert mit dem Zeitstempel der jeweiligen Freigabe-Aktion.
Neue Mandanten oder Kunden onboarden
Sobald die Integration produktiv läuft, wiederholt sich eine Frage bei jedem neuen Mandanten oder Kunden: Wie viel Vorlaufzeit braucht die Erkennung, bis sie für dessen konkrete Belege zuverlässig funktioniert? Die ehrliche Antwort lautet meist: keine gesonderte, da die Erkennung nicht auf einen bestimmten Lieferantenkreis trainiert werden muss. Ein neuer Mandant lässt sich mit denselben Standardeinstellungen — Schwellenwert, Kontenrahmen-Zuordnung — starten wie ein bestehender, und erst wenn dessen erste echten Belege durchlaufen sind, zeigt sich, ob eine individuelle Anpassung überhaupt nötig ist.
In der Praxis lohnt sich trotzdem ein kurzer, standardisierter Ablauf für die ersten Belege eines neuen Mandanten: die ersten fünf bis zehn Belege bewusst vollständig manuell prüfen, auch die Felder über der Konfidenz-Schwelle, um ein Gefühl für die typischen Lieferantenlayouts dieses einen Mandanten zu bekommen. Zeigt sich dabei ein systematisches Muster — etwa ein Hauptlieferant mit einem ungewöhnlichen Tabellenlayout —, lässt sich das früh und gezielt in der eigenen Prüfoberfläche berücksichtigen, statt es erst nach Wochen laufender Beschwerden zu bemerken.
Sicherheit und Datenschutz
Der API-Schlüssel gehört ins Backend, nicht ins Frontend — ein direkter Aufruf aus dem Browser würde ihn offenlegen. API-Schlüssel werden serverseitig ausschließlich als SHA-256-Hash gespeichert, und ein hochgeladener Beleg wird unmittelbar nach der Verarbeitung gelöscht. FlowParse ist kein Archivsystem — die Aufbewahrungspflicht für den Originalbeleg bleibt bei Ihrer Software.