Transaktionen per API filtern

Mit Filtern holst du genau die Transaktionen ab, die deine Anwendung braucht. Alle Beispiele verwenden die öffentliche API mit /v1/WORKSPACE_ID und einem Bearer-Schlüssel.

SEPA-Mandatsreferenz auslesen

Die Referenz des SEPA-Mandats einer Lastschrift findest du unter counterpart.mandateReference, die SEPA Gläubiger-ID unter counterpart.creditorId. Vergleiche beide Angaben mit einem bekannten SEPA-Mandat: Verschiedene Gläubiger können dieselbe Mandatsreferenz verwenden. Dieser Ausschnitt zeigt die beiden Felder in einer Transaktion:

{
  "counterpart": {
    "mandateReference": "0001042",
    "creditorId": "DE98ZZZ09999999999"
  }
}

Beide Felder sind optional und erscheinen nur, wenn ein Wert vorliegt. Behandle Referenzen und Kennungen als Zeichenketten, damit etwa führende Nullen erhalten bleiben. Ein JavaScript-Beispiel zeigt, wie du vorhandene und fehlende Werte ausliest.

Die API liefert hier Kennungen zum SEPA-Mandat, keine vollständigen Mandatsunterlagen. Bestätige die Zuordnung zu einem Vertrag anhand deiner vorhandenen Unterlagen. Dasselbe SEPA-Mandat kann mehrere Lastschriften abdecken; auch Gläubiger-ID und Referenz zusammen identifizieren keine einzelne Rechnung.

Weitere Zahlungsangaben nutzen

Diese optionalen Antwortfelder helfen dir beim Abgleich mit deinen eigenen Zahlungs- und Rechnungsdaten. Welche Angaben vorliegen, hängt von der Bank und der Buchung ab.

Fehlende oder leere Angaben werden ausgelassen. Die Referenzen bleiben Zeichenketten. originalAmount ist eine Zahl; auch 0 bleibt erhalten. Verwende für den ursprünglichen Betrag die zugehörige originalCurrency. Die Felder ersetzen nicht amount und currency der aktuellen Buchung und sind keine allgemeine Aufschlüsselung einer Währungsumrechnung.

PayPal-Daten auslesen

Wie du das Konto verbindest und den Zugriff für API, MCP oder Integrationen einrichtest, erklärt PayPal anbinden und nutzen.

Bei PayPal-Transaktionen kann ein zusätzliches Objekt paypal vorhanden sein:

{
  "paypal": {
    "invoiceNumber": "RE-2026-1042",
    "fee": 0,
    "net": 29.9
  }
}

invoiceNumber ist die von PayPal gelieferte Rechnungsnummer als Zeichenkette, fee die PayPal-Gebühr und net der PayPal-Nettobetrag als Zahlen. Das Objekt erscheint nur bei PayPal-Transaktionen mit verfügbaren PayPal-Daten. Einzelne Angaben können fehlen; ein leeres paypal-Objekt wird nicht ausgegeben. Ein Betrag von 0, etwa bei einer gebührenfreien Zahlung, bleibt erhalten. Ein PayPal-Name im Verwendungszweck allein bedeutet nicht, dass diese Zusatzdaten vorliegen.

Konto und Zeitraum wählen

Für ein bestimmtes Konto verwendest du:

GET /v1/WORKSPACE_ID/accounts/KONTO_ID/transactions

Für einen Zeitraum kannst du diese Parameter ergänzen:

Die Grenzen werden einschließlich ausgewertet. Verwende vollständige Zeitangaben mit Zeitzone, wenn du einen Zeitraum genau abgrenzen möchtest. Ein reines Datum wie 2026-08-31 steht für den Tagesbeginn, nicht für das Ende dieses Tages.

Dieses Beispiel liest Buchungen im August 2026 nach UTC. KONTOFLUX_WORKSPACE_ID und KONTOFLUX_API_KEY stehen für Umgebungsvariablen deiner Anwendung:

curl --fail-with-body --get \
  "https://api.kontoflux.io/v1/${KONTOFLUX_WORKSPACE_ID}/transactions" \
  --header "Authorization: Bearer ${KONTOFLUX_API_KEY}" \
  --data-urlencode 'bookedAfter=2026-08-01T00:00:00.000Z' \
  --data-urlencode 'bookedBefore=2026-08-31T23:59:59.999Z' \
  --data-urlencode 'limit=50'

Kategorien filtern

Mit category filterst du nach der Kategorie einer Transaktion. Du kannst eine Kategorie-ID oder einen exakten Kategorienamen übergeben. Die gültigen Werte liest du über /categories.

parentCategory eignet sich für eine übergeordnete Kategorie. Der Filter berücksichtigt sie auch dann, wenn die Transaktion direkt dieser Hauptkategorie zugeordnet ist. Verwende für einfache Abfragen jeweils den passenden einzelnen Kategorienfilter.

Suchen oder Referenzen abgleichen

Verwende zum Beispiel /transactions/match?query=RE-2026-1042 für eine Rechnungsreferenz. Die Ergebnisse enthalten einen score, der die Übereinstimmung bewertet. Er ist keine Bestätigung, dass eine Rechnung bezahlt ist. Prüfe zusätzlich Betrag, Währung, Richtung und mögliche Mehrfachtreffer.

Für /match kannst du mit threshold zwischen 0 und 1 die Mindestbewertung festlegen. Der Standardwert ist 0.60. Ein höherer Wert lässt weniger Treffer zu. Der Abgleich verwendet Referenz- und Textmerkmale; aus dem Score lässt sich keine Zahlungswahrscheinlichkeit ableiten.

Konto- und Datumsfilter helfen auch beim Referenzabgleich, den Suchbereich einzugrenzen. Die Varianten für ein einzelnes Konto enden entsprechend auf /accounts/KONTO_ID/transactions/search oder /accounts/KONTO_ID/transactions/match.

Weitere Ergebnisse laden

Listen liefern ein JSON-Array. Mit limit bestimmst du die Seitengröße, mit offset überspringst du bereits geladene Ergebnisse.

Bei limit=50 rufst du nacheinander offset=0, offset=50, offset=100 ab. Im Antwortheader X-Total-Count findest du die Gesamtzahl der passenden Ergebnisse. Behalte beim Weiterblättern dieselben Filter bei.

Alle Parameter und Antwortfelder findest du in der API-Referenz.