SEPA-Zahlungen auf dem Konto automatisch finden

Die Überweisung an den Druckdienstleister ist beauftragt. Ein Kunde hat angekündigt, die Anzahlung zu überweisen. Und diese Woche müsste der Softwareanbieter seine Lastschrift einziehen. Im Büro stehen drei Fragen auf der Liste, für die jemand wieder das Bankportal öffnet und die Umsätze durchsucht.

Diese Suche lässt sich in einen regelmäßigen Ablauf übersetzen. Deine Anwendung kennt die erwarteten Zahlungen, liest die Kontoumsätze über die Kontoflux.io-API und sucht passende Buchungen. Das Team bekommt eine Liste der gefundenen Zahlungen und der Fälle, bei denen noch etwas fehlt. So muss niemand jeden Morgen denselben Kontoauszug durchsuchen.

Mit einer Liste erwarteter SEPA-Zahlungen anfangen

Zum SEPA-Zahlungsverkehr gehören Überweisungen und Lastschriften. Einen Überblick gibt die Deutsche Bundesbank. Für die automatische Suche hilft es, bereits vor dem Abruf festzuhalten, was du erwartest: Konto, Zeitraum, Betrag, Richtung, Gegenpartei und eine bekannte Referenz. Die folgenden Angaben sind frei erfunden:

Eine ausgehende Buchung hat einen negativen Betrag, ein Eingang einen positiven. Beim Kunden kann die vereinbarte Referenz im freien Verwendungszweck stehen; beim eigenen Überweisungsauftrag ist möglicherweise eine strukturierte endToEndReference verfügbar. Plane deine Suche anhand der Angaben, die du für den jeweiligen Vorgang tatsächlich hast.

Das richtige Konto und Zeitfenster abrufen

Verbinde dein Bankkonto mit Kontoflux.io und richte einen API-Schlüssel mit Leserechten für die gewünschten Transaktionen und das Konto ein. Die Konto-ID erhältst du über GET /v1/WORKSPACE_ID/accounts. Hinterlege die Kennungen und den Schlüssel in den Umgebungsvariablen deines Servers. Der Schlüssel gehört nicht in den JavaScript-Code deiner Website.

Im Beispiel suchen wir die Lieferantenzahlung in den Buchungen vom 24. August bis einschließlich 6. September 2026 nach UTC. Ein etwas größerer Zeitraum berücksichtigt, dass Auftrag und Buchung an unterschiedlichen Tagen liegen können. bookedAfter und bookedBefore schließen ihre Grenzen ein; die vollständigen Zeitangaben erfassen auch den letzten Tag.

// Serverseitiges JavaScript mit fetch, zum Beispiel in Node.js.
const workspaceId = process.env.KONTOFLUX_WORKSPACE_ID;
const accountId = process.env.KONTOFLUX_ACCOUNT_ID;
const apiKey = process.env.KONTOFLUX_API_KEY;
if (!workspaceId || !accountId || !apiKey) {
  throw new Error('Workspace, Konto oder API-Schlüssel fehlt.');
}

const url = new URL(
  'https://api.kontoflux.io/v1/' + encodeURIComponent(workspaceId) +
  '/accounts/' + encodeURIComponent(accountId) + '/transactions'
);
url.searchParams.set('bookedAfter', '2026-08-24T00:00:00.000Z');
url.searchParams.set('bookedBefore', '2026-09-06T23:59:59.999Z');
url.searchParams.set('sortBy', '_id');
url.searchParams.set('order', 'asc');
url.searchParams.set('limit', '100');

const transactions = new Map();
for (let offset = 0; ; offset += 100) {
  url.searchParams.set('offset', String(offset));
  const response = await fetch(url, {
    headers: { Authorization: 'Bearer ' + apiKey },
  });
  if (!response.ok) {
    throw new Error('Kontoflux.io: HTTP ' + response.status);
  }
  const page = await response.json();
  if (!Array.isArray(page)) throw new Error('Keine Transaktionsliste.');
  for (const transaction of page) {
    transactions.set(transaction.id, transaction);
  }
  if (page.length < 100) break;
}

// Bekannter SEPA-Überweisungsauftrag: 480 EUR an einen Lieferanten.
const expected = { reference: 'E2E-2026-0081', cents: -48000 };
const candidates = [...transactions.values()].filter(transaction =>
  transaction.endToEndReference === expected.reference &&
  transaction.currency === 'EUR' &&
  Number.isFinite(transaction.amount) &&
  Math.round(transaction.amount * 100) === expected.cents
);

// Anschließend Gegenpartei und mögliche Mehrfachtreffer prüfen.
console.log(candidates);

