Zum Inhalt springen
Agile Finance
AnmeldenZugang beantragen
AblaufEntwicklerPreiseSicherheitAnmelden

Für Entwickler

Vom Schlüssel zum ersten Umsatz in wenigen Aufrufen.

Eine REST-API mit OpenAPI-Beschreibung, signierte Webhooks, ein MCP-Zugang und eine Testbank, die sich wie eine echte Bank verhält, mit TAN, App-Freigabe und Fehlerfällen.

API-ReferenzSchnellstart

API

Basisadresse /api/v1, Anmeldung mit Bearer-Schlüssel (agile_finance_test_… oder agile_finance_live_…). Beträge in ganzen Cent, Soll negativ. Idempotency-Key für POST, Rate-Limit in den Kopfzeilen, Blättern mit Cursor.

Schlüssel gibt es nach der Freigabe in der App unter Entwickler.

Anfrage
curl -s https://finance.agiledeveloper.de/api/v1/verbinden \
  -H "Authorization: Bearer $AF_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endkunde_extern_ref": "kunde-4711",
    "quelle": "testbank",
    "zurueck_url": "https://ihre-plattform.example/bank/fertig"
  }'
Antwort · 201
{
  "url": "https://finance.agiledeveloper.de/verbinden/vb_8Yk2…",
  "gueltig_bis": "2026-11-02T09:30:00.000Z",
  "endkunde_id": "3c1f8a90-6d24-4b1e-8f37-1a2b9c0d7e65"
}
POST/endkundenEndkunden anlegen, mit Ihrer eigenen Kennung extern_ref
POST/verbindenEinmal-Link zur Verbinden-Strecke erzeugen
GET/verbindungenBankanbindungen mit Status und Einwilligung
GET/kontenKonten mit IBAN, Inhaber und Saldo
GET/konten/{id}/umsaetzeUmsätze mit Filter von, bis, q, kategorie
GET/konten/{id}/saldenTagessalden
GET/konten/{id}/auszuegeKontoauszüge eines Kontos
GET/konten/{id}/exportExport als camt053, mt940, csv oder pdf
POST/importeDatei hochladen: camt, MT940, CSV, PDF
POST/sandbox/buchungBuchung simulieren, nur in der Sandbox
Ein Umsatz, alle Felder
{
  "id": "0b7c3f52-8a1e-4c67-9d10-5f2a6e1b3c44",
  "konto_id": "7e19d0c2-34ab-4f8e-a6d1-92c05b7f1e30",
  "buchung": "2026-11-02",
  "wertstellung": "2026-11-02",
  "betrag_cent": -95000,
  "waehrung": "EUR",
  "verwendungszweck": "Miete 11/2026",
  "gegen_name": "Hausverwaltung Sonnenhof",
  "gegen_iban": "DE89370400440532013000",
  "gegen_bic": null,
  "bank_ref": "TB2026110201",
  "end_to_end": null,
  "mandat_ref": null,
  "glaeubiger_id": null,
  "buchungstext": "DAUERAUFTRAG",
  "gvc": "152",
  "vorgemerkt": false,
  "kategorie": "miete",
  "wiederkehrend": true,
  "erstellt": "2026-11-02T06:14:09.000Z"
}

Auszug-Arten: bank_pdf ist das Original der Bank, camt die Datei, report unser eigenes PDF, immer als „kein Bankbeleg“ gekennzeichnet. Beim Abruf über PSD2 gibt es kein Original-PDF, „Kontoauszug“ meint dort die Umsätze.

Webhooks

Jede Zustellung trägt agile-event, agile-delivery und agile-signature (t=Zeitstempel, v1=HMAC-SHA256 über „t.Rohdaten“). Fehlgeschlagene Zustellungen wiederholen wir. Der Inhalt enthält immer die Umgebung, nie Zugangsdaten.

verbindung.aktivEndkunde hat seine Bank verbunden
umsaetze.neuNeue Umsätze sind da
auszug.neuNeuer Kontoauszug
import.fertigDatei-Import abgeschlossen
einwilligung.laeuft_ab14, 7 und 1 Tag vor Ablauf
einwilligung.abgelaufenEinwilligung ist abgelaufen
einwilligung.widerrufenEndkunde hat widerrufen
verbindung.fehlerVerbindung gestört, mit Code
abruf.fehlgeschlagenEin Abruf schlug fehl
Signatur prüfen
import crypto from "node:crypto";

function echt(rohdaten, kopf, geheimnis) {
  const { t, v1 } = Object.fromEntries(
    kopf.split(",").map((teil) => teil.split("=")),
  );
  const soll = crypto.createHmac("sha256", geheimnis)
    .update(`${t}.${rohdaten}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(soll), Buffer.from(v1));
}
Inhalt · umsaetze.neu
{
  "id": "f6a1c2d8-2b45-4e90-b7c3-0d9e8f7a6b51",
  "typ": "umsaetze.neu",
  "erstellt": "2026-11-02T06:14:11.000Z",
  "daten": {
    "umgebung": "sandbox",
    "verbindung_id": "5d2e7b14-90ac-4f33-8e21-6c7d1a0f9b28",
    "abruf_id": "a93e0c71-5f18-4d2a-b6e4-3f8c2d1e7a06",
    "neu": 3
  }
}

MCP

KI-Assistenten wie Claude oder ChatGPT verbinden sich über OAuth 2.1 mit /mcp. Die Werkzeuge lesen Daten, erzeugen Verbinden-Links und stoßen Abrufe an. Keines gibt Zugangsdaten heraus oder löscht etwas.

Anleitung für MCP

konten_listeumsaetze_suchensaldenauszuege_listeverbindungen_listeverbinden_linkverbindung_aktualisierenendkunden_listestatistik

Sandbox

Eine eigene Testbank mit drei Konten, täglich neuen Buchungen und Auszügen als PDF und camt.053. Kostenlos und unbegrenzt nach der Freigabe, zählt nie für die Abrechnung.

Zugänge der Testbank (BLZ 00000000, PIN demo, TAN 123456)

demoNormaler Ablauf mit TAN
demo-appFreigabe in der App, nach 10 Sekunden erteilt
falschFehlerfall: Zugang abgelehnt
abgelaufenEinwilligung läuft sofort ab

Eine Buchung simulieren und damit umsaetze.neu auslösen:

POST /api/v1/sandbox/buchung
curl -s https://finance.agiledeveloper.de/api/v1/sandbox/buchung \
  -H "Authorization: Bearer $AF_KEY" \
  -H "Content-Type: application/json" \
  -d '{"konto_id":"KONTO_ID","betrag_cent":-1299,"verwendungszweck":"Testkauf"}'

Fehler

Fehler kommen immer als { fehler: { code, nachricht, details } }. Der Code entscheidet, ob sich eine Wiederholung lohnt, nie der Text.

zugang_falschtan_falschtan_noetigeinwilligung_abgelaufenbank_nicht_erreichbarbank_lehnt_abnicht_unterstuetztrate_limitlive_bank_gesperrt

Bereit für den ersten Aufruf?

Schlüssel und Sandbox gibt es nach der Prüfung.

Zugang beantragen
Für Entwickler · Agile Finance