API-Codebeispiele

Die Beispiele lesen Daten aus einem Workspace. Sie setzen einen aktiven API-Schlüssel mit passenden Berechtigungen voraus.

Hinterlege Workspace-Kennung und Schlüssel als KONTOFLUX_WORKSPACE_ID und KONTOFLUX_API_KEY in der Umgebung deines Skripts. So bleiben die Zugangsdaten außerhalb des Quelltexts.

Berechtigungen mit curl prüfen

curl --fail-with-body \
  "https://api.kontoflux.io/v1/${KONTOFLUX_WORKSPACE_ID}/key/scope" \
  --header "Authorization: Bearer ${KONTOFLUX_API_KEY}"

Die Antwort enthält unter anderem workspaceId, scopes und die Kontobeschränkung. Prüfe diese Angaben, wenn ein anderer Endpunkt den Zugriff ablehnt.

Konten abrufen

curl --fail-with-body \
  "https://api.kontoflux.io/v1/${KONTOFLUX_WORKSPACE_ID}/accounts" \
  --header "Authorization: Bearer ${KONTOFLUX_API_KEY}"

Rechnungsreferenz suchen

curl --fail-with-body --get \
  "https://api.kontoflux.io/v1/${KONTOFLUX_WORKSPACE_ID}/transactions/match" \
  --header "Authorization: Bearer ${KONTOFLUX_API_KEY}" \
  --data-urlencode 'query=RE-2026-1042' \
  --data-urlencode 'threshold=0.8' \
  --data-urlencode 'limit=10'

--data-urlencode übernimmt die korrekte Übertragung von Leerzeichen und Sonderzeichen. Die Treffer sind Kandidaten für deinen Abgleich. Prüfe die Transaktion, bevor du daraus einen Zahlungsstatus ableitest.

Transaktionen mit JavaScript lesen

Dieses Beispiel ist für eine serverseitige JavaScript-Umgebung mit fetch und Umgebungsvariablen gedacht:

const workspaceId = process.env.KONTOFLUX_WORKSPACE_ID;
const apiKey = process.env.KONTOFLUX_API_KEY;

if (!workspaceId || !apiKey) {
  throw new Error('Workspace-Kennung und API-Schlüssel fehlen.');
}

const url = new URL(
  `https://api.kontoflux.io/v1/${encodeURIComponent(workspaceId)}/transactions`
);
url.searchParams.set('limit', '50');
url.searchParams.set('offset', '0');

const response = await fetch(url, {
  headers: { Authorization: `Bearer ${apiKey}` },
});

if (!response.ok) {
  throw new Error(`Kontoflux.io antwortet mit HTTP ${response.status}.`);
}

const transactions = await response.json();
if (!Array.isArray(transactions)) {
  throw new Error('Die API-Antwort enthält keine Transaktionsliste.');
}

console.log(`${transactions.length} Transaktionen geladen.`);
console.log(`Treffer insgesamt: ${response.headers.get('X-Total-Count')}`);

Für weitere Seiten erhöhst du offset um die Seitengröße. Zeitraum, Konten und Kategorien kannst du wie unter Transaktionen filtern beschrieben ergänzen.