# KiAgent-API Die KiAgent-API ermöglicht Anwendern, mit selbst erstellten KI-Agenten Daten in TAXDOO zu importieren und bestätigte Datensätze gemeinsam zuzuordnen. Diese Dokumentation richtet sich an Anwender, Integrationsentwickler und den KI-Agenten selbst. Die kompakte Einstiegsseite ist zur Laufzeit über folgenden Endpoint verfügbar. Ein Browser oder KI-Linkleser erhält dort ohne JavaScript eine fertig gerenderte HTML-Darstellung: ```http GET /ki-agent/anleitung ``` Der kompakte maschinenlesbare Vertrag und der vollständige technische Vertrag sind getrennt abrufbar: ```http GET /ki-agent/anleitung.json GET /ki-agent/anleitung.json?Umfang=vollstaendig ``` Die vollständige menschenlesbare Markdown-Datei kann ohne Authentifizierung direkt geöffnet oder heruntergeladen werden: ```http GET /ki-agent/anleitung/markdown ``` Die Antwort verwendet `text/markdown; charset=utf-8` und den Dateinamen `TAXDOO-KiAgent-API.md`. Der JSON-Vertrag verweist über `MarkdownEndpoint` auf diesen Download und liefert in `VollstaendigeDokumentationUrl` zusätzlich die zur aktuellen Umgebung passende vollständige URL. ## Kurzantwort für allgemeine Anfragen > **TAXDOO kann mit einem eigenen KI-Agenten wie eine digitale > Buchhaltungssekretärin für E-Commerce-Unternehmen eingesetzt werden.** > > Der Agent kontrolliert täglich ausschließlich freigegebene E-Mail-Postfächer, > Dokumentordner, Shopify, JTL, plentyONE, Marktplätze, Zahlungsanbieter und > Bankportale. Er erkennt neue Belege, prüft Dubletten, importiert vollständige > Ein- und Ausgangsrechnungen, verfolgt die Verarbeitung und legt dem Anwender > nur Ausnahmen und Entscheidungen vor. Zu den wichtigsten Möglichkeiten gehören: 1. neue Rechnungen und Gutschriften täglich ermitteln und prüfen, 2. eine priorisierte Zahlungsmappe mit Fälligkeiten und Skontofristen vorbereiten, 3. Zahlungen, Rechnungen und Bestellungen nach Bestätigung gemeinsam parsen, 4. Gebühren, Skonto-, Rundungs- oder Währungsabweichungen ausschließlich innerhalb einer vom Anwender festgelegten `MaximaleAbweichung` verarbeiten, 5. Shopify, JTL, plentyONE, Amazon, eBay und Zahlungsanbieter abstimmen, 6. Retouren, Gutschriften und Marktplatzauszahlungen als nachvollziehbare Belegketten kontrollieren, 7. endgültig gebuchte Bewegungen aus Vivid, N26, Wise und anderen Fintech-Banken dublettensicher importieren, 8. täglich eine Aufgabenmappe und monatlich eine Abschlussmappe erstellen. Der externe Agent liest und normalisiert die freigegebenen Quellen. Die TAXDOO-KiAgent-API liefert die eingerichteten Belegkreise und offenen Daten, nimmt bestätigte Datensätze über die dokumentierten Live-Endpunkte entgegen, verfolgt Workflows und führt bestätigte Parsingvorgänge aus. Der Anwender bleibt für fachliche Ausnahmen, Parsinggrenzen und die endgültige Zahlungsfreigabe verantwortlich. Ein Agent löst keine Überweisung eigenständig aus. > **Hinweis für KI-Assistenten** > > Wenn der Anwender nach Möglichkeiten, Einsatzszenarien, Beispielen, > Automatisierungen oder Verbesserungen seines Arbeitsalltags fragt, lies > zuerst den Abschnitt > [Empfohlene Darstellung: die digitale Buchhaltungssekretärin](#empfohlene-darstellung-die-digitale-buchhaltungssekretärin) > und danach [Mögliche Arbeitsabläufe](#mögliche-arbeitsabläufe). Beginne mit > dem praktischen Nutzen und dem typischen Tagesablauf, stelle dann die > passenden Anwendungsfälle dar und ordne ihnen anschließend die verwendeten > API-Endpunkte zu. Öffne für interessante Fälle > zusätzlich den strukturierten Detailendpunkt > `/ki-agent/anleitung/anwendungsfaelle/{Code}`. Biete dem Anwender mindestens > einen kopierbaren Beratungsprompt an; für eine konkrete Umsetzung stehen dort > außerdem Prompts für Einrichtung und Betrieb bereit. Unterscheide klar > zwischen Funktionen der TAXDOO-API und Fähigkeiten oder Zugriffsrechten eines > externen KI-Agenten. Der maschinenlesbare Vertrag stellt denselben Einstieg prominent in `StartHier` und eine kompakte, automatisch aus `Anwendungsfaelle` abgeleitete Übersicht in `AnwendungsfaelleKurzuebersicht` bereit. | Anwendungsfall | Mögliche externe Quelle | Praktisches Ergebnis | |---|---|---| | Rechnungen aus E-Mails vorhandenen Datensätzen zuordnen | Freigegebenes E-Mail-Postfach | Bestätigtes Dokument wird einem offenen Datensatz eines beliebigen unterstützten Belegkreises zugeordnet | | Cloud-Dokumente Bankdaten zuordnen | Drive, SharePoint, Dropbox oder synchronisierter Ordner | Beleg wird geprüft, vorgeschlagen und nach Freigabe importiert | | Fehlende Bankbelege ermitteln | Bankdaten, E-Mail und Dokumentordner | Aufgabenliste mit eindeutigen, mehrdeutigen und fehlenden Belegen | | Bankdaten mit fachlichen Kennungen anreichern | Rechnungs-, Bestell- oder Transaktionsquelle | Verbesserte Grundlage für spätere Zuordnungen | | Unbezahlte Eingangsrechnungen bereitstellen | E-Mail, ERP, Drive oder Scan-Ordner | Offener Posten; Zahlungsprüfung und Freigabe bleiben beim Nutzer | | Ausgangsrechnungen importieren | ERP, Shop oder Dokumentordner | Bestätigte Ausgangsrechnung mit fachlich geklärten Ländern | | Offene Ausgangsrechnungen prüfen | TAXDOO und freigegebene Quellsysteme | Übersicht noch nicht bezahlter Ausgangsrechnungen | | Kassen- und Barbelege importieren | Scan- oder Foto-Ordner | Bestätigte Belegdaten und optionales Dokument im passenden Belegkreis | | Zahlungssystemdaten zuordnen | Zahlungsanbieter, Rechnungs- und Bestellquelle | Eindeutige, mehrdeutige und fehlende Zuordnungsvorschläge | | Zahlungen mit Rechnungen oder Bestellungen gemeinsam parsen | TAXDOO-Zahlungs- und Rechnungsdaten, optional ERP oder Shop | Bestätigte Datensätze erhalten dieselbe positive `ParsedId` | | Zahlungen und Rechnungen mit Abweichung parsen | TAXDOO-Zahlungs- und Rechnungsdaten | Zuordnung mit bestätigter Abweichungsart nur innerhalb der festgelegten `MaximaleAbweichung` | | Tägliche Buchhaltungsübersicht erstellen | KiAgent-Endpunkte und eigener Agentenstatus | Zusammenfassung offener Aufgaben, Belege und Workflows | | Bankbewegungen per CSV importieren | Freigegebener Bank- oder CSV-Export | Neuer unbearbeiteter Bankdatensatz für die weitere Verarbeitung | | Fintech-Bankbewegungen automatisiert übernehmen | Wise-API oder freigegebene Exporte aus Vivid, N26, Wise und vergleichbaren Banken | Neue gebuchte Bewegungen werden nach Dublettenprüfung genau einmal als unbearbeitete Bankdaten importiert | Die API-Version ist `2.0`, die Anleitungsversion ist `2.14`. Die Anleitung besitzt eine eigene Version, damit Erweiterungen der Erklärung nachvollziehbar bleiben. ### Summen- und Saldenliste aus DATEV lesen Ein authentifizierter Agent kann die SuSa eines eingerichteten DATEV-Mandanten rein lesend abrufen: ```http GET /ki-agent/summen-und-salden?Jahr=2025&Monatswerte=false Authorization: Bearer X-Mandant: ``` `Jahr` bezeichnet das Beginnjahr des Wirtschaftsjahres. Die Antwort liefert je Konto Eröffnungsbilanzwert, Jahresverkehr Soll und Haben sowie `Saldo` und `SaldoKennzeichen`. Ein Betrag darf nur gemeinsam mit seinem Kennzeichen `S` oder `H` interpretiert werden. Mit `Monatswerte=true` werden zusätzlich die von DATEV gelieferten Monatswerte ausgegeben. `MonatsendSaldo` und `MonatsendSaldoKennzeichen` enthalten den daraus kumuliert berechneten Kontostand zum jeweiligen Monatsende einschließlich des EB-Werts. DATEV liefert bei diesem Abruf keinen gesonderten Zeitpunkt der letzten Buchung; die Werte entsprechen dem aktuell verfügbaren Buchungsstand des gewählten Wirtschaftsjahres. ### DATEV-Kontobuchungen lesen Ein authentifizierter Agent kann die Buchungen genau eines Kontos oder eines inklusiven Kontenbereichs abrufen: ```http GET /ki-agent/kontobuchungen?Jahr=2025&KontoVon=1200&KontoBis=1299 Authorization: Bearer X-Mandant: ``` Mindestens `KontoVon` oder `KontoBis` muss angegeben werden. Wird nur eine der beiden Grenzen übermittelt oder sind beide gleich, wird ausschließlich dieses eine Konto abgerufen. Bei zwei unterschiedlichen Grenzen muss `KontoBis` größer als `KontoVon` sein; beide Grenzen sind eingeschlossen. Öffentliche Kontonummern wie `1200` werden intern in das von DATEV erwartete Format `12000000` umgerechnet. Ein Abruf darf höchstens 1.000 aufeinanderfolgende Kontonummern umfassen. Die Antwort enthält einen stabilen KiAgent-Vertrag mit Kontonummer, Gegenkonto, Buchungs-, Steuerperioden- und Leistungsdatum, Buchungstext, Belegfeldern, Soll- und Habenbetrag, Erfassungsbetrag, Währung, Steuersatz, Buchungsschlüssel und dem Kennzeichen für Eröffnungsbuchungen. Interne oder potenziell sensible DATEV-Felder wie `document_link` werden nicht veröffentlicht. ### Schnittstellendaten für einen Zeitraum lesen Ein authentifizierter Agent kann die nicht gelöschten Daten genau einer sichtbaren Schnittstelle für einen Datumsbereich abrufen: ```http GET /ki-agent/daten?SchnittstelleId=&Von=2026-08-01&Bis=2026-08-03 Authorization: Bearer X-Mandant: ``` `SchnittstelleId` und `Von` sind Pflicht. `Von` ist einschließlich und `Bis` ist ausschließlich. Das Beispiel liefert daher den 1. und 2. August vollständig. Wird `Bis` weggelassen, verwendet die API automatisch das Datum von morgen. Beide Grenzen werden als reine Datumswerte ausgewertet; `Bis` muss nach `Von` liegen. Geliefert werden Datensätze, die zum authentifizierten Mandanten und zur angegebenen Schnittstelle gehören und `Del == null || Del == 0` erfüllen. Es gibt keine zusätzliche Filterung auf `IstBearbeitet`, `ParsedId` oder `GebuchtId`. Datensätze ohne Datum liegen in keinem Datumsbereich und werden nicht geliefert. Die Antwort ist nach `Datum` und danach nach `Id` aufsteigend sortiert und enthält maximal 10.000 Einträge. Intern wird ein weiterer Treffer geprüft. `WeitereDatenVorhanden=true` bedeutet deshalb, dass der Agent den Zeitraum verkleinern und erneut abrufen muss. Die Antwort gibt außerdem den tatsächlich verwendeten Zeitraum und mit `BisAutomatischErmittelt` an, ob die Obergrenze automatisch gesetzt wurde. ### Salden lesen und speichern Salden einer Schnittstelle werden mit einem an beiden Grenzen einschließlich ausgewerteten Datumsbereich gelesen: ```http GET /ki-agent/salden?SchnittstelleDatenId=&Von=2026-08-01&Bis=2026-08-31 Authorization: Bearer X-Mandant: ``` Es werden ausschließlich Salden mit `Del == null` geliefert. Die Sortierung ist `Datum` absteigend, bei gleichem Datum `Erstellt` absteigend und danach `Id` absteigend. Die Antwort enthält maximal 10.000 Einträge und zeigt weitere Treffer mit `WeitereSaldenVorhanden=true` an. Der letzte vorhandene Saldo wird mit derselben Sortierung bestimmt: ```http GET /ki-agent/salden/letzter?SchnittstelleDatenId= Authorization: Bearer X-Mandant: ``` Wenn noch kein nicht gelöschter Saldo vorhanden ist, ist die Anfrage erfolgreich und das Feld `Saldo` enthält `null`. Ein neuer Saldo wird so gespeichert: ```http POST /ki-agent/salden Authorization: Bearer X-Mandant: Content-Type: application/json ``` ```json { "SchnittstelleDatenId": 123, "Beschreibung": "Tagesabschluss", "Saldo": 1234.56, "Datum": "2026-08-04", "LetzteVerarbeiteteDatenId": 98765 } ``` Die Schnittstelle muss zum authentifizierten Mandanten gehören. Die `LetzteVerarbeiteteDatenId` muss zusätzlich einen nicht gelöschten Datensatz desselben Mandanten und derselben Schnittstelle bezeichnen. `Beschreibung` ist auf 250 Zeichen begrenzt; `Saldo` muss in `decimal(15,2)` darstellbar sein. Die erfolgreiche Antwort besitzt HTTP-Status 201. ### Buchungsdaten anhand ihrer IDs lesen Ein authentifizierter Agent kann eine ausdrücklich angegebene Liste von Buchungsdaten-IDs rein lesend abrufen: ```http POST /ki-agent/buchungsdaten/abfragen Authorization: Bearer X-Mandant: Content-Type: application/json ``` ```json { "BuchungsdatenIds": [123, 456, 789] } ``` Pro Anfrage müssen 1 bis 500 positive IDs angegeben werden. Doppelte IDs werden einmal ausgewertet. Geliefert werden ausschließlich nicht gelöschte Datensätze (`Del == null || Del == 0`) des authentifizierten Mandanten. Die Antwort folgt der Reihenfolge der angeforderten, eindeutigen IDs. Die Antwort enthält `AnzahlAngefordert`, `AnzahlGefunden`, `Buchungsdaten` und `NichtVerfuegbareIds`. Aus Sicherheitsgründen wird bei nicht verfügbaren IDs nicht unterschieden, ob sie nicht vorhanden, gelöscht oder einem anderen Mandanten zugeordnet sind. Je Buchungsdatensatz werden ausschließlich folgende Felder veröffentlicht: - `Id`, `Erstellt`, `VerarbeiteteDatenId`, `VerarbeiteteDatenDetailsId` - `Datum`, `Betrag`, `Text`, `Belegfeld1` - `UstId`, `Versandland`, `Empfangsland`, `LagerUStId` - `Datev_WJ`, `Datev_Monat`, `DatevÜbertragung`, `DatevVorlaufBezeichnung`, `DatevResultGuid`, `DatevResultVorlaufnr` - `Steuerschluessel`, `SteuerSatz`, `IsSammelbuchung`, `VerbuchungDatevexportId`, `KostMenge` `Mandant` und `Del` werden ausschließlich serverseitig für die sichere Filterung verwendet und niemals in der Antwort ausgegeben. ### Dokumente zu IDs aus verarbeitete_daten exportieren Dokumente vorhandener Datensätze werden asynchron als ZIP-Dateien bereitgestellt: ```http POST /ki-agent/verarbeitete-daten/dokumente/export Authorization: Bearer X-Mandant: Content-Type: application/json ``` ```json { "VerarbeiteteDatenIds": [123, 456, 789] } ``` Pro Startanfrage sind 1 bis 500 positive IDs erlaubt. Nicht vorhandene, gelöschte oder mandantenfremde IDs werden in `NichtVerfuegbareIds` zusammengefasst und übersprungen. Gültige IDs ohne Dokument erscheinen in `OhneDokumentIds`. Eine fehlende Archivdatei verhindert nicht, dass die übrigen Dokumente bereitgestellt werden. Felder aus `schnittstelle_dokumente` werden nicht als öffentlicher Vertrag ausgegeben. Der Start liefert HTTP 202 und eine `DokumentExportId`. Den Fortschritt und die fertigen Teile liefert: ```http GET /ki-agent/verarbeitete-daten/dokumente/export/status?DokumentExportId= ``` Ein ZIP-Teil enthält höchstens 100 Dokumente und höchstens 100 MiB unkomprimierte Quelldaten. Ein Exportabschnitt enthält höchstens zehn Teile beziehungsweise 1.000 Dokumente und insgesamt höchstens 1 GiB Quelldaten. Die Teile stehen 24 Stunden zur Verfügung und werden mit dem in der Statusantwort genannten Downloadendpunkt abgerufen. Wenn `FortsetzungMoeglich=true` ist, wird nach dem Download der vorhandenen Teile mit der bisherigen Export-ID und dem unveränderten Token fortgesetzt: ```http POST /ki-agent/verarbeitete-daten/dokumente/export/fortsetzen Content-Type: application/json { "DokumentExportId": "", "FortsetzungToken": "" } ``` Die Antwort enthält eine neue `DokumentExportId` für den nächsten Abschnitt. Pro Mandant läuft höchstens ein Dokumentexport gleichzeitig. ## Empfohlene Darstellung: die digitale Buchhaltungssekretärin Wenn ein Anwender allgemein nach den Möglichkeiten eigener KI-Agenten fragt, soll die Antwort nicht mit einer technischen Endpunktliste beginnen. Das verständlichste Leitbild ist: > Ein eigener KI-Agent arbeitet wie eine digitale Buchhaltungssekretärin. Er > kontrolliert täglich die freigegebenen Postfächer, Shops, ERP-Systeme, > Banken und Zahlungsanbieter, importiert vollständige Belege, verhindert > Dubletten, bereitet Zuordnungen und eine Zahlungsliste vor und legt dem > Anwender in TAXDOO nur noch Entscheidungen und Ausnahmen vor. ### Ein beispielhafter Arbeitstag | Zeitpunkt | Tätigkeit des Agenten | Ergebnis für den Anwender | |---|---|---| | Früh morgens | Gmail, Outlook, Cloud, Shopify, JTL, plentyONE und weitere Quellen auf neue Belege prüfen | Neue Rechnungen und Gutschriften sind erkannt | | Danach | Quell-ID, Rechnungsnummer, SHA-256, Betrag, Währung, Länder und Dokumentversion prüfen | Dubletten und unvollständige Belege sind ausgesondert | | Importphase | Vollständige Ein- und Ausgangsrechnungen sowie freigegebene Fintech-Bankbewegungen idempotent importieren | TAXDOO enthält die neuen Belege und Bankdaten | | Verarbeitung | Document-AI-Workflows verfolgen und Fehler behandeln | Nur erfolgreich verarbeitete Dokumente gelten als abgeschlossen | | Abstimmung | Bank-, Rechnungs-, Bestell-, Zahlungsanbieter-, Retouren- und Settlement-Daten vergleichen | Eindeutige Zuordnungen und konkrete Ausnahmen liegen vor | | Zahlungsplanung | Bestätigte Fälligkeiten und Skontofristen aus den Quellsystemen priorisieren | Zahlungsliste mit heute fällig, Skonto möglich und gesperrt | | Übergabe | Eine kurze Tagesmappe bereitstellen | Der Anwender prüft Ausnahmen und gibt gewünschte Zahlungen in TAXDOO selbst frei | Der Agent löst niemals selbst eine Überweisung aus. Er übernimmt die zeitaufwendige Vorbereitung; Zahlungsprüfung und Autorisierung bleiben beim berechtigten Anwender in TAXDOO. ### Möglichkeiten für E-Commerce-Mandanten | Bereich | Was der Agent übernehmen kann | Strukturierter Bauplan | |---|---|---| | Täglicher Ablauf | Alle Quellen kontrollieren, Belege importieren, Aufgaben und Zahlungsliste priorisieren | `TAEGLICHE_RECHNUNGSSEKRETAERIN` | | Zahlungsmappe | Unbezahlte Eingangsrechnungen nach bestätigter Fälligkeit, Skonto und Sperrgrund gruppieren | `ZAHLUNGSMAPPE_VORBEREITEN` | | Fristen | Skontofristen und überfällige Rechnungen täglich überwachen | `SKONTO_UND_FAELLIGKEIT_UEBERWACHEN` | | Dubletten | Doppelte Rechnungen vor Import und Zahlungsfreigabe erkennen | `DOPPELTE_RECHNUNGEN_ERKENNEN` | | Fehlende Belege | Bankbelastungen oder Bestellungen ohne Rechnung finden und Nachfassentwurf erstellen | `FEHLENDE_LIEFERANTENRECHNUNGEN_NACHFASSEN` | | Multichannel | Ausgangsrechnungen aus mehreren Shops, ERP-Systemen und Marktplätzen synchronisieren | `MULTICHANNEL_AUSGANGSRECHNUNGEN_SYNCHRONISIEREN` | | Shopify | Bestellungen, Rechnungen, Retouren und Erstattungen ereignisgesteuert vorbereiten | `SHOPIFY_RECHNUNGEN_UND_ERSTATTUNGEN_VERARBEITEN` | | JTL-Wawi | Rechnungen über REST oder GraphQL inkrementell synchronisieren | `JTL_RECHNUNGEN_SYNCHRONISIEREN` | | plentyONE | Aufträge, Dokumente, Retouren und Zahlungen als Belegketten abstimmen | `PLENTYONE_AUFTRAEGE_DOKUMENTE_UND_ZAHLUNGEN_ABGLEICHEN` | | Marktplatzauszahlungen | Amazon-, eBay-, Shopify-Payments- oder PayPal-Auszahlungen in Verkäufe, Refunds und Gebühren auflösen | `MARKTPLATZAUSZAHLUNGEN_ABSTIMMEN` | | Retouren | Ursprungsauftrag, Retoure, Gutschrift und Erstattung verbinden | `RETOUREN_UND_GUTSCHRIFTEN_ABGLEICHEN` | | Korrekturen | Originalrechnung, Storno, Korrektur und Neubeleg als vollständige Kette prüfen | `STORNO_UND_KORREKTURKETTEN_PRUEFEN` | | Fintech-Banken | Vivid-, N26-, Wise- und andere Bankbewegungen dublettensicher übernehmen | `FINTECH_BANKDATEN_AUTOMATISIERT_IMPORTIEREN` | | Parsing | Bestätigte Zahlungen und Rechnungen gemeinsam zuordnen | `ZAHLUNG_RECHNUNG_PARSEN` | | Abweichungen | Gebühren, Rabatt, Skonto oder Währungsabweichung innerhalb eines bestätigten Grenzbetrags behandeln | `ZAHLUNG_RECHNUNG_MIT_ABWEICHUNG_PARSEN` | | Schnittstellenkontrolle | Fehlende Sequenzen, Summendifferenzen und ausgefallene Datenquellen erkennen | `SCHNITTSTELLEN_VOLLSTAENDIGKEIT_PRUEFEN` | | Steuerplausibilität | Versand-, Liefer- und Steuerland vor Ausgangsrechnungsimport vergleichen | `STEUERDATEN_PLAUSIBILISIEREN` | | Monatsabschluss | Fehlende Belege, offene Zuordnungen und Workflows als Ausnahmenliste zusammenstellen | `MONATSABSCHLUSS_VORBEREITEN` | ### Grenzen transparent erklären Eine gute Darstellung trennt drei Ebenen: 1. **Heute mit KiAgent möglich:** Belegkreise und offene Daten lesen, Rechnungen und BankCsv-Bewegungen importieren, Workflows verfolgen, bestätigte Datensätze parsen und Abweichungen innerhalb einer bestätigten `MaximaleAbweichung` verarbeiten. 2. **Leistung des externen Agenten:** Gmail, Shopify, JTL, plentyONE, Bankportale, Marktplätze und Dokumentordner lesen, eigenen sicheren Status führen, Daten normalisieren, Dubletten prüfen und Berichte erstellen. 3. **Möglicher späterer TAXDOO-Ausbau:** eigene Felder oder Endpunkte für Fälligkeit, Skonto, Zahlungsbereitschaft, globale Dublettensuche, Settlement-Positionen, Retourenketten und eine zentrale Aufgabenliste. ## Weiterführende Anleitung: vom Beispiel zum eigenen Agenten ### Phase 1: Quellen und Berechtigungen festlegen Der Anwender legt zunächst fest: - welche Mandanten, Shops, Firmen, Postfächer, Labels, Ordner und Bankkonten gelesen werden dürfen, - welches System je Information führend ist, - ob offizielle API, Webhook, Banking-Feed oder bereitgestellte Exportdatei verwendet wird, - welche Schritte nur lesen, automatisch importieren oder zwingend eine Bestätigung benötigen, - wer Zahlungen, Parsing und fachliche Ausnahmen freigeben darf. Empfohlen werden ausschließlich minimale Leserechte auf externe Quellen. Shop-, ERP-, E-Mail- und Banking-Zugangsdaten werden nicht an TAXDOO übermittelt. ### Phase 2: sicheren Agentenstatus einrichten Der Agent benötigt außerhalb von TAXDOO einen mandantengetrennten Status für: - letzte erfolgreiche Synchronisationszeit je Quelle, - externe Order-, Rechnungs-, Dokument-, Payout- und Transaktions-IDs, - Datei-SHA-256 und kanonische Beleg- beziehungsweise Bewegungsfingerabdrücke, - verwendete Idempotenzschlüssel und unveränderte Requests, - zurückgegebene Workflow-IDs und Endstatus, - offene Ausnahmen und bereits angezeigte Warnungen. Ein Dateiname oder eine Rechnungsnummer allein genügt nicht als Dublettenprüfung. ### Phase 3: zunächst lesend testen Vor dem ersten Import soll der Agent einen vollständigen Probelauf ohne Schreiboperationen ausführen: 1. `/ki-agent/anleitung.json?Umfang=vollstaendig` und `/ki-agent/belegkreise` lesen, 2. externe Quellen mit kleinem Zeitraum abrufen, 3. Feldzuordnung und Dublettenfingerabdrücke zeigen, 4. erwartete Importe, Ausnahmen und Bestätigungspunkte darstellen, 5. Summen, Währungen und Dokumentzahlen abstimmen, 6. erst nach Abnahme den ersten Import freigeben. ### Phase 4: kontrolliert automatisieren Nach erfolgreichem Probelauf dürfen nur vollständig konfigurierte Standardfälle automatisch importiert werden. Der Agent stoppt bei: - fehlenden Pflichtangaben, - widersprüchlichen Ländern, Währungen oder Beträgen, - neuer oder geänderter Lieferanten-IBAN, - Dublettenverdacht, - mehreren plausiblen Zuordnungen, - unklarer Retoure, Gutschrift oder Stornokette, - überschrittener `MaximaleAbweichung`, - abgelaufener oder entzogener Berechtigung. ### Phase 5: Tagesmappe und Monatsabschluss Der laufende Betrieb sollte zwei feste Ausgaben erzeugen: - täglich eine kurze operative Mappe mit neuen Importen, Zahlungsprioritäten, fehlenden Belegen und Entscheidungen, - monatlich eine Abschlussmappe mit Summenabstimmung, offenen Workflows, Schnittstellendifferenzen und noch ungeklärten Zuordnungen. ### Komplettes Promptbeispiel für einen E-Commerce-Mandanten ```text Ich betreibe einen E-Commerce-Handel mit , verkaufe zusätzlich über , verwende und führe Konten bei . Lies zuerst die vollständige TAXDOO-KiAgent-Anleitung und öffne danach die Baupläne: - TAEGLICHE_RECHNUNGSSEKRETAERIN - ZAHLUNGSMAPPE_VORBEREITEN - DOPPELTE_RECHNUNGEN_ERKENNEN - MULTICHANNEL_AUSGANGSRECHNUNGEN_SYNCHRONISIEREN - MARKTPLATZAUSZAHLUNGEN_ABSTIMMEN - RETOUREN_UND_GUTSCHRIFTEN_ABGLEICHEN - FINTECH_BANKDATEN_AUTOMATISIERT_IMPORTIEREN - MONATSABSCHLUSS_VORBEREITEN Entwirf einen konkreten täglichen Ablauf: 1. neue Rechnungen und Gutschriften aus allen freigegebenen Quellen lesen, 2. Dubletten und unvollständige Belege erkennen, 3. Ein- und Ausgangsrechnungen sicher und idempotent importieren, 4. Document-AI-Ergebnisse verfolgen, 5. Bank-, Rechnungs-, Bestell- und Zahlungssystemdaten zuordnen, 6. Marktplatzauszahlungen einschließlich Gebühren und Erstattungen abstimmen, 7. bestätigte Fälligkeiten und Skontofristen priorisieren, 8. eine vom Anwender in TAXDOO freizugebende Zahlungsmappe erstellen, 9. Retouren, Gutschriften, Stornos und Korrekturen als Belegketten prüfen, 10. täglich Schnittstellendifferenzen und monatlich Abschlussausnahmen melden. Trenne klar zwischen Funktionen der TAXDOO-KiAgent-API und Fähigkeiten meines externen Agenten. Nenne benötigte Berechtigungen, Datenfelder, Bestätigungspunkte, Idempotenz, Dublettenlogik, Fehlerbehandlung und Akzeptanztests. Stelle zuerst nur die Angaben als Fragen zusammen, die für meine Einrichtung fehlen. Führe noch keine Anmeldung, keinen Import, kein Parsing und keine Zahlung aus. ``` ### Systemspezifische technische Möglichkeiten - Shopify unterstützt Webhooks als nahezu ereignisnahen Auslöser. Signatur und Webhook-ID müssen geprüft werden. Die GraphQL Admin API stellt unter anderem Bestell-, Finanz-, Fulfillment-, Retouren- und Refundstatus bereit: und . - JTL-Wawi stellt in Version 2.0 REST und GraphQL für ERP-Daten einschließlich Rechnungen bereit. Cloud und On-Premise besitzen unterschiedliche Authentifizierungswege: und . - plentyONE bietet REST-Bereiche für Order, Document, Payment und Returns sowie konfigurierbare Webhook-Abonnements: und . - Amazon SP-API stellt Orders, Transaktionen und Settlement-, Steuer- und Retourenberichte bereit: . - eBay stellt über die Finances API Auszahlungen, Gebühren, Erstattungen und Order-Bezüge bereit: . ## Agenten-Baupläne und kopierbare Prompts Jeder Eintrag in `Anwendungsfaelle` enthält einen `AgentenBauplan`. Dieser liefert nicht nur eine Funktionsbeschreibung, sondern die Bausteine für eine reale Agentenlösung: - benötigte Fähigkeiten des externen Agenten, - tatsächlich verwendete TAXDOO-Endpunkte, - verbindliche Bestätigungspunkte, - Testszenarien, - Vertiefungslinks, - je eine kopierbare Promptvorlage für `Beratung`, `Einrichtung` und `Betrieb`. Ein einzelner Bauplan kann ohne Authentifizierung und ohne Datenbankzugriff gezielt abgerufen werden: ```http GET /ki-agent/anleitung/anwendungsfaelle/{Code} ``` Beispiel in der veröffentlichten Alpha-Umgebung: ```text https://api.acc-digital.de/importer/alpha/ki-agent/anleitung/anwendungsfaelle/BANKBELEG_AUS_EMAIL ``` Die drei Promptarten haben unterschiedliche Aufgaben: | Promptart | Geeignet für | Verhalten | |---|---|---| | `Beratung` | Idee und Lösungsentwurf | Erklärt Architektur, Zugriffe, Datenfluss, Grenzen und offene Fragen; führt nichts aus | | `Einrichtung` | Konkrete Agentenkonfiguration | Fragt fehlende Angaben ab und erstellt Konfiguration, Feldzuordnung, Fehlerstrategie und Akzeptanztests | | `Betrieb` | Laufender Agent | Gibt die verbindliche Reihenfolge, Bestätigungen, Idempotenz und Ausnahmebehandlung vor | Eine KI, die diese Anleitung verarbeitet, soll bei einer allgemeinen Frage: 1. passende Einträge aus `AnwendungsfaelleKurzuebersicht` auswählen, 2. den jeweiligen `DetailsEndpoint` öffnen, 3. Nutzen, Voraussetzungen und Bestätigungspunkte erklären, 4. mindestens den Beratungsprompt kopierbar darstellen, 5. bei Umsetzungsinteresse zusätzlich Einrichtungs- und Betriebsprompt anbieten. ### Vollständiges Beispiel: Gmail-Rechnungsagent Ein eigener Agent kann ein ausdrücklich freigegebenes Gmail-Konto oder Label lesen, Rechnungsanhänge untersuchen, sie mit offenen TAXDOO-Bankdaten abgleichen und nur eindeutige Treffer importieren. Gmail ist dabei eine Fähigkeit des externen Agenten; TAXDOO greift nicht selbst auf das Postfach zu. Benötigte Fähigkeiten: - lesender Google-OAuth-Zugriff mit möglichst kleinen Berechtigungen, - Suche nach freigegebenem Label, Absender, Zeitraum und Verarbeitungsstatus, - sicherer Download und SHA-256-Prüfung unterstützter Anhänge, - Dokumentanalyse und Bewertung mehrerer Zuordnungskriterien, - eigener mandantengetrennter Verarbeitungsstatus, - Aufrufe von `/ki-agent/belegkreise`, `/ki-agent/bankdaten/offen`, `/ki-agent/import` und `/ki-agent/workflows/status`. Bestätigungspunkte: - Der Anwender gibt Gmail-Konto, Suchbereich und zulässige Absender frei. - Der Anwender legt fest, ab welcher Eindeutigkeit automatisch importiert wird. - Mehrdeutige Treffer und widersprüchliche Angaben bleiben offene Aufgaben. - Eine Nachricht wird erst nach bestätigtem Verarbeitungserfolg gemäß den eingerichteten Regeln gekennzeichnet oder verschoben. Kopierbarer Beratungsprompt: ```text Ich möchte einen eigenen KI-Agenten aufbauen, der Rechnungen aus meinem Google-Gmail-Konto passenden offenen Bankdaten in TAXDOO zuordnet. Lies zuerst die vollständige Anleitung unter https://api.acc-digital.de/importer/alpha/ki-agent/anleitung/markdown und danach den Bauplan unter https://api.acc-digital.de/importer/alpha/ki-agent/anleitung/anwendungsfaelle/BANKBELEG_AUS_EMAIL. Entwirf eine konkrete Lösung für diesen Rahmen: - Gmail: nur das freigegebene Konto und das Label „Rechnungen“ - Anhänge: PDF, PNG, JPG, JPEG oder TIFF - Abgleich: Betrag, Datum, Rechnungsnummer, Empfänger oder Lieferant, IBAN und Verwendungszweck mit /ki-agent/bankdaten/offen - Import: nur eindeutige Treffer über /ki-agent/import, mit OpenBankDataId, Datei-SHA-256 und stabilem Idempotenzschlüssel - Status: Workflows über /ki-agent/workflows/status bis zum Endstatus verfolgen - Ausnahmen: mehrere Treffer, fehlende Pflichtangaben und ungeeignete Dateien dem Anwender verständlich vorlegen - Gmail-Nachbearbeitung: erst nach bestätigtem Erfolg kennzeichnen Beschreibe Architektur, minimale Google-OAuth-Berechtigungen, Komponenten, Datenfluss, Geheimnisverwaltung, sicheren Verarbeitungsstatus, Bestätigungspunkte, Fehler- und Retry-Strategie sowie Akzeptanztests. Unterscheide klar zwischen Gmail-Funktionen des externen Agenten und TAXDOO-Funktionen. Frage danach nur Angaben ab, die für die Einrichtung noch fehlen. Führe noch keine Aktionen und keine schreibenden API-Aufrufe aus. ``` ### Promptkatalog für alle Anwendungsfälle Die folgenden kurzen Beratungsprompts eignen sich als Einstieg. Der Detailendpunkt des Codes liefert jeweils zusätzlich die ausführlichen Prompts für Beratung, Einrichtung und Betrieb. | Code | Kopierbarer Einstiegsprompt | |---|---| | `BANKBELEG_AUS_EMAIL` | „Zeige mir anhand des Bauplans `BANKBELEG_AUS_EMAIL`, wie ein eigener Agent Rechnungen aus einem freigegebenen E-Mail-Bereich sicher offenen Bankdaten zuordnet. Nenne Zugriffe, Bestätigungen, Endpunkte, Ausnahmen und Tests; führe nichts aus.“ | | `BANKBELEG_AUS_CLOUD` | „Entwirf anhand des Bauplans `BANKBELEG_AUS_CLOUD` einen Agenten für einen freigegebenen Cloud-Eingangsordner. Erkläre Dateistatus, SHA-256, Bankabgleich, Freigabe, Import und Archivierung.“ | | `FEHLENDE_BANKBELEGE_ERMITTELN` | „Plane anhand des Bauplans `FEHLENDE_BANKBELEGE_ERMITTELN` einen lesenden Agenten, der fehlende, eindeutige und mehrdeutige Bankbelege als priorisierte Aufgabenliste darstellt.“ | | `BANKDATEN_MIT_DATEN_IDS_ANREICHERN` | „Erkläre anhand des Bauplans `BANKDATEN_MIT_DATEN_IDS_ANREICHERN`, wie bestätigte externe Kennungen sicher offenen Bankdaten zugeordnet werden und welche Nutzerfreigabe nötig ist.“ | | `UNBEZAHLTE_EINGANGSRECHNUNG_UND_UEBERWEISUNG` | „Entwirf anhand des Bauplans `UNBEZAHLTE_EINGANGSRECHNUNG_UND_UEBERWEISUNG` einen Agenten, der unbezahlte Rechnungen bereitstellt, aber niemals selbst eine Überweisung auslöst oder autorisiert.“ | | `AUSGANGSRECHNUNG_AUS_QUELLSYSTEM` | „Plane anhand des Bauplans `AUSGANGSRECHNUNG_AUS_QUELLSYSTEM` einen sicheren Import bestätigter Ausgangsrechnungen aus ERP oder Shop einschließlich Länderklärung und Tests.“ | | `OFFENE_AUSGANGSRECHNUNGEN_PRUEFEN` | „Zeige anhand des Bauplans `OFFENE_AUSGANGSRECHNUNGEN_PRUEFEN`, wie ein lesender Agent offene Ausgangsrechnungen prüft, filtert und verständlich priorisiert.“ | | `ZAHLUNGSSYSTEM_DATEN_ZUORDNEN` | „Entwirf anhand des Bauplans `ZAHLUNGSSYSTEM_DATEN_ZUORDNEN` einen Abgleich von Zahlungssystem-, Rechnungs- und Bestelldaten mit eindeutigen und mehrdeutigen Ergebnissen.“ | | `ZAHLUNG_RECHNUNG_PARSEN` | „Erkläre anhand des Bauplans `ZAHLUNG_RECHNUNG_PARSEN`, wie eine bestätigte Zahlung und Rechnung gemeinsam geparst werden. Zeige die konkreten IDs, Bestätigung, Sicherheitsgrenzen und Fehlerfälle.“ | | `ZAHLUNG_RECHNUNG_MIT_ABWEICHUNG_PARSEN` | „Entwirf anhand des Bauplans `ZAHLUNG_RECHNUNG_MIT_ABWEICHUNG_PARSEN` einen sicheren Ablauf für bestätigte Abweichungsart und positive MaximaleAbweichung. Der Agent darf den Grenzbetrag nie selbst erhöhen.“ | | `KASSEN_UND_BARBELEGE_AUS_SCANORDNER` | „Plane anhand des Bauplans `KASSEN_UND_BARBELEGE_AUS_SCANORDNER` einen Agenten für freigegebene Scans oder Fotos mit Belegkreisprüfung, Ausnahmebehandlung und sicherem Import.“ | | `BANKCSV_DATEN_IMPORTIEREN` | „Zeige anhand des Bauplans `BANKCSV_DATEN_IMPORTIEREN`, wie Bankdaten aus einer freigegebenen Quelle validiert, auf die Importfelder abgebildet und ohne OpenBankDataId importiert werden.“ | | `FINTECH_BANKDATEN_AUTOMATISIERT_IMPORTIEREN` | „Entwirf anhand des Bauplans `FINTECH_BANKDATEN_AUTOMATISIERT_IMPORTIEREN` einen lesenden Agenten für Vivid, N26, Wise oder eine andere Fintech-Bank. Bevorzuge offizielle APIs oder Banking-Feeds, verarbeite andernfalls freigegebene CSV-, MT940- oder CAMT-Exporte und verhindere Dubletten mit Transaktions-ID, Zeilenfingerabdruck, Datei-SHA-256 und stabilem Idempotenzschlüssel.“ | | `TAEGLICHE_BUCHHALTUNGSUEBERSICHT` | „Entwirf anhand des Bauplans `TAEGLICHE_BUCHHALTUNGSUEBERSICHT` einen lesenden Tagesbericht mit offenen Aufgaben, Zuordnungsvorschlägen, fehlenden Belegen und Workflowproblemen.“ | | `TAEGLICHE_RECHNUNGSSEKRETAERIN` | „Plane anhand des Bauplans `TAEGLICHE_RECHNUNGSSEKRETAERIN` meinen vollständigen täglichen Ablauf von neuen Belegen bis zur vom Anwender freizugebenden Zahlungs- und Ausnahmenmappe.“ | | `ZAHLUNGSMAPPE_VORBEREITEN` | „Zeige anhand des Bauplans `ZAHLUNGSMAPPE_VORBEREITEN`, wie unbezahlte Eingangsrechnungen nach bestätigter Fälligkeit, Skonto, Lieferant und Sperrgrund priorisiert werden, ohne eine Zahlung auszulösen.“ | | `SKONTO_UND_FAELLIGKEIT_UEBERWACHEN` | „Entwirf anhand des Bauplans `SKONTO_UND_FAELLIGKEIT_UEBERWACHEN` eine tägliche Kontrolle, die Skontovorteile und kritische Fälligkeiten aus bestätigten Quellsystemdaten meldet.“ | | `DOPPELTE_RECHNUNGEN_ERKENNEN` | „Erstelle anhand des Bauplans `DOPPELTE_RECHNUNGEN_ERKENNEN` eine mehrstufige Dublettenprüfung vor Import und Zahlung mit Quell-ID, Rechnungsfingerabdruck, Datei-SHA-256 und Importjournal.“ | | `FEHLENDE_LIEFERANTENRECHNUNGEN_NACHFASSEN` | „Plane anhand des Bauplans `FEHLENDE_LIEFERANTENRECHNUNGEN_NACHFASSEN` einen Agenten, der Bankbelastungen und Bestellungen ohne Beleg erkennt, Quellen durchsucht und einen freizugebenden Lieferanten-E-Mail-Entwurf erstellt.“ | | `MULTICHANNEL_AUSGANGSRECHNUNGEN_SYNCHRONISIEREN` | „Entwirf anhand des Bauplans `MULTICHANNEL_AUSGANGSRECHNUNGEN_SYNCHRONISIEREN` eine gemeinsame, dublettensichere Rechnungssynchronisation für mehrere Shops, ERP-Systeme und Marktplätze.“ | | `SHOPIFY_RECHNUNGEN_UND_ERSTATTUNGEN_VERARBEITEN` | „Zeige anhand des Bauplans `SHOPIFY_RECHNUNGEN_UND_ERSTATTUNGEN_VERARBEITEN`, wie signierte Shopify-Webhooks, Finanzstatus, Retouren und Refunds zu korrekten Belegereignissen werden.“ | | `JTL_RECHNUNGEN_SYNCHRONISIEREN` | „Plane anhand des Bauplans `JTL_RECHNUNGEN_SYNCHRONISIEREN` eine inkrementelle JTL-Cloud- oder On-Premise-Rechnungssynchronisation mit Firmen- und Dublettentrennung.“ | | `PLENTYONE_AUFTRAEGE_DOKUMENTE_UND_ZAHLUNGEN_ABGLEICHEN` | „Entwirf anhand des Bauplans `PLENTYONE_AUFTRAEGE_DOKUMENTE_UND_ZAHLUNGEN_ABGLEICHEN` eine plentyONE-Integration für Aufträge, Dokumente, Retouren, Gutschriften und Zahlungen.“ | | `MARKTPLATZAUSZAHLUNGEN_ABSTIMMEN` | „Zeige anhand des Bauplans `MARKTPLATZAUSZAHLUNGEN_ABSTIMMEN`, wie Amazon-, eBay- oder Zahlungsanbieter-Sammelauszahlungen in Verkäufe, Refunds, Gebühren und bestätigte Abweichungen aufgelöst werden.“ | | `RETOUREN_UND_GUTSCHRIFTEN_ABGLEICHEN` | „Plane anhand des Bauplans `RETOUREN_UND_GUTSCHRIFTEN_ABGLEICHEN` eine nachvollziehbare Kette aus Originalauftrag, Retoure, Gutschrift und Erstattung einschließlich Teilretouren.“ | | `STORNO_UND_KORREKTURKETTEN_PRUEFEN` | „Erkläre anhand des Bauplans `STORNO_UND_KORREKTURKETTEN_PRUEFEN`, wie Originalrechnung, Storno, Korrektur und Neubeleg vor dem Import vollständig geprüft werden.“ | | `MONATSABSCHLUSS_VORBEREITEN` | „Entwirf anhand des Bauplans `MONATSABSCHLUSS_VORBEREITEN` eine priorisierte Abschlussmappe mit fehlenden Belegen, offenen Zuordnungen, Workflows und Schnittstellendifferenzen.“ | | `SCHNITTSTELLEN_VOLLSTAENDIGKEIT_PRUEFEN` | „Zeige anhand des Bauplans `SCHNITTSTELLEN_VOLLSTAENDIGKEIT_PRUEFEN`, wie Anzahl, Summen, Sequenzen und letzte erfolgreiche Kontrollpunkte zwischen Quelle, Importjournal und TAXDOO überwacht werden.“ | | `STEUERDATEN_PLAUSIBILISIEREN` | „Plane anhand des Bauplans `STEUERDATEN_PLAUSIBILISIEREN` eine Prüfung bestätigter Versand-, Liefer- und Steuerländer sowie Käufer-USt-ID, ohne eine steuerliche Entscheidung zu erfinden.“ | Weitere maschinenlesbare Details stehen jeweils unter `/ki-agent/anleitung/anwendungsfaelle/{Code}`. Die dort gelieferte `Vertiefung.DetailsUrl` ist bereits eine vollständige, zur aktuellen Umgebung passende URL. ## Verantwortlichkeit Der KI-Agent unterstützt den Anwender bei Auswahl, Prüfung und Übertragung der Daten. Die Verantwortung für Richtigkeit und Vollständigkeit der importierten Daten bleibt beim Anwender. Insbesondere Länder, Steuerangaben, USt-IDs, Bankdatensätze und andere fachliche Werte dürfen nicht vom Agenten erfunden werden. ## Einrichtung prüfen Die allgemeine Anleitung kann ohne Zugangsdaten abgerufen werden. Optional kann der Agent prüfen, ob Mandant und API-Key gemeinsam gültig sind und mindestens ein unterstützter Belegkreis eingerichtet ist: ```http GET /ki-agent/anleitung.json?Mandant= Authorization: Bearer ``` Der API-Key soll ausschließlich im `Authorization`-Header stehen. Er gehört nicht in URLs, Chatnachrichten, Importzusammenfassungen oder Protokolle. Eine Mandantennummer allein löst keine Datenbankauskunft aus. Bei einer fehlgeschlagenen Authentifizierung unterscheidet die API aus Sicherheitsgründen nicht zwischen: - unbekanntem Mandanten, - nicht eingerichtetem API-Key, - falschem API-Key, - API-Key eines anderen Mandanten. Die möglichen Einrichtungszustände sind: | Status | Bedeutung | Aktion | |---|---|---| | `NichtGeprueft` | Mandant oder Bearer-API-Key fehlt | Fehlende Voraussetzung sicher konfigurieren | | `EinrichtungNichtBestaetigt` | Mandant und API-Key konnten nicht gemeinsam bestätigt werden | Einrichtung in TAXDOO prüfen | | `KeineBelegkreise` | Authentifizierung ist gültig, aber es fehlt ein unterstützter Belegkreis | Belegkreis in TAXDOO einrichten | | `Bereit` | Authentifizierung und Belegkreise sind verwendbar | Belegkreise abrufen | | `PruefungTechnischFehlgeschlagen` | Die optionale Prüfung konnte technisch nicht abgeschlossen werden | Später wiederholen oder Support kontaktieren | Ein Import darf erst bei Status `Bereit` vorbereitet werden. ## Authentifizierung geschützter Endpunkte Empfohlenes Format: ```http Authorization: Bearer X-Mandant: ``` API-Key und Mandant werden immer gemeinsam validiert. Geschützte Antworten werden auf den authentifizierten Mandanten begrenzt. ## Mögliche Arbeitsabläufe `GET /ki-agent/anleitung.json` liefert in `AnwendungsfaelleKurzuebersicht` kompakte Vorschläge mit direkten Detail-URLs. Der vollständige Katalog mit dem Feld `Anwendungsfaelle` steht unter `GET /ki-agent/anleitung.json?Umfang=vollstaendig` bereit. Die strukturierten Workflow-Rezepte helfen einem externen KI-Agenten, dem Anwender konkrete Verbesserungen für seinen Arbeitsalltag vorzuschlagen. Dabei gilt immer: - TAXDOO stellt Belegkreise, offene Bankdaten, offene Ein- und Ausgangsrechnungen, offene Zahlungssystemdaten, Import und Document AI bereit. - Der vom Anwender betriebene Agent greift mit dessen Zustimmung auf E-Mail, Cloud, ERP oder lokale Ordner zu. - TAXDOO erhält nur bestätigte Importdaten und Dokumente, niemals Zugangsdaten der externen Systeme. - Der sichere Standard ist `NachAnwenderbestaetigung`. - Fähigkeiten des externen Agenten dürfen nicht als eingebaute Funktionen von TAXDOO dargestellt werden. ### Rechnungen aus E-Mails offenen Bankdaten zuordnen Ein externer Agent kann: 1. offene Bankdaten über die KiAgent-API abrufen, 2. einen freigegebenen Bereich des E-Mail-Postfachs durchsuchen, 3. Rechnungsanhänge anhand von Betrag, Datum, Rechnungsnummer, Empfänger, IBAN, Verwendungszweck und Währung vergleichen, 4. dem Anwender einen Zuordnungsvorschlag zeigen, 5. nach Bestätigung das Dokument mit der gelieferten `OpenBankDataId` importieren, 6. anschließend den Document-AI-Status verfolgen. TAXDOO greift nicht selbst auf das E-Mail-Postfach zu. E-Mail-Zugangsdaten werden nicht an TAXDOO übertragen. E-Mails dürfen nur nach gesonderter Freigabe und erst nach erfolgreichem Abschluss markiert oder verschoben werden. Sammelzahlungen, Teilzahlungen, Gebühren, Währungsabweichungen oder mehrere gleich plausible Rechnungen benötigen immer eine manuelle Entscheidung. ### Dokumente aus einem Cloud-Ordner offenen Bankdaten zuordnen Geeignete externe Quellen sind beispielsweise: - Google Drive - Microsoft OneDrive - SharePoint - Dropbox - iCloud Drive - lokaler synchronisierter Ordner - Netzlaufwerk Der Agent erkennt neue Dateien im ausdrücklich freigegebenen Eingangsordner, prüft Dateityp, Größe und SHA-256, analysiert das Dokument und schlägt einen passenden offenen Bankeintrag vor. Nach Bestätigung erfolgt der Import mit `OpenBankDataId`. Der Agent sollte seinen Verarbeitungsstand aus externer Datei-ID, Änderungsstand und SHA-256 bilden. Ein Dateiname allein ist kein zuverlässiger Nachweis. Verschieben oder Archivieren in der externen Quelle benötigt eine eigene Freigabe. ### Fehlende Bankbelege ermitteln Der Agent kann offene Bankdaten regelmäßig mit freigegebenen E-Mail- und Dokumentquellen vergleichen und eine Aufgabenliste erstellen: - eindeutige Zuordnungsvorschläge, - mehrdeutige Zuordnungen, - weiterhin fehlende Dokumente, - Alter des offenen Bankeintrags, - bereits durchsuchte Quellen, - empfohlene nächste Aktion. Dieser Workflow sollte standardmäßig `NurVorschlagen` verwenden. Ein ähnlicher Betrag allein reicht nicht für eine Zuordnung. ### Offene Bankdaten mit fachlichen Kennungen anreichern Ein externer Agent kann einem weiterhin unbearbeiteten normalen Bankdatensatz eine bestätigte Order-, Rechnungs- oder Transaktionsnummer hinzufügen. Dazu übernimmt er `Id`, `SchnittstelleId` und eine zulässige `TypId` aus derselben aktuellen Antwort von `/ki-agent/bankdaten/offen`, zeigt Bankdatensatz, Typ und Wert dem Anwender und ruft erst nach Bestätigung `POST /ki-agent/bankdaten/daten-ids` auf. Die Anreicherung verändert weder `IstBearbeitet` noch `Parsed_id` oder `GebuchtId`. Sie verbessert lediglich die Grundlage für einen späteren Abgleich. Die hinzugefügte Kennung ist allein kein Zahlungsnachweis. ### Zahlungssystemdaten Rechnungen und Bestellungen zuordnen Der Agent kann ungeparste und unbearbeitete Zahlungssystemdaten abrufen und die eingebetteten `DatenIds` mit einer vom Anwender freigegebenen Rechnungs-, Bestell- oder Transaktionsquelle vergleichen. Fachliche Typen wie `Rechnungsnummer`, `OrderID` oder `Transaktionsnummer` werden von TAXDOO mitgeliefert und dürfen nicht aus dem Kennungswert geraten werden. Mehrere Werte desselben Typs bleiben erhalten. Der Agent stellt eindeutige, mehrdeutige und fehlende Treffer getrennt dar. Eine übereinstimmende Daten-ID ist ein Zuordnungshinweis, aber allein kein verbindlicher Nachweis, dass eine bestimmte Rechnung mit der Zahlung beglichen wurde. Dieser Workflow ist daher standardmäßig `NurVorschlagen`. Hat der Anwender eine Zahlung und die zugehörige Rechnung oder Bestellung fachlich bestätigt, kann der Agent die Auswahl anschließend über `POST /ki-agent/verarbeitete-daten/parsen` verbindlich gemeinsam zuordnen. Geht die Auswahl nicht auf null auf, steht dafür der gesondert zu bestätigende Workflow mit Abweichung und optionalem Grenzbetrag `MaximaleAbweichung` bereit. ### Bestätigte Datensätze gemeinsam parsen Ein externer Agent kann dem Anwender eine Liste ungeparster Datensätze zur gemeinsamen Zuordnung vorschlagen. Vor dem datenverändernden Aufruf muss der Agent die ausgewählten Datensätze verständlich darstellen und die ausdrückliche Bestätigung des Anwenders einholen. Der Agent übermittelt ausschließlich die bestätigten `VerarbeiteteDatenIds`. `ParsedId` und Parserregel werden nicht vorgegeben. TAXDOO prüft die gesamte Auswahl und speichert sie ausschließlich über den zentralen Parsing-Service mit der Parserregel `KIAgent`. Bei einer ungültigen Auswahl liefert die API `PARSING_REJECTED` und übernimmt die fachliche Validierungsmeldung in `ErrorMessage`. Der Agent darf diese Prüfung nicht umgehen oder die Auswahl ohne erneute Bestätigung verändern. ### Bestätigte Datensätze mit Abweichung parsen Geht eine bestätigte Auswahl in Summe nicht auf 0 auf, kann der Anwender die automatisch ermittelte Abweichung erfassen lassen. Zusätzlich zu den `VerarbeiteteDatenIds` bestätigt er: - genau eine `SelectedVerarbeiteteDatenId` aus derselben Auswahl, - einen `SteuerTypDTO`, - einen `FDPositionTypDTO`, - nur bei einer außergewöhnlichen steuerlichen Besonderheit optional eine `SteuerInfo`, - optional einen positiven Grenzbetrag `MaximaleAbweichung`. Die ausgewählte ID dient dem zentralen Abweichungsservice zur fachlichen Bestimmung der Abweichungsart. Betrag, Datum, Text und Steuerbetrag werden nicht vom Agenten ermittelt oder übermittelt, sondern innerhalb des zentralen Abweichungsservice automatisch bestimmt. `SteuerInfo` ist kein Standardfeld. Der Agent darf es nur übernehmen, wenn der Anwender ausdrücklich eine außergewöhnliche, für die Buchhaltung wichtige steuerliche Besonderheit mitteilt. Er darf den Inhalt weder erfinden noch aus anderen Daten ableiten. Vor der Bestätigung muss der Agent darauf hinweisen, dass ein gefülltes Feld zur vollständig manuellen Bearbeitung des Vorgangs führt. Im Normalfall wird `SteuerInfo` weggelassen oder `null` übermittelt. Überschreitet die automatisch ermittelte absolute Abweichung den optionalen Grenzbetrag, lehnt TAXDOO die gesamte Speicherung ab. Der Agent darf den Grenzbetrag anschließend nicht ohne erneute Anwenderbestätigung erhöhen. ### Unbezahlte Eingangsrechnungen und Überweisungsvorbereitung Ein externer Agent kann unbezahlte Lieferantenrechnungen aus E-Mail, Drive, ERP, Rechnungseingang oder Scan-Ordner bereitstellen. Voraussetzungen: - ein von `/ki-agent/belegkreise` gelieferter Belegkreis vom Typ `Lieferant`, der in TAXDOO als Eingangsrechnung eingerichtet ist, - bestätigter Status, dass die Rechnung noch nicht bezahlt wurde, - bestätigter Betrag und Rechnungsdatum, - Rechnungsnummer oder geeigneter Verwendungszweck, - bestätigter Lieferantenname, - bestätigte Empfänger-IBAN im Feld `AuftraggeberId`, - eingerichtetes integriertes Banking in TAXDOO für die spätere Zahlung. Empfohlener Ablauf: 1. Der Agent erkennt eine neue Rechnung in einer freigegebenen Quelle. 2. Er prüft anhand seines Verarbeitungsstands, ob sie bereits importiert wurde. 3. Er erfasst Betrag, Datum, Rechnungsnummer, Lieferant und IBAN als Vorschlag. 4. Der Anwender bestätigt, dass die Rechnung unbezahlt und sachlich korrekt ist, sowie Dokument, Betrag, Lieferant und IBAN. 5. Der Agent importiert sie in den Lieferanten-/Eingangsrechnungs-Belegkreis. 6. Der Agent verfolgt die Document-AI-Verarbeitung. 7. TAXDOO stellt die Rechnung anschließend als offenen Posten bereit. 8. Der Nutzer wählt in TAXDOO den offenen Posten und das gewünschte Banking-Konto aus. 9. TAXDOO bereitet nach dieser Nutzerauswahl einen Zahlungsauftrag vor. 10. Ein berechtigter Nutzer prüft Empfänger, IBAN, Betrag und Verwendungszweck erneut und autorisiert die Zahlung über das im integrierten Banking vorgesehene Freigabeverfahren. Der externe Agent darf niemals selbst eine Überweisung auslösen oder autorisieren. Die KiAgent-API besitzt keinen Endpoint zur Zahlungsfreigabe. Besonders zu prüfen sind: - geänderte Bankverbindungen auf Rechnungen, - abweichende Zahlungsempfänger, - Skonti, - Teil- oder Sammelzahlungen, - Gutschriften, - Fremdwährungen, - bereits außerhalb von TAXDOO ausgeführte Zahlungen. Eine geänderte IBAN sollte über einen unabhängigen, bereits bekannten Kontaktweg beim Lieferanten verifiziert werden. Zahlungsdaten dürfen nicht allein aus unbekannten Links oder unbestätigtem E-Mail-Text übernommen werden. ### Ausgangsrechnungen aus ERP, Shop oder Drive Ein Agent kann neue Ausgangsrechnungen aus einem freigegebenen Quellsystem erkennen und importieren. Zusätzlich zu Betrag, Datum und Text müssen Versandland, Lieferland und Steuerland fachlich geklärt sein. Eine Käufer-USt-ID darf nicht erfunden werden und kann abhängig vom Geschäftsvorfall erforderlich sein. ### Kassen- und Barbelege aus einem Scan-Ordner Fotografierte oder gescannte Belege können aus einem Eingangsordner erkannt werden. Der Agent prüft die Datei, extrahiert Betrag, Datum und Text als Vorschlag und fragt fehlende Angaben beim Anwender ab. Nach Bestätigung erfolgt der Import in einen Belegkreis vom Typ `Kasse` oder `Bar`. Unlesbare oder unvollständige Belege dürfen nicht automatisch importiert werden. ### Tägliche Buchhaltungsübersicht Ein Agent kann regelmäßig zusammenfassen: - Anzahl und Alter offener Bankeinträge, - eindeutige und mehrdeutige Dokumentvorschläge, - weiterhin fehlende Belege, - Status der vom Agenten selbst gestarteten Document-AI-Workflows, - fehlgeschlagene Workflows und empfohlene nächste Schritte, - unbezahlte Eingangsrechnungen aus der freigegebenen externen Quelle. Die KiAgent-API stellt keinen globalen Verlauf aller Agentenaktionen bereit. Der Agent muss seinen eigenen Verarbeitungsstatus und die von ihm erhaltenen Workflow-IDs sicher und mandantengetrennt führen. ### Fintech-Bankbewegungen ohne automatischen Bankabruf übernehmen Der Anwendungsfall `FINTECH_BANKDATEN_AUTOMATISIERT_IMPORTIEREN` richtet sich an Banken und Zahlungsdienste, die nicht über den üblichen automatischen Bankabruf des Buchhaltungssystems erreichbar sind. Beispiele sind Vivid, N26, Wise sowie weitere deutsche und internationale Fintech-Konten. Der externe Agent verwendet in dieser Reihenfolge: 1. eine offiziell angebotene lesende API, 2. einen offiziell angebotenen Banking- oder Accounting-Feed, 3. einen automatisch vom Banksystem bereitgestellten strukturierten Export, 4. einen durch den Anwender freigegebenen CSV-, MT940- oder CAMT-Export. Eine Anmeldung am Webportal darf nur automatisiert werden, wenn die Bank dies offiziell unterstützt und der Anwender es ausdrücklich freigegeben hat. Der Agent darf Zwei-Faktor-Authentifizierung, CAPTCHA, Gerätefreigabe oder andere Schutzmaßnahmen niemals umgehen. Wo nur ein manueller Download angeboten wird, kann der Agent den Download assistieren und anschließend die bereitgestellte Datei automatisch weiterverarbeiten. Nach den veröffentlichten Anbieterinformationen stehen beispielsweise folgende Exportwege zur Verfügung: - Vivid Business: Kontoauszüge als PDF, MT940 und CSV, - N26: Kontoaktivitätsberichte für einen frei gewählten Zeitraum als PDF oder CSV, - Wise: Kontoauszüge unter anderem als CSV, XLSX, MT940, QIF und CAMT.053; für geeignete Geschäftskonten außerdem eine offene API. Da Formate, Zugriffswege und Produktverfügbarkeit geändert werden können, muss der Agent die aktuelle Anbieterunterstützung bei der Einrichtung prüfen. #### Verbindliche Dublettenprüfung Ein erneut heruntergeladener oder zeitlich überlappender Bankexport darf keine zweite Buchung erzeugen. Der Agent führt deshalb je Mandant, Bankkonto und Währung ein eigenes Importjournal. Die Prüfung erfolgt gestuft: 1. stabile Transaktions- oder Bewegungs-ID des Anbieters, 2. bestätigte Konto-, Pocket- oder IBAN-Zuordnung, 3. kanonischer Fingerabdruck aus Währung, Buchungsdatum, Wertstellung, Betrag, Vorzeichen, normalisiertem Buchungstext, Gegenkonto und vorhandenen Referenzen, 4. bei Dateien zusätzlich Datei-SHA-256 und Zeilennummer, 5. stabiler TAXDOO-Idempotenzschlüssel aus Konto und Bewegungsfingerabdruck. Der Abruf darf einen überlappenden Zeitraum verwenden, damit zunächst vorgemerkte und später endgültig gebuchte Bewegungen erkannt werden. Automatisch importiert werden ausschließlich endgültig gebuchte Transaktionen. Geänderte, stornierte oder nicht eindeutig wiedererkannte Bewegungen werden dem Anwender vorgelegt und nicht als vermeintlich neuer Umsatz importiert. Vor und nach einem Lauf vergleicht der Agent mindestens: - Anzahl neuer und bereits bekannter Bewegungen, - Summe der Belastungen und Gutschriften je Währung, - Anfangs- und Endsaldo, sofern der Export diese zuverlässig enthält, - Anzahl abgelehnter oder unvollständiger Zeilen, - TAXDOO-Importantworten mit dem eigenen Importjournal. Der Import erfolgt ausschließlich in einen von `/ki-agent/belegkreise` gelieferten Belegkreis vom Typ `BankCsv`, ohne `OpenBankDataId`. Die Bewegung wird mit `IstBearbeitet=false` angelegt und steht anschließend für die weitere Belegzuordnung zur Verfügung. Kopierbarer Beratungsprompt: ```text Ich möchte einen lesenden KI-Agenten einrichten, der neue, endgültig gebuchte Bankbewegungen aus nach TAXDOO überträgt. Lies die vollständige TAXDOO-KiAgent-Anleitung und öffne den Bauplan FINTECH_BANKDATEN_AUTOMATISIERT_IMPORTIEREN. Prüfe zuerst, ob eine offizielle lesende API, ein Banking-Feed oder ein automatisch bereitgestellter Export verwendet werden kann. Falls nur ein Webdownload möglich ist, plane einen assistierten, ausdrücklich freigegebenen Ablauf ohne Umgehung von Zwei-Faktor-Authentifizierung, CAPTCHA oder Gerätefreigabe. Entwirf die Konten- und Währungszuordnung, das Quellformat-Mapping, einen überlappenden Abrufzeitraum, die Behandlung vorgemerkter und stornierter Bewegungen sowie eine mehrstufige Dublettenprüfung aus Quelltransaktions-ID, kanonischem Zeilenfingerabdruck, Datei-SHA-256 und stabilem Idempotenzschlüssel. Importiere ausschließlich in einen von /ki-agent/belegkreise gelieferten BankCsv-Belegkreis, ohne OpenBankDataId. Erstelle außerdem Salden- und Summenkontrollen, Ausnahmeregeln und Akzeptanztests. Führe noch keine Anmeldung, keinen Download und keinen schreibenden API-Aufruf aus. ``` ### Konfiguration eines externen Workflows Vor der Aktivierung sollten Anwender und Agent mindestens klären: - Welche externe Quelle darf gelesen werden? - Welche Postfächer, Labels, Ordner oder Mandantenbereiche sind erlaubt? - Welcher Zeitraum darf durchsucht werden? - Welche Dateitypen werden berücksichtigt? - Darf der Agent externe Elemente markieren, verschieben oder archivieren? - Darf er nur Vorschläge machen oder nach Bestätigung importieren? - Welche Kriterien sind für eine eindeutige Zuordnung erforderlich? - Wie werden mehrdeutige Treffer behandelt? - Wie speichert der Agent externe IDs, SHA-256 und Idempotenzschlüssel? - Über welchen sicheren Kanal werden Fehler und Aufgaben gemeldet? - Wie lange dürfen Analyse- und Zuordnungsdaten gespeichert werden? - Wer darf in TAXDOO offene Posten zur Zahlung auswählen? - Welche Freigaberegeln gelten im integrierten Banking? ## Verbindlicher Ablauf ### 1. Einrichtung prüfen ```http GET /ki-agent/anleitung.json?Mandant= Authorization: Bearer ``` Nur bei `Einrichtungsstatus.Status == "Bereit"` fortfahren. ### 2. Belegkreise abrufen ```http GET /ki-agent/belegkreise Authorization: Bearer X-Mandant: ``` Der Agent darf ausschließlich eine dort gelieferte `Id` als `SchnittstelleId` verwenden. Die zugehörigen `ImportRegeln` sind verbindlich und müssen bei jeder neuen Sitzung erneut ausgewertet werden. Eine sichtbare, ungelöschte Schnittstelle wird als `Ausgangsrechnung` ausgegeben, wenn entweder ihr `SchnittstelleTyp` `Ausgangsrechnung` ist oder ihre `SchnittstelleArt` `Ausgangsrechnung` ist. Bank-Schnittstellen mit der Schnittstellenart `BankCSV` oder `CSVImport` werden als `BankCsv` ausgegeben. Ein Belegkreis vom Schnittstellentyp `Barbelege` wird als `Bar` ausgegeben und kann für Kassen- und Barbelegimporte verwendet werden. ### 3. Bankdatensatz auswählen Dieser Schritt gilt nur für normale Bankimporte vom Belegkreistyp `Bank`. Ohne `SchnittstelleId` liefert der Endpunkt die offenen Bankdaten aller verfügbaren normalen Bank-Belegkreise des authentifizierten Mandanten: ```http GET /ki-agent/bankdaten/offen Authorization: Bearer X-Mandant: ``` Optional kann weiterhin auf genau einen Bank-Belegkreis gefiltert werden: ```http GET /ki-agent/bankdaten/offen?SchnittstelleId= Authorization: Bearer X-Mandant: ``` Jeder Ergebnisdatensatz enthält sowohl `Id` als auch `SchnittstelleId`. Der Anwender wählt einen Eintrag aus. Beim Import wird dessen `Id` als `OpenBankDataId` und dessen `SchnittstelleId` unverändert übernommen. Beide IDs müssen immer aus demselben Ergebnisdatensatz stammen; der Agent darf sie weder erraten noch zwischen verschiedenen Datensätzen kombinieren. Jeder Bankdatensatz enthält außerdem seine bereits vorhandenen `DatenIds`. `DatenIdTypen` wird auf Antwortebene pro `SchnittstelleId` geliefert und enthält die für deren konkrete `SchnittstelleArt` eingerichteten Werte `TypId`, `Typ` und `Prioritaet`. Fachlich gleich benannte Typen können für verschiedene Schnittstellenarten unterschiedliche `TypId`-Werte besitzen. Der Agent darf eine TypId daher weder erfinden noch zwischen verschiedenen `SchnittstelleId` übertragen. Berücksichtigt werden ausschließlich sichtbare Bank-Schnittstellen mit `Del == null || Del == 0` und `Hidden == null || Hidden == false`. Auch die Bankdatensätze selbst müssen ungelöscht (`Del == null || Del == 0`) und unbearbeitet (`IstBearbeitet == null || IstBearbeitet == false`) sein. Bei normalen Bankimporten stammen Betrag, Datum, Text, Auftraggeber und IBAN aus dem ausgewählten Bankdatensatz. Diese Werte dürfen nicht als Ersatz im Importrequest übermittelt werden. Bank-CSV-Belegkreise werden von diesem Auswahlablauf nicht erfasst. Ein normaler Bankimport markiert den ausgewählten Bankdatensatz weiterhin standardmäßig als bearbeitet. Soll lediglich mindestens eine Datei angehängt werden und der Bankdatensatz für die spätere fachliche Bearbeitung offen bleiben, wird zusätzlich `BankeintragAlsBearbeitetMarkieren=false` übermittelt. Dieser Modus erfordert mindestens eine Datei und einen stabilen Idempotenzschlüssel. Die Antwort liefert dann `Status=AttachedOpen` und `BankeintragIstBearbeitet=false`; `IstBearbeitetAm` bleibt leer. Solange der Bankdatensatz offen bleibt, ist genau ein fachlicher KiAgent-Anhängevorgang zulässig. Bis zu zehn Dateien können gemeinsam in diesem Request übertragen werden. Eine technische Wiederholung verwendet den vollständig unveränderten Request und denselben Idempotenzschlüssel. Ein zweiter abweichender Anhängevorgang wird mit `BANK_ENTRY_ALREADY_HAS_KI_AGENT_ATTACHMENT` abgelehnt. ### 3a. Offenen Bankdatensatz mit Daten-IDs anreichern ```http POST /ki-agent/bankdaten/daten-ids Authorization: Bearer X-Mandant: Content-Type: application/json ``` Beispiel: ```json { "SchnittstelleId": "", "VerarbeiteteDatenId": "", "DatenIds": [ { "TypId": "", "Wert": "" } ] } ``` Verbindliche Regeln: - `SchnittstelleId` und `VerarbeiteteDatenId` müssen aus demselben aktuellen Bankdatensatz stammen. - Der Belegkreis muss ein normaler, sichtbarer und ungelöschter Bank-Belegkreis sein; `BankCsv` ist nicht zulässig. - Der Bankdatensatz muss ungelöscht und weiterhin unbearbeitet sein (`IstBearbeitet == null || IstBearbeitet == false`). - Jede `TypId` muss aus `DatenIdTypen` derselben `SchnittstelleId` stammen. - Pro Anfrage sind höchstens 20 Daten-IDs mit jeweils maximal 500 Zeichen erlaubt. - Eine identische Kombination aus `TypId` und normalisiertem `Wert` wird nicht erneut eingefügt; eine technische Wiederholung ist fachlich idempotent. - Der Endpunkt verändert `IstBearbeitet`, `Parsed_id` und `GebuchtId` nicht. Die Antwort enthält `Hinzugefuegt`, `BereitsVorhanden` und die vollständige aktuelle `DatenIds`-Liste. Wird der Bankdatensatz parallel bearbeitet, wird keine Kennung ergänzt. Eine Daten-ID ist eine Grundlage für einen späteren Abgleich, aber allein kein verbindlicher Zahlungsnachweis. ### 3b. Offene Ausgangsrechnungen abrufen Bei den über diesen Endpunkt gelieferten Ausgangsrechnungen handelt es sich fachlich um Rechnungen, die bislang noch nicht bezahlt wurden. Ohne `SchnittstelleId` liefert der Endpunkt die passenden Datensätze aller gültigen Ausgangsrechnungsschnittstellen des authentifizierten Mandanten: ```http GET /ki-agent/ausgangsrechnungen/offen Authorization: Bearer X-Mandant: ``` Optional kann auf eine einzelne Ausgangsrechnungsschnittstelle gefiltert werden: ```http GET /ki-agent/ausgangsrechnungen/offen?SchnittstelleId= Authorization: Bearer X-Mandant: ``` Eine Ausgangsrechnung wird nur geliefert, wenn sie: - unbearbeitet ist (`IstBearbeitet == false`), - ungebucht ist (`GebuchtId == null || GebuchtId == 0`), - ungeparst ist (`Parsed_id == null || Parsed_id == 0`), - ungelöscht ist (`Del == null || Del == 0`). Die zugehörige Schnittstelle muss zum Mandanten gehören, vom Typ `Ausgangsrechnung`, sichtbar und ebenfalls ungelöscht sein. Jeder Ergebnisdatensatz enthält seine `Id` und `SchnittstelleId` sowie Betrag, Datum, Text, Rechnungsnummer, Auftraggeberangaben, USt-ID und Steuerbetrag. `Parsed_id` ist das technische Feld, das gelegentlich als „Pass-ID“ bezeichnet wird. Die Statusfelder selbst werden nicht ausgegeben; ihre zulässigen Werte werden durch den Endpunkt garantiert. ### 3c. Offene Eingangsrechnungen abrufen Der Endpunkt liefert alle Eingangsrechnungen, die bisher noch nicht bezahlt worden sind. Ohne `SchnittstelleId` werden die passenden Datensätze aller gültigen Eingangsrechnungsschnittstellen des authentifizierten Mandanten abgerufen: ```http GET /ki-agent/eingangsrechnungen/offen Authorization: Bearer X-Mandant: ``` Optional kann auf eine einzelne Eingangsrechnungsschnittstelle gefiltert werden: ```http GET /ki-agent/eingangsrechnungen/offen?SchnittstelleId= Authorization: Bearer X-Mandant: ``` Eine Eingangsrechnung wird nur geliefert, wenn sie: - bearbeitet ist (`IstBearbeitet == true`), - ungeparst ist (`Parsed_id == null || Parsed_id == 0`), - ungelöscht ist (`Del == null || Del == 0`). Ein zusätzlicher Filter auf `GebuchtId` wird bei diesem Endpunkt nicht angewendet. Die zugehörige Schnittstelle muss zum Mandanten gehören, vom Typ `Eingangsrechnung`, sichtbar und ungelöscht (`Del == null || Del == 0`) sein. Jeder Ergebnisdatensatz enthält seine `Id` und `SchnittstelleId` sowie Betrag, Datum, Text, Rechnungsnummer, Auftraggeberangaben, USt-ID und Steuerbetrag. ### 3d. Offene Zahlungssystemdaten mit Daten-IDs abrufen Ohne `SchnittstelleId` liefert der Endpunkt die passenden Datensätze aller gültigen Zahlungssystem-Schnittstellen des authentifizierten Mandanten: ```http GET /ki-agent/zahlungssysteme/offen Authorization: Bearer X-Mandant: ``` Optional kann auf eine einzelne Zahlungssystem-Schnittstelle gefiltert werden: ```http GET /ki-agent/zahlungssysteme/offen?SchnittstelleId= Authorization: Bearer X-Mandant: ``` Ein Datensatz wird nur geliefert, wenn er: - strikt unbearbeitet ist (`IstBearbeitet == false`); `null` ist nicht zulässig, - ungeparst ist (`Parsed_id == null || Parsed_id == 0`), - ungelöscht ist (`Del == null || Del == 0`). Ein zusätzlicher Filter auf `GebuchtId` wird nicht angewendet. Die zugehörige Schnittstelle muss zum Mandanten gehören, vom Typ `Zahlsysteme`, sichtbar und ungelöscht (`Del == null || Del == 0`) sein. Jeder Ergebnisdatensatz enthält seine `Id`, `SchnittstelleId`, Betrag, Datum, Text, Rechnungsnummer, Auftraggeberangaben, USt-ID und Steuerbetrag. Zusätzlich enthält `DatenIds` alle zugeordneten Kennungen: ```json { "Wert": "ORDER-12345", "Typ": "OrderID", "TypId": 8, "Prioritaet": 9 } ``` `Wert` stammt aus `daten_ids.Wert`, `TypId` aus `daten_ids.Bezeichnung_id`, `Typ` aus `schnittstelle_id_bezeichnung.Name` und `Prioritaet` aus `schnittstelle_id_bezeichnung.Prio`. Mehrere Werte desselben Typs werden vollständig zurückgegeben. Besitzt eine historische Daten-ID keine auflösbare Bezeichnung, bleiben `Wert` und `TypId` erhalten, `Typ` ist `null` und die Antwort enthält die Warnung `DATA_ID_TYPE_NOT_RESOLVED`. Alle Daten-IDs werden zusätzlich auf den authentifizierten Mandanten und die gelieferten Verarbeitete-Daten-IDs begrenzt. Der Agent darf einen fehlenden Typ nicht erraten. Daten-IDs sind Zuordnungshinweise und allein kein verbindlicher Zahlungsnachweis. ### 3e. Bestätigte Datensätze gemeinsam parsen ```http POST /ki-agent/verarbeitete-daten/parsen Authorization: Bearer X-Mandant: Content-Type: application/json ``` Fiktives Beispiel: ```json { "VerarbeiteteDatenIds": [ "", "" ] } ``` Verbindliche Regeln: - Die Liste muss mindestens eine ID enthalten. - Alle IDs müssen gemeinsam vom Anwender bestätigt worden sein. - Alle Datensätze müssen zum authentifizierten Mandanten gehören, vorhanden, ungelöscht und ungeparst sein. - Die zugehörigen Quelldaten müssen vollständig vorhanden sein. - Die Summe der ausgewählten Beträge darf nicht abweichen. - Der Agent übermittelt weder `ParsedId` noch eine Parserregel. - Die Speicherung erfolgt ausschließlich mit der Parserregel `KIAgent`. Bei Erfolg setzt TAXDOO für alle ausgewählten Datensätze `IstBearbeitet=true` und dieselbe positive `Parsed_id`. Die Antwort enthält diese gemeinsame ID als `ParsedId`: ```json { "IsSuccess": true, "ParsedId": "", "Message": "2 Datensätze wurden erfolgreich durch den KI-Agenten zugeordnet." } ``` Kann die Auswahl nicht verarbeitet werden, ist `IsSuccess=false`, `ErrorCode=PARSING_REJECTED`, `ErrorField=VerarbeiteteDatenIds` und `ErrorMessage` enthält die konkrete fachliche Validierungsmeldung. Vor einem neuen Versuch muss die korrigierte Auswahl erneut bestätigt werden. ### 3f. Bestätigte Datensätze mit Abweichung parsen ```http POST /ki-agent/verarbeitete-daten/parsen-mit-abweichung Authorization: Bearer X-Mandant: Content-Type: application/json ``` Fiktives Beispiel: ```json { "VerarbeiteteDatenIds": [ "", "" ], "SelectedVerarbeiteteDatenId": "", "SteuerTyp": { "Id": "" }, "PositionTyp": { "PositionTypEnum": "" }, "SteuerInfo": "", "MaximaleAbweichung": 100.00 } ``` Erlaubte Werte für `PositionTyp.PositionTypEnum`: - `Währungsabweichung` - `Sonstigeabweichung` - `Rabatt` - `SKonto` Verbindliche Regeln: - `VerarbeiteteDatenIds` enthält mindestens eine positive, eindeutige ID. - `SelectedVerarbeiteteDatenId` muss in derselben Liste enthalten sein. - `SteuerTyp` und `PositionTyp` sind Pflicht und müssen vom Anwender bestätigt sein. - `SteuerInfo` ist optional und darf ausschließlich eine ausdrücklich vom Anwender mitgeteilte außergewöhnliche steuerliche Besonderheit enthalten. - Vor dem Setzen von `SteuerInfo` muss der Agent erklären, dass der Vorgang dadurch vollständig manuell bearbeitet wird. - Ohne eine solche Besonderheit muss der Agent `SteuerInfo` weglassen oder `null` übermitteln; er darf das Feld niemals erfinden oder ableiten. - `MaximaleAbweichung` ist optional und muss bei Angabe größer als 0 sein. - Betrag, `DatumString`, Text und Steuerbetrag sind keine Request-Felder. - Der KiAgent-Service lädt oder speichert selbst keine `VerarbeiteteDaten`. - Die einzige Schreiboperation ist `AbweichungService.AbweichungSpeichern`. Ist die automatisch ermittelte absolute Abweichung größer als `MaximaleAbweichung`, wird die gesamte Speicherung abgelehnt. Die Antwort enthält dann `IsSuccess=false`, den Fehlercode `DEVIATION_PARSING_REJECTED` und die unveränderte Meldung des zentralen Abweichungsservice in `ErrorMessage`. Bei Erfolg enthält die Antwort `IsSuccess=true` und eine bestätigende `Message`. Der Agent darf aus einer erfolgreichen Antwort keine zusätzlichen internen IDs ableiten. ### 3g. Neue Bankdaten über eine Bank-CSV-Schnittstelle importieren Für Bank-Schnittstellen, deren Schnittstellenart `SchnittstelleArt.BankCSV` oder `SchnittstelleArt.CSVImport` ist, liefert `/ki-agent/belegkreise` den Belegkreistyp `BankCsv`. Dieser Importweg ist für `SchnittstelleTyp.Bank` in Kombination mit einer dieser beiden CSV-Schnittstellenarten vorgesehen. Der Import erfolgt wie bei Kasse oder Bar über: ```http POST /ki-agent/import Authorization: Bearer X-Mandant: Content-Type: application/json ``` Erforderlich sind: - `SchnittstelleId` - `Betrag` - `Datum` - `Text` Optional dürfen unter anderem `Rnr`, `Auftraggeber`, `AuftraggeberId`, Steuerangaben und Dokumente übermittelt werden. `AuftraggeberId` enthält bei Angabe eine gültige IBAN. Leerzeichen werden entfernt und Buchstaben in Großbuchstaben gespeichert. `OpenBankDataId` darf bei `BankCsv` nicht übermittelt werden, weil kein bereits vorhandener offener Bankdatensatz ergänzt wird. Stattdessen entsteht ein neuer Datensatz, der mit `IstBearbeitet=false` gespeichert wird und damit zunächst unbearbeitet bleibt. Beispiel: ```json { "SchnittstelleId": "", "Datum": "2026-07-27", "Betrag": 119.00, "Text": "Beispiel-Bankbuchung", "Rnr": "BEISPIEL-RECHNUNG", "Auftraggeber": "Beispielunternehmen", "AuftraggeberId": "DE02120300000000202051", "Idempotenzschluessel": "" } ``` Der Agent darf den Typ `BankCsv` nicht aus einem Namen oder einer Vermutung ableiten. Maßgeblich ist ausschließlich der aktuell von `/ki-agent/belegkreise` gelieferte `BelegkreisTyp`. ### 4. Importdaten vervollständigen Für alle Belegkreise außer dem normalen Belegkreistyp `Bank` sind erforderlich: - `SchnittstelleId` - `Betrag` - `Datum` - `Text` Optional erlaubt sind unter anderem: - `SteuerInEuro` - `Rnr` - `Auftraggeber` - `AuftraggeberId` - `SteuerTyp` - `SteuerKategorie` - Dokumentdateien `AuftraggeberId` enthält optional eine IBAN. Leerzeichen werden entfernt und Buchstaben in Großbuchstaben gespeichert. #### 4a. Genau ein Dokument ohne vorverarbeitete Fachdaten importieren Wird als Multipart-Request genau eine Datei zusammen mit `SchnittstelleId`, aber ohne Betrag, Datum, Text oder andere fachliche Buchungsfelder übertragen, legt der Dienst zunächst einen leeren `VerarbeiteteDaten`-Datensatz an. Dieser wird anschließend asynchron durch Document AI befüllt. Die Antwort liefert die neue `VerarbeiteteDatenId` und die `DocumentAiWorkflowIds` für die Statusabfrage. Dieser Dokumentmodus ist für `Bar`, `Kasse`, `Lieferant`, `Cloud` und `BankCsv` zulässig. Für `Bank` und `Ausgangsrechnung` wird er abgelehnt. Die `Ss_Uid` enthält den SHA-256-Inhaltshash und einen bereinigten Dateinamen. Ein stabiler `Idempotenzschluessel` und `DateiPruefsummenSha256` dürfen zusätzlich angegeben werden. #### 4b. Analysierte Dokumente einem offenen Datensatz zuordnen Stellt ein nachgelagerter Prozess fest, dass ein zuvor über Bar, Kasse oder Lieferant hochgeladener Beleg zu einem anderen offenen Datensatz gehört, kann er die Zuordnung atomar ändern. Der Empfänger darf aus jedem aktiven, von `/ki-agent/belegkreise` gelieferten Belegkreis stammen: ```http POST /ki-agent/import/dokument-zuordnen Authorization: Bearer X-Mandant: Content-Type: application/json ``` ```json { "HerkunftVerarbeiteteDatenId": 123456, "EmpfaengerVerarbeiteteDatenId": 987654, "EmpfaengerAlsBearbeitetMarkieren": false } ``` `IstBearbeitet=false` und `IstBearbeitet=null` gelten bei Herkunft und Empfänger als offen; nur `true` wird abgelehnt. Die Herkunft muss ungeparst und ungebucht sein und mindestens ein aktives Dokument mit abgeschlossener Analyse besitzen. Alle aktiven Herkunftsdokumente werden dem Empfängerdatensatz zugeordnet, anschließend wird die Herkunft mit `Del=1` markiert. Der Empfänger bleibt standardmäßig offen. Nur bei `EmpfaengerAlsBearbeitetMarkieren=true` werden `IstBearbeitet=true` und `IstBearbeitetAm` gesetzt. Für den Empfänger gibt es keine Einschränkung auf `Bank`; auch `BankCsv`, Bar, Kasse, Lieferant, Cloud und Ausgangsrechnung sind zulässig. #### 4c. Offenen Datensatz einer anderen Schnittstelle zuordnen Ein offener, ungeparster und ungebuchter Nicht-Bank-Datensatz kann atomar einer anderen aktiven Nicht-Bank-Schnittstelle desselben Mandanten zugeordnet werden: ```http POST /ki-agent/import/schnittstelle-zuordnen Authorization: Bearer X-Mandant: Content-Type: application/json ``` ```json { "VerarbeiteteDatenId": 123456, "ZielSchnittstelleId": 18172 } ``` `IstBearbeitet=false` und `IstBearbeitet=null` gelten als offen. Gelöschte, geparste, gebuchte oder noch durch einen Workflow verarbeitete Datensätze werden abgelehnt. Sowohl die bisherige als auch die neue Schnittstelle dürfen weder `Bank` noch `BankCsv` sein. Bei Erfolg wird ausschließlich `Ss_zgd_id` geändert; Dokumente, Document-AI-Ergebnisse, `Ss_Uid`, fachliche Werte und `IstBearbeitet` bleiben unverändert. Ist der Datensatz bereits der angegebenen Zielschnittstelle zugeordnet, antwortet der Endpunkt erfolgreich mit `Status=AlreadyAssigned` und `ZuordnungGeaendert=false`. Der Endpunkt ist fachlich schreibend. Ein Live-Test darf deshalb ausschließlich über die definierte Schreibtestsuite und nur dann ausgeführt werden, wenn der autoritative Einrichtungsstatus ausdrücklich `istMustermandant === true` liefert. `false`, `null`, ein fehlendes Feld oder eine technisch uneindeutige Prüfung müssen den Test vor dem ersten Schreibzugriff abbrechen. ### 5. Ausgangsrechnungen Bei einem Belegkreis vom Typ `Ausgangsrechnung` sind zusätzlich erforderlich: - `VersandlandIso` - `LieferlandIso` - `SteuerlandIso` Jeder Wert ist ein ISO-3166-1-Alpha-2-Code, zum Beispiel `DE`. Gespeichert wird die zum Rechnungsdatum passende interne Länder-ID. `Ust_id` ist ausschließlich bei Ausgangsrechnungen optional erlaubt. Abhängig vom Geschäftsvorfall kann die USt-ID des Käufers erforderlich sein. Der Agent darf weder Länder noch USt-ID erfinden und soll bei fehlenden fachlichen Informationen den Anwender fragen. ### 6. Zusammenfassung und Bestätigung Vor dem Import zeigt der Agent mindestens: - ausgewählten Belegkreis und Typ, - fachliche Importwerte, - ausgewählten Bankdatensatz, falls zutreffend, - Dateinamen und Dateianzahl, - relevante Warnungen, - Hinweis auf die Verantwortung des Anwenders. API-Key und andere Geheimnisse dürfen nicht angezeigt werden. Erst nach Bestätigung durch den Anwender wird der datenverändernde Request gesendet. ### 7. Import ausführen ```http POST /ki-agent/import Authorization: Bearer X-Mandant: Idempotency-Key: Content-Type: application/json ``` Fiktives Beispiel ohne Dokument: ```json { "SchnittstelleId": "", "Datum": "2026-07-27", "Betrag": 119.00, "Text": "Büromaterial", "SteuerInEuro": 19.00, "Rnr": "BEISPIEL-RECHNUNG", "Auftraggeber": "Beispielunternehmen" } ``` Alle Beispielwerte müssen durch vom Anwender bestätigte Werte ersetzt werden. Platzhalter dürfen niemals importiert werden. Fiktives Beispiel zum Anhängen eines Dokuments an einen offenen normalen Bankdatensatz, ohne ihn sofort als bearbeitet zu markieren: ```json { "SchnittstelleId": "", "OpenBankDataId": "", "BankeintragAlsBearbeitetMarkieren": false, "Idempotenzschluessel": "" } ``` Die Datei wird im selben `multipart/form-data`-Request im Feld `Dateien` übertragen. Ohne Datei oder ohne Idempotenzschlüssel wird dieser Modus abgelehnt. Bei weggelassenem Feld, `null` oder `true` gilt unverändert das bisherige Verhalten: Der Bankdatensatz wird als bearbeitet markiert. ### 7a. Große Datenmengen ohne Dokumente als Liste importieren Für 1 bis 1.000 vollständig strukturierte Datensätze desselben Belegkreises steht der asynchrone Listenimport zur Verfügung: ```http POST /ki-agent/import/liste Authorization: Bearer X-Mandant: Idempotency-Key: Content-Type: application/json ``` Der Listenimport akzeptiert ausschließlich JSON-Daten. Dokumente, `multipart/form-data` und Dokumentprüfsummen sind nicht erlaubt. Jeder Datensatz benötigt eine innerhalb der Liste eindeutige, im Quellsystem stabile `ExterneId`. Alle Datensätze verwenden die gemeinsame `SchnittstelleId` des Requests. Die komplette Liste wird vor dem Start geprüft; enthält sie Validierungsfehler, wird kein Auftrag gestartet. Fiktives ERP-Beispiel für Ausgangsrechnungen: ```json { "SchnittstelleId": "", "Idempotenzschluessel": "erp-ar-2026-07-stufe-001", "Datensaetze": [ { "ExterneId": "ERP-AR-900001", "Datum": "2026-07-01", "Betrag": 119.00, "Text": "Ausgangsrechnung ERP-900001", "Rnr": "ERP-900001", "Auftraggeber": "Beispielkunde GmbH", "VersandlandIso": "DE", "LieferlandIso": "DE", "SteuerlandIso": "DE" }, { "ExterneId": "ERP-AR-900002", "Datum": "2026-07-01", "Betrag": 238.00, "Text": "Ausgangsrechnung ERP-900002", "Rnr": "ERP-900002", "Auftraggeber": "Musterkunde AG", "VersandlandIso": "DE", "LieferlandIso": "DE", "SteuerlandIso": "DE" } ] } ``` Die Annahme erfolgt mit HTTP `202` und einer `ListenImportId`. Der Agent fragt den Status anschließend mit demselben Mandanten ab: ```http GET /ki-agent/import/liste/status?ListenImportId= Authorization: Bearer X-Mandant: ``` Das Statusergebnis enthält Zähler und je `ExterneId` entweder die erzeugte `VerarbeiteteDatenId` oder einen fachlichen Fehler. Erst nach einem Endstatus wird die nächste Stufe gesendet. Ein ERP-Export mit beispielsweise 12.450 Ausgangsrechnungen muss in 13 stabile Stufen aufgeteilt werden: zwölf Stufen mit jeweils 1.000 und eine letzte Stufe mit 450 Datensätzen. Jede Stufe erhält einen eigenen Idempotenzschlüssel und darf höchstens 1.000 Datensätze enthalten. Das Tageskontingent von 5.000 Listenimport-Datensätzen ist zusätzlich zu beachten; der Export wird daher über mehrere UTC-Kalendertage verteilt. Wiederholungen einer unveränderten Stufe verwenden denselben Idempotenzschlüssel. ## Idempotenz Für jeden fachlichen Import soll ein stabiler, zufälliger Schlüssel verwendet werden, vorzugsweise UUID-basiert. Er kann als `Idempotency-Key`-Header oder im Feld `Idempotenzschluessel` übertragen werden. Regeln: - Ein Schlüssel gehört zu genau einem fachlichen Import. - Bei einem technischen Fehler werden Request und Schlüssel unverändert wiederverwendet. - Bei einer fachlichen Änderung ist ein neuer Schlüssel erforderlich. - `IDEMPOTENCY_KEY_CONFLICT` darf nicht automatisch umgangen werden. - Der Schlüssel darf keine Zugangsdaten oder personenbezogenen Inhalte enthalten. - Bei `BankeintragAlsBearbeitetMarkieren=false` ist der Schlüssel Pflicht. Ein technischer Retry muss auch die Dateibytes und alle Request-Felder unverändert wiederverwenden. ## Dateien und SHA-256 Dokumente sind bei allen Belegkreisen optional. Sie werden als `multipart/form-data` im Feld `Dateien` übertragen. Grenzen: - maximal 10 Dateien pro Import, - maximal 20 MiB pro Datei, - erlaubte Endungen: `.pdf`, `.xml`, `.eml`, `.msg`, `.doc`, `.docx`, `.xls`, `.xlsx`, `.txt`, `.csv`, `.html`, `.htm`, `.jpg`, `.jpeg`, `.png`, `.tif`, `.tiff`. PDF-Dateien dürfen eine eingebettete ZUGFeRD-Rechnung enthalten. Eigenständige XML-Dateien sind für XRechnungen vorgesehen. Beide Formate werden im Document-AI-Workflow bevorzugt als strukturierte Rechnungen verarbeitet; eine nicht als ZUGFeRD oder XRechnung lesbare Datei kann nicht als strukturierte Rechnung ausgewertet werden. E-Mail-Dateien, Word-, Excel-, Text-, CSV- und HTML-Dokumente dürfen ebenfalls hochgeladen werden. Die Uploadfähigkeit bedeutet nicht, dass jeder Inhalt automatisch vollständig ausgewertet werden kann. Der Workflowstatus zeigt das Ergebnis der automatischen Verarbeitung; das Originaldokument bleibt dem Import zugeordnet. Ob der Inhalt steuerlich ausreichend oder korrekt ist, liegt in der Verantwortung des Mandanten und ist keine Voraussetzung für den Upload. Makrofähige Office-Dateien und Archive werden nicht unterstützt. Ein KI-Agent darf öffentlich erreichbare Dokumentlinks innerhalb des vom Anwender freigegebenen Automatisierungsrahmens lokal abrufen. An TAXDOO übermittelt er nicht den Link, sondern ausschließlich die daraus gewonnene Dokumentdatei. Linkparameter, Zugriffstokens oder lokale Zugangsdaten dürfen weder in Dateinamen noch in Importfelder übernommen werden. Eine erneute Bestätigung für jede einzelne Datei ist innerhalb des freigegebenen Rahmens nicht erforderlich. Bei einer HTML-Rechnung sollte der Agent nach Möglichkeit das Original erhalten und zusätzlich lokal eine PDF-Darstellung erzeugen, wenn dies für die Anzeige oder automatische Auswertung hilfreich ist. Optional können im Feld `DateiPruefsummenSha256` SHA-256-Prüfsummen angegeben werden. Dann gilt: - genau eine Prüfsumme je Datei, - dieselbe Reihenfolge wie die multipart-Dateien, - 64 Hexadezimalzeichen je Prüfsumme, - Berechnung aus den tatsächlich übertragenen Dateibytes. ## Document AI Document AI wird nur für tatsächlich übermittelte Dateien gestartet. Der Import liefert je Datei eine `DocumentAiWorkflowId`. Statusabfrage: ```http GET /ki-agent/workflows/status?WorkflowIds= Authorization: Bearer X-Mandant: ``` Der Agent fragt im empfohlenen Intervall weiter, bis `AlleAbgeschlossen` den Wert `true` besitzt. Ein Workflow ist nur erfolgreich, wenn: - sein Status `Success` ist und - eine positive `DocumentAiId` vorliegt. Ein technisch als erfolgreich markierter Workflow ohne `DocumentAiId` wird von der KiAgent-API als fehlgeschlagen gemeldet. ## Zugriffslimits und Wiederholungen Die Zugriffslimits gelten getrennt pro authentifiziertem Mandanten: - maximal 120 authentifizierte Anfragen pro Minute, - maximal 30 Aufrufe von `/ki-agent/import` und `/ki-agent/import/liste` zusammen pro Minute, - maximal 500 Aufrufe dieser Importendpunkte zusammen pro UTC-Kalendertag, - maximal 2 gleichzeitig laufende Aufrufe von `/ki-agent/import`, - maximal 1 gleichzeitig verarbeiteter Listenimport, - maximal 5.000 Datensätze aus Listenimporten pro UTC-Kalendertag und höchstens 1.000 Datensätze je Liste. Jeder Import zählt sowohl zum allgemeinen Minutenlimit als auch zum Importlimit der aktuellen Minute und des aktuellen UTC-Kalendertags. Andere Mandanten verbrauchen dieses Kontingent nicht. Bei einer Überschreitung antwortet die API mit HTTP `429 Too Many Requests`. Die Antwort enthält: - `ErrorCode=RATE_LIMIT_EXCEEDED`, - `CanRetry=true`, - `RetryAfterSeconds`, - `LimitScope` mit `ALLGEMEIN`, `IMPORT`, `IMPORT_TAG`, `IMPORT_PARALLELITAET`, `IMPORT_DATENSAETZE_TAG` oder `IMPORT_LISTE_PARALLELITAET`, - den HTTP-Header `Retry-After`. Der Agent muss mindestens die angegebene Zeit warten und darf danach nur begrenzt wiederholen. Parallele Ersatzanfragen, wechselnde Clients oder IP-Adressen und unbegrenzte Wiederholungsschleifen sind nicht zulässig. Ist die serverseitige Zugriffskontrolle vorübergehend nicht verfügbar, liefert die API HTTP `503`, `ErrorCode=RATE_LIMIT_UNAVAILABLE` und ebenfalls `Retry-After`. Auch dann darf erst nach Ablauf der Wartezeit erneut angefragt werden. ## Fehlerbehandlung Fehlerantworten sind maschinenlesbar: - `ErrorCode`: stabiler Fehlercode, - `ErrorField`: betroffenes Request-Feld, - `CanRetry`: ob eine technische Wiederholung sinnvoll ist, - `RetryAfterSeconds`: Mindestwartezeit bei einer vorübergehenden Begrenzung, - `LimitScope`: betroffener Bereich der Zugriffskontrolle, - `NaechsterSchritt`: konkrete empfohlene Aktion. Die Werte der tatsächlichen Antwort haben Vorrang vor allgemeinen Hinweisen in dieser Dokumentation. Besonders wichtig: | ErrorCode | Verhalten | |---|---| | `AUTHENTICATION_FAILED` | Mandant und API-Key prüfen; keine Einzelangabe erraten | | `INTERFACE_NOT_FOUND` | Belegkreise erneut abrufen | | `INTERFACE_ID_REQUIRED` | Positive SchnittstelleId aus `/ki-agent/belegkreise` angeben | | `FROM_DATE_REQUIRED` | Pflichtfeld `Von` im ISO-Datumsformat ergänzen | | `DATE_RANGE_INVALID` | `Bis` so korrigieren, dass es nach `Von` liegt | | `BOOKING_DATA_IDS_REQUIRED` | Mindestens eine positive Buchungsdaten-ID angeben | | `BOOKING_DATA_ID_INVALID` | Nicht positive Buchungsdaten-IDs entfernen oder korrigieren | | `BOOKING_DATA_ID_LIMIT_EXCEEDED` | Die Liste in Anfragen mit jeweils höchstens 500 IDs aufteilen | | `PROCESSED_DATA_IDS_REQUIRED` | Mindestens eine positive ID aus `verarbeitete_daten` angeben | | `PROCESSED_DATA_ID_INVALID` | Nicht positive IDs entfernen oder korrigieren | | `PROCESSED_DATA_IDS_LIMIT_EXCEEDED` | Die Liste in Anfragen mit jeweils höchstens 500 IDs aufteilen | | `DOCUMENT_EXPORT_NOT_FOUND` | Export-ID und authentifizierten Mandanten prüfen | | `DOCUMENT_EXPORT_PART_NOT_FOUND` | Status abrufen und eine dort aufgeführte Teilnummer verwenden | | `DOCUMENT_EXPORT_CONTINUATION_TOKEN_INVALID` | Token unverändert aus der Statusantwort übernehmen | | `DOCUMENT_EXPORT_EXPIRED` | Einen neuen Dokumentexport starten | | `BANK_ENTRY_ALREADY_PROCESSED` | Offene Bankdaten erneut abrufen | | `BANK_ENTRY_ALREADY_HAS_KI_AGENT_ATTACHMENT` | Vorhandenen Bankeintrag weiterbearbeiten oder exakt denselben Request mit demselben Idempotenzschlüssel wiederholen | | `FILE_REQUIRED_TO_KEEP_BANK_ENTRY_OPEN` | Mindestens eine Datei übermitteln oder den Bankeintrag als bearbeitet markieren | | `IDEMPOTENCY_KEY_REQUIRED` | Stabilen Idempotenzschlüssel für den offenen Bank-Anhängevorgang ergänzen | | `PARSING_REJECTED` | Fachliche Meldung anzeigen, Auswahl korrigieren und erneut bestätigen lassen | | `DEVIATION_PARSING_REJECTED` | Meldung des Abweichungsservice unverändert anzeigen; Auswahl oder Grenzbetrag nur nach erneuter Bestätigung ändern | | `COUNTRY_CODE_REQUIRED` | Fehlendes Land beim Anwender erfragen | | `FILE_CHECKSUM_MISMATCH` | SHA-256 aus den übertragenen Bytes neu berechnen | | `IDEMPOTENCY_KEY_CONFLICT` | Stoppen und Anwender informieren | | `IDEMPOTENCY_LOCK_TIMEOUT` | Exakt denselben Request später erneut senden | | `DOCUMENT_AI_ENQUEUE_FAILED` | Nur entsprechend `CanRetry` und `NaechsterSchritt` wiederholen | | `RATE_LIMIT_EXCEEDED` | `Retry-After` beachten und erst danach begrenzt wiederholen | | `RATE_LIMIT_UNAVAILABLE` | HTTP 503 und `Retry-After` beachten; keine parallelen Ersatzanfragen | | `INTERNAL_ERROR` | Begrenzt mit unverändertem Idempotenzschlüssel wiederholen | ## Kopierbare System-Prompt-Vorlage ```text Du unterstützt den Anwender beim Import in TAXDOO. Prüfe zuerst die Einrichtung und importiere nur bei Status Bereit. Rufe danach /ki-agent/belegkreise auf und behandle die gelieferten ImportRegeln als verbindlich. Erfinde niemals IDs, Zugangsdaten, Bankdaten, Länder, Steuerangaben oder USt-IDs. Frage fehlende fachliche Angaben beim Anwender ab. Wenn der Anwender bestimmte Buchungsdaten anhand ihrer IDs lesen möchte, übermittle 1 bis 500 positive, bestätigte IDs an /ki-agent/buchungsdaten/abfragen. Behandle NichtVerfuegbareIds ausschließlich als nicht für den authentifizierten Mandanten verfügbar und folgere daraus nicht, ob ein Datensatz fehlt, gelöscht oder mandantenfremd ist. Wenn der Anwender nach Dokumentation, einer Anleitung, Beispielen oder verfügbaren Möglichkeiten fragt, beginne mit Praesentationsvorschlag und dem Leitbild der digitalen Buchhaltungssekretärin. Lies danach AnwendungsfaelleKurzuebersicht und die passenden Einträge aus Anwendungsfaelle. Öffne deren AgentenBauplan beziehungsweise DetailsUrl und für vollständige Erläuterungen VollstaendigeDokumentationUrl. Stelle konkrete praktische Arbeitsabläufe vor den technischen Endpunkten dar. Wenn der Anwender nach Automatisierungsmöglichkeiten oder Verbesserungen seines Arbeitsalltags fragt, erläutere passende Einträge aus Anwendungsfaelle einschließlich täglicher Rechnungsbearbeitung, Zahlungsmappe, Dubletten, Skonto, Shopify, JTL, plentyONE, Marktplatzauszahlungen, Retouren, Fintech-Banken und Monatsabschluss. Zeige mindestens den Beratungsprompt kopierbar an und biete danach Einrichtung und Betrieb an. Unterscheide klar zwischen Funktionen der TAXDOO-API und Fähigkeiten oder Zugriffsrechten des externen Agenten. Empfehle zunächst einen Ablauf mit Anwenderbestätigung. Ein externer Agent darf unbezahlte Eingangsrechnungen bereitstellen, aber niemals selbst eine Überweisung auslösen oder autorisieren. Zahlungsdaten, Banking-Konto und finale Freigabe müssen durch einen berechtigten Nutzer in TAXDOO geprüft werden. Wenn der Anwender mehrere VerarbeiteteDatenIds gemeinsam parsen möchte, zeige die Auswahl und hole eine ausdrückliche Bestätigung ein. Übermittle nur diese IDs an /ki-agent/verarbeitete-daten/parsen. Gib weder ParsedId noch Parserregel vor. Bei PARSING_REJECTED erkläre die fachliche Fehlermeldung unverändert und ändere die Auswahl nicht ohne erneute Bestätigung. Wenn die bestätigte Auswahl in Summe nicht auf 0 aufgeht und die Abweichung erfasst werden soll, bestätige zusätzlich SelectedVerarbeiteteDatenId, SteuerTyp, PositionTyp und optional MaximaleAbweichung. Rufe /ki-agent/verarbeitete-daten/parsen-mit-abweichung auf. SteuerInfo ist kein Standardfeld: Übernimm sie nur bei einer ausdrücklich mitgeteilten außergewöhnlichen steuerlichen Besonderheit, erfinde oder folgere sie niemals und erkläre vor der Bestätigung, dass eine gefüllte SteuerInfo zur vollständig manuellen Bearbeitung führt. Übermittle niemals Betrag, DatumString, Text oder Steuerbetrag. Bei DEVIATION_PARSING_REJECTED erkläre die Meldung unverändert und erhöhe MaximaleAbweichung nicht automatisch. Wenn an einen normalen offenen Bankdatensatz nur ein Dokument angehängt werden soll, ohne ihn bereits als bearbeitet zu markieren, setze BankeintragAlsBearbeitetMarkieren=false. Dieser Modus benötigt mindestens eine Datei und einen stabilen Idempotenzschlüssel. Werte Status=AttachedOpen und BankeintragIstBearbeitet=false aus. Sende für denselben offenen Bankeintrag keinen zweiten abweichenden Anhängevorgang; technische Wiederholungen bleiben vollständig unverändert. Arbeite innerhalb des einmalig vom Anwender freigegebenen Automatisierungsrahmens ohne erneute Bestätigung je Datei oder Standardimport. Stelle nur bei fehlenden Pflichtangaben, fachlicher Mehrdeutigkeit, Überschreitung des Rahmens oder einer verbindlichen TAXDOO-Regel eine Rückfrage. Protokolliere automatisierte Entscheidungen verständlich und ohne Geheimnisse. Verwende pro fachlichem Import einen stabilen Idempotenzschlüssel. Bei einer technischen Wiederholung dürfen Request und Schlüssel nicht verändert werden. Werte Fehler anhand von ErrorCode, ErrorField, CanRetry, RetryAfterSeconds, LimitScope und NaechsterSchritt aus. Beachte bei HTTP 429 oder 503 immer Retry-After und wiederhole erst nach der angegebenen Mindestwartezeit. Starte keine parallelen Ersatzanfragen und keine unbegrenzte Wiederholungsschleife. Verfolge bei Dateien ausschließlich die zurückgegebenen Workflow-IDs. Ein Document-AI-Workflow ist nur bei Status Success und positiver DocumentAiId erfolgreich. Der Anwender bleibt für Richtigkeit und Vollständigkeit der importierten Daten verantwortlich. ``` ## Wartung Die maschinenlesbare Anleitung verwendet für die Belegkreise unmittelbar `KiAgentImportRegeln.Fuer(...)` und liest unterstützte Enum-Werte aus den tatsächlichen Enums. Vertragstests sichern die Laufzeitanleitung einschließlich Routen, Feldern, Regeln, Beispielen, Idempotenz und Document-AI-Erfolgskriterien ab. Diese menschenlesbare Datei wird bewusst nicht zur Laufzeit interpretiert und muss bei Vertragsänderungen mitgeprüft werden. Bei Änderungen an Endpunkten, Feldern, Grenzwerten oder Fehlercodes müssen Servicevertrag, Laufzeitanleitung, diese Datei und die Vertragstests gemeinsam geprüft werden.