Anleitungen

Rechnungen

Der Agent kann eine ausgestellte Rechnung aus einem verbundenen Fakturoid- oder ABRA-Flexi-Konto lesen und als Grundlage für einen Erinnerungsanruf nutzen - er stellt nie eine Rechnung aus und markiert auch keine als bezahlt.

Was er kann und was nicht

• Sucht ausgestellte Rechnungen nach Nummer oder Firmenname (list_invoices).
• Liest den aktuellen Stand einer Rechnung direkt beim Anbieter (get_invoice).
• Legt eine Erinnerungsaufgabe an (taskType: "invoice"), die auf die Rechnung verweist.

Was er nicht kann

• Er stellt keine Rechnung aus, bearbeitet oder löscht keine.
• Er markiert keine Rechnung als bezahlt - das können nur Fakturoid oder ABRA selbst.
• Er verbindet Fakturoid nicht mit Zugangsdaten - nur über OAuth im Browser.

Konto verbinden

Beide Rechnungsdienste verwalten Sie an derselben Stelle wie Kalender, im Portal im Bereich Daten und Integrationen (/propojeni). list_integrations und GET /v1/integrations sind nur lesend: Sie liefern den Verbindungsstatus und gegebenenfalls eine connectUrl, verbinden aber selbst nichts. Den ausführlichen Ablauf für den Agenten (list_integrations -> connectUrl -> Schritt im Browser) finden Sie auf der Seite Verbindungen.

Fakturoid

Die Verbindung läuft ausschließlich über die OAuth-Anmeldung im Browser - POST /v1/integrations mit provider: "fakturoid" lehnt REST mit dem Fehler integration_unsupported ab, Zugangsdaten lassen sich hier nicht senden. Hat das Konto mehrere Firmen mit Rechnungsstellung, kehrt der Browser nach der Anmeldung zur Seite Daten und Integrationen in volai zurück (/propojeni) und erst dort erscheint die Firmenauswahl - der Eintrag in integrations entsteht erst nach dieser Auswahl. ready bei fakturoid in GET /v1/integrations meldet nur, dass volai die OAuth-Zugangsdaten zu Fakturoid eingerichtet hat (FAKTUROID_CLIENT_ID und weitere) - NICHT, dass ein bestimmtes Konto bereits verbunden ist. Ob die Verbindung steht, erkennt der Agent daran, dass sie im Feld integrations erscheint.

ABRA Flexi

Die Verbindung erfolgt mit Zugangsdaten, genau wie bei Apple Calendar: POST /v1/integrations mit {provider: "abra-flexi", baseUrl, company, username, password}. Die Serveradresse (baseUrl) muss genau der Adresse entsprechen, die der Betreiber vorab freigegeben hat (ABRA_FLEXI_ALLOWED_HOSTS) - jede andere liefert einen Fehler.

Rechnungen lesen

Ein Ablauf in zwei Schritten: zuerst die Suche, dann der aktuelle Stand der einen Rechnung, die Sie interessiert.

• list_invoices({integrationId, search?}) - search (bis 100 Zeichen) sucht beim Anbieter nach Rechnungsnummer oder Firmenname; geliefert werden die ersten 40 Zeilen bei Fakturoid oder 50 bei ABRA, ohne Seitenumbruch. Bei zu vielen Treffern präzisieren Sie search.
• get_invoice({integrationId, invoiceId}) - invoiceId ist die aus list_invoices übernommene externalId. Liefert den aktuellsten Stand direkt vom Anbieter, nicht das, was volai gespeichert hat.

REST-Entsprechungen: GET /v1/integrations/{id}/invoices?search=... und GET /v1/integrations/{id}/invoices/{invoiceId}.

status ist paid, unpaid, overdue oder unknown; amountDueMinor ist eine ganze Zahl in der kleinsten Einheit der WÄHRUNG DES BELEGS (nicht zwingend CZK), und null bedeutet einen nicht ermittelten Restbetrag. Das Detail enthält zusätzlich provider, fetchedAt und evidence: "provider_response".

Erinnerung über Aufgaben

Massenhafte Erinnerungsanrufe zu unbezahlten Rechnungen laufen über Aufgaben.

Eine Aufgabe vom Typ taskType: "invoice" wird mit source: "integration" angelegt, und jeder Empfänger (oder die ganze Aufgabe, wenn die Rechnung für alle gleich ist) trägt externalRefs.invoice = {connectionId, externalId, provider?} - connectionId ist die Verbindungs-ID aus list_integrations, externalId die Rechnungs-ID aus list_invoices. Ohne diesen Verweis scheitern create_task/POST /v1/tasks mit dem Fehler validation und der Meldung recipients.externalRefs, und es wird keine Aufgabe gespeichert. Fehlt der Pflichtverweis bei einem bereits vorhandenen Datensatz, führt ihn get_task/GET /v1/tasks/{id} in issues auf, und start_task weigert sich, die Aufgabe mit demselben Validierungsfehler zu starten.

Jeder Empfänger trägt außerdem das Feld paymentStatus (not_applicable, unknown, unpaid, paid, disputed) - nur lesend, das System leitet es aus dem letzten Lesen der Rechnung beim Anbieter unmittelbar vor dem Wählen ab. Ohne Rechnungsverweis ist es not_applicable, nach dem Anlegen oder wenn sich Status oder Betrag nicht prüfen lassen unknown, sonst gemäß der Antwort von Fakturoid/ABRA - bei einer bezahlten Rechnung überspringt die Aufgabe den Eintrag (skipped) und setzt paid. Den Wert disputed setzt das System heute nicht selbst, das Portal kann ihn nur anzeigen - er gehört zur öffentlichen Aufzählung (TaskItem in /openapi.json) für eine künftige manuelle Markierung strittiger Rechnungen.

Fehler

• integration_not_found - Eine Verbindung mit dieser integrationId existiert nicht oder gehört nicht zu diesem Konto.
• integration_unsupported - Die Verbindung dient nicht der Rechnungsstellung (zum Beispiel ein Kalender), oder es wurde versucht, Fakturoid mit Zugangsdaten statt über OAuth zu verbinden.
• integration_unauthorized - Fakturoid oder ABRA haben den Zugriff widerrufen - die Verbindung muss im Portal neu hergestellt werden.
• integration_provider_error - Der Anbieter antwortet derzeit nicht oder hat einen Fehler gemeldet - versuchen Sie es später erneut und behandeln Sie den Rechnungsstatus bis dahin als unbekannt.
• integration_invalid_query - ABRA hat search mit Backslashes oder gemischten Anführungszeichen abgelehnt - vereinfachen Sie die Anfrage.

Die vollständige Tabelle mit allen Codes finden Sie im Abschnitt Rechnungen in der REST-API-Referenz und in den MCP-Fehlern.

Sicherheit

Zugriffstoken und Passwörter für Fakturoid und ABRA Flexi gibt weder die REST API noch MCP jemals zurück, und wir speichern sie verschlüsselt. Eine Integration trennen Sie nur im Portal oder über REST (DELETE /v1/integrations/{id}) - MCP hat dafür absichtlich kein Werkzeug, weil der Vorgang nicht umkehrbar ist.