Belege per KI-Agent einreichen, prüfen und buchen

Vom Upload zur Buchung in vier Schritten

upload_receipt: was die Datei mitbringen muss

Pflicht sind filename (mit Endung) und content_base64, also die Datei Base64-kodiert. Optional sind content_type und direction — Eingangsbeleg als Standard oder Ausgangsbeleg.

• Formate: PDF, PNG, JPEG, WebP sowie XRechnung oder ZUGFeRD als XML.
• Größe: Über den gehosteten MCP-Server höchstens rund 7 MB je Datei, weil eine Anfrage bis 10 MB groß sein darf und Base64 die Datei um ein Drittel vergrößert. Dateien bis 20 MB nimmt die REST-API unter POST /v1/receipts als multipart an.
• Wiederholung: Dieselbe Datei erneut senden liefert denselben Beleg zurück; ein zweiter entsteht nicht.
• Schon gebucht: Steht dieselbe Rechnung — gleiche Rechnungsnummer, gleicher Partner, gleicher Betrag — bereits in der Buchhaltung, speichert der Server die Kopie nicht und sagt das in der Antwort.
• Kein Beleg: Ein Logo, eine Signatur oder eine Newsletter-Grafik weist der Server mit not_a_receipt ab.
• Menge: Je Gesellschaft nimmt die API höchstens 200 Belege in rollierenden 24 Stunden an.
• Kontingent: Belege, die die Belegerkennung liest, zählen wie im Posteingang auf das Kontingent der KI-erkannten Belege — 100 je Gesellschaft und Monat sind enthalten, jeder weitere kostet 0,20 €. E-Rechnungen im XML-Format liest der Server ohne KI.

Ihr KI-Programm muss die Datei dafür selbst lesen und als Base64 übergeben können. Kann es das nicht, laden Sie Belege wie gewohnt in der App hoch oder schicken sie an den Posteingang: list_receipts zeigt dem Agenten alle Belege, gleich ob per API, Upload, Posteingang oder Anbindung eingegangen.

Buchungsvorschlag lesen und bestätigen

list_receipts zeigt die Belege mit ihrem Stand — processing, received, needs_review, booked oder dismissed —, neueste zuerst, filterbar nach Eingangsdatum und Richtung. Für jeden Beleg mit needs_review holt der Agent mit get_receipt_proposal den Vorschlag: Soll- und Habenkonto, Steuerschlüssel, Betrag, Datum, Gegenpartei, confidence_level, die Herkunft der Kontierung und unter explanation.needs_check, ob vor dem Buchen etwas zu prüfen ist.

Die Antwort enthält außerdem state_version. Diesen Wert gibt der Agent an confirm_receipt weiter, zusammen mit der Beleg-ID und einer neuen UUID als idempotency_key. Der Server bucht über denselben Weg wie „Buchen“ in der Belegprüfung und prüft Geschäftsjahr, Festschreibung, Dubletten, Umsatzsteuer, Kreditor, Anlage und Abgrenzung. Hat sich der Beleg zwischenzeitlich geändert, passt state_version nicht mehr, und der Agent lädt den Vorschlag neu.

Ist der Vorschlag falsch oder meldet er correction_required, bucht der Agent mit correction: Er übernimmt die correction_template vollständig, ändert nur das Falsche und nennt einen Grund, der als Prüfspur gespeichert wird. Dublettenhinweise kann er über die Schnittstelle nicht übersteuern — er zeigt sie Ihnen, und ist es wirklich eine Dublette, legt er den Beleg mit dismiss_receipt ab.

Alternativ bucht book_incoming_invoice eine Eingangsrechnung zu einem Beleg: mit receipt_id und dem receipt_updated_at aus dem Vorschlag als expected_receipt_updated_at. Rückholbar ist jede Belegbuchung nur per Storno; für eine Eingangsrechnung erledigt das cancel_incoming_invoice, danach liegt der Beleg wieder zur Prüfung bereit.

Ablegen, verwerfen, löschen — drei verschiedene Dinge

Beispiel: drei Rechnungen aus einem Ordner

Ein typischer Auftrag an einen Agenten mit Dateizugriff:

