Schnellstart für Entwickler

In fünf Minuten holen Sie die ersten Umsätze aus der Testbank. Alle Beispiele laufen so, wie sie hier stehen. Sie brauchen nur einen freigegebenen Arbeitsbereich und einen Sandbox-Schlüssel.

1. Schlüssel anlegen

Legen Sie unter Entwickler, API-Schlüssel in der Umgebung Sandbox einen Schlüssel an und merken Sie ihn sich in einer Variablen. Schlüssel der Sandbox beginnen mit agile_finance_test_.

export AF_KEY="agile_finance_test_..."
export AF="https://finance.agiledeveloper.de/api/v1"

2. Endkunden anlegen

Ein Endkunde ist ein Kunde Ihrer Plattform. extern_ref ist Ihre eigene Kennung und je Umgebung eindeutig.

curl -s "$AF/endkunden" \
  -H "Authorization: Bearer $AF_KEY" \
  -H "Content-Type: application/json" \
  -d '{"extern_ref":"kunde-4711","name":"Muster GmbH"}'

Die Antwort enthält die id, die Sie gleich brauchen.

3. Verbinden-Link erzeugen

Der Link führt Ihren Endkunden durch Einwilligung, Bank und TAN. Er gilt 30 Minuten und nur einmal. In der Sandbox darf der Rücksprung auch auf localhost zeigen.

curl -s "$AF/verbinden" \
  -H "Authorization: Bearer $AF_KEY" \
  -H "Content-Type: application/json" \
  -d '{"endkunde_extern_ref":"kunde-4711","quelle":"testbank","zurueck_url":"http://localhost:3000/fertig"}'

4. Testbank verbinden

Öffnen Sie die url aus der Antwort im Browser, stimmen Sie zu und melden Sie sich an: Zugang demo und demo, TAN 123456. Danach springt die Strecke zurück auf Ihre zurueck_url mit verbindung und status.

5. Konten und Umsätze lesen

Beträge kommen in ganzen Cent, Soll ist negativ. Die Liste blättert mit dem Cursor aus naechster_cursor.

curl -s "$AF/konten" -H "Authorization: Bearer $AF_KEY"

curl -s "$AF/konten/KONTO_ID/umsaetze?limit=20&q=miete" \
  -H "Authorization: Bearer $AF_KEY"

6. Buchung simulieren und Webhook empfangen

Nur in der Sandbox: Eine simulierte Buchung löst das Ereignis umsaetze.neu aus. Webhooks legen Sie unter Entwickler an, jede Zustellung ist mit dem Signatur-Geheimnis signiert.

curl -s "$AF/sandbox/buchung" \
  -H "Authorization: Bearer $AF_KEY" \
  -H "Content-Type: application/json" \
  -d '{"konto_id":"KONTO_ID","betrag_cent":-1299,"verwendungszweck":"Testkauf"}'

7. Exportieren

Als camt053, mt940, csv oder pdf. Exporte sind von uns erzeugt und kein Bankbeleg.

curl -s "$AF/konten/KONTO_ID/export?format=camt053" \
  -H "Authorization: Bearer $AF_KEY" -o umsaetze.xml

Fehler und Grenzen

Fehler haben immer die Form {"fehler":{"code","nachricht","details"}}. Ohne Freigabe antwortet die API mit 403 onboarding_offen. Schreibende Anfragen dürfen einen Idempotency-Key tragen, das Limit steht in den Kopfzeilen.

Weiter

Alle Routen stehen in der API-Referenz. Für Claude und ChatGPT gibt es die MCP-Anleitung.