Das Skript lädt jeweils 100 Buchungen, bis keine vollständige Seite mehr zurückkommt. Alle Seiten verwenden dasselbe Konto und dieselben Datumsfilter. Die Map hält jede Transaktions-ID innerhalb dieses Laufs nur einmal. Für Euro-Beträge vergleicht das Beispiel ganze Cent: Minus 48.000 Cent bedeutet eine ausgehende Zahlung von 480 Euro.

Der exakte Referenzvergleich liefert Kandidaten für diesen Auftrag. Prüfe dazu die erwartete Gegenpartei und ob mehrere Buchungen passen. Eine fehlende endToEndReference lässt den Vergleich scheitern; sie beweist nicht, dass die SEPA-Überweisung ausgeblieben ist. Referenzfelder sind optional und hängen von den gelieferten Bankdaten ab. Behalte sie als Zeichenketten, einschließlich führender Nullen.

Eine Referenz auch im Verwendungszweck finden

Wenn die Referenz in einem Text steckt oder anders geschrieben wurde, hilft /transactions/match. Dieser Endpunkt durchsucht Referenzen und Textangaben und gibt Kandidaten mit einem score zurück. Für den Lieferantenauftrag sieht der Aufruf so aus:

curl --fail-with-body --get \
  "https://api.kontoflux.io/v1/${KONTOFLUX_WORKSPACE_ID}/accounts/${KONTOFLUX_ACCOUNT_ID}/transactions/match" \
  --header "Authorization: Bearer ${KONTOFLUX_API_KEY}" \
  --data-urlencode 'query=E2E-2026-0081' \
  --data-urlencode 'bookedAfter=2026-08-24T00:00:00.000Z' \
  --data-urlencode 'bookedBefore=2026-09-06T23:59:59.999Z' \
  --data-urlencode 'threshold=0.8' \
  --data-urlencode 'limit=50' \
  --data-urlencode 'offset=0'

Der Score bewertet die Übereinstimmung mit der Suche. Er bestätigt weder den Zahlungsbetrag noch die Richtung oder den Zahlungserfolg. Prüfe diese Angaben in deiner Anwendung. Für die Kundenanzahlung suchst du entsprechend nach PROJEKT-2408 und erwartest einen Eingang von 1.800 Euro.

Der Header X-Total-Count nennt die Zahl der Treffer im ausgewerteten Suchbereich. Die Suche berücksichtigt höchstens die 100.000 neuesten Buchungen, die zu deinen Filtern passen. Grenze große Kontohistorien deshalb zeitlich ein. Sind es mehr als 50, lade mit denselben Filtern und offset=50, offset=100 und so weiter nach. Die Dokumentation zu Filtern und Referenzsuche erklärt die Parameter. Gib einen fehlgeschlagenen Abruf als Fehler aus; eine leere Trefferliste und ein HTTP-Fehler brauchen unterschiedliche Behandlung.

SEPA-Lastschriften über das bekannte SEPA-Mandat suchen

Beim Softwareanbieter kennst du vielleicht keine einzelne Zahlungsreferenz, aber die Angaben zum SEPA-Mandat. Vergleiche die gelieferten Felder counterpart.creditorId und counterpart.mandateReference gemeinsam mit deinen geprüften Unterlagen. Ergänze den erwarteten Zeitraum, die Richtung und den Betrag von 75 Euro.

Dasselbe SEPA-Mandat kann für mehrere Lastschriften verwendet werden. Deshalb gehört jede gefundene Buchung zu einem eigenen Prüfvorgang. Wie du damit auch wiederkehrende Einzüge verschiedenen Verträgen zuordnest, zeigt der Beitrag SEPA-Mandate und Verträge abgleichen.

Aus der Suche wird eine tägliche Prüfliste

Lass deinen eigenen Dienst regelmäßig die noch offenen Suchaufträge durchgehen. Speichere zu jedem Ergebnis den Workspace, die Transaktions-ID, die erwartete Zahlung und den Prüfstatus. Der Schlüssel aus Workspace und Transaktions-ID verhindert, dass ein erneuter Lauf dieselbe Buchung als neue Zahlung behandelt. Mehrere plausible Treffer oder ein abweichender Betrag bleiben zur Klärung offen. Speichere einen Lauf erst als abgeschlossen, wenn alle Seiten erfolgreich verarbeitet sind.

Lies bei Folgeläufen einen überlappenden Zeitraum erneut ein und aktualisiere bereits bekannte Buchungen. So können später importierte Umsätze noch auftauchen. Eine Rücklastschrift oder Erstattung bekommt einen eigenen Vorgang und kann eine zuvor bestätigte Zuordnung wieder zur Prüfung bringen.

Zeige neben den Ergebnissen den Datenstand. Ein API-Abruf liest die in Kontoflux.io importierten Umsätze und startet keinen neuen Bankabruf. Bei einem fehlenden Treffer prüft dein Ablauf deshalb zunächst den Importstand und das Suchfenster, bevor er eine Zahlung als ausstehend meldet.