Im Ordner „Rechnungen Oktober“ liegen drei PDFs.
Bitte alle als Eingangsbelege einliefern.
Was nicht automatisch gebucht wird: Vorschlag zeigen,
nach meinem Okay buchen. Dubletten nicht buchen, sondern ablegen.

Schritt 1: Der Agent liest die drei Dateien, kodiert sie als Base64 und ruft je Datei upload_receipt mit filename und content_base64 auf. Die Antwort nennt je Beleg ID und Stand sowie outcome created, existing oder duplicate.

Schritt 2: Mit list_receipts prüft er kurz darauf, welche Belege der Autopilot schon gebucht hat (booked) und welche needs_review tragen.

Schritt 3: Für jeden offenen Beleg ruft er get_receipt_proposal auf und zeigt Ihnen Lieferant, Betrag, Konto und Steuerschlüssel — und den Prüfhinweis, falls needs_check gesetzt ist.

Schritt 4: Nach Ihrem Okay bucht er mit confirm_receipt, mit state_version aus dem Vorschlag und einer neuen UUID. Meldet der Server eine mögliche Dublette, bucht er nicht, sondern legt den Beleg nach Rückfrage mit dismiss_receipt und dem Grund „Dublette“ ab.

Originaldatei und Belegarchiv

get_receipt_file nennt Name, Typ und download_path der Originaldatei. Die Datei selbst geht bewusst nicht durch das Sprachmodell: Ihr Agent lädt sie per REST mit dem Schlüssel aus einer Umgebungsvariable, nie mit einem Schlüssel aus dem Chat.

get_receipt_archive liefert für ein Geschäftsjahr das Belegarchiv — den GoBD-Datenexport samt Originalbelegen — in Teilen mit Belegzahl, Größe und Download-Pfad. Fehlen Originaldateien, meldet der Server das; der Agent zeigt Ihnen die betroffenen Belege und lädt den Teil nur nach Ihrer Bestätigung trotzdem.

Häufige Fragen

Welche Belegformate kann der Agent einreichen?

PDF, PNG, JPEG und WebP sowie E-Rechnungen als XRechnung oder ZUGFeRD im XML-Format. Über den gehosteten MCP-Server sind Dateien bis rund 7 MB möglich, über die REST-API bis 20 MB.

Zählen Belege vom Agenten auf das Belegkontingent?

Ja, genauso wie Belege aus dem Posteingang: Jeder Beleg, den die Belegerkennung liest, zählt auf das monatliche Kontingent der KI-erkannten Belege Ihrer Gesellschaft. E-Rechnungen im XML-Format werden ohne KI gelesen.

Was passiert, wenn der Agent denselben Beleg zweimal schickt?

Es entsteht nichts doppelt. Dieselbe Datei liefert denselben Beleg zurück. Steht die Rechnung mit gleicher Nummer, gleichem Partner und gleichem Betrag schon in der Buchhaltung, wird die Kopie nicht gespeichert. Und confirm_receipt liefert bei einer Wiederholung mit derselben UUID dieselbe Buchung, keine zweite.

Kann der Agent einen gebuchten Beleg löschen?

Nein. Ein gebuchter Beleg ist aufbewahrungspflichtig und wird weder verworfen noch gelöscht. Eine falsche Buchung nimmt der Agent per Storno zurück, bei einer Eingangsrechnung mit cancel_incoming_invoice; danach liegt der Beleg wieder zur Prüfung bereit.

Sieht der Agent auch Belege, die ich in der App hochgeladen habe?

Ja. list_receipts zeigt alle Belege der Gesellschaft mit ihrem Buchungsstand, gleich ob per API, Upload, Posteingang oder Anbindung eingegangen. Der Agent kann also auch Belege abarbeiten, die über den Posteingang gekommen sind und auf Prüfung warten.

Kann der Agent die Kontierung eines Belegs ändern?

Ja, vor dem Buchen: confirm_receipt mit correction ändert den Vorschlag begründet und bucht ihn dann. Der Grund wird als Prüfspur gespeichert. Nach dem Buchen geht das nur noch per Storno und neuer Buchung.