Änderungsprotokoll – API-Doku

Versionierung

Neue Endpunkte, neue optionale Parameter und neue Felder in Antworten sind keine inkompatiblen Änderungen.
Entfernte oder umbenannte Felder, geänderte Typen oder Fehlercodes sind inkompatibel. Sie erhalten eine neue Version (Datum) und werden hier vorher angekündigt.
Neue Ereignistypen können jederzeit hinzukommen. Webhook-Empfänger sollten unbekannte type-Werte ignorieren.

2026-11-04

Recherche, Gläubiger-KI, Aktivitäten und neue Ereignisse

Keine inkompatiblen Änderungen; DebtFlow-Version bleibt 2026-11-01.
Neue Scopes research:read|write, ai:read|write und activity:read|write.
Recherche: /contacts/{id}/address-research, Melderegisteranfragen unter /contacts/{id}/residence-registry-inquiries (kostenpflichtig, Schutz vor Doppelbeauftragung mit 409 inquiry_in_progress) und Social-Media-Profile unter /contacts/{id}/social-profiles.
Gläubiger-KI: POST /debts/{id}/recommendations erzeugt eine Handlungsempfehlung aus den gespeicherten Daten (begrenztes Kontingent, 429 ai_rate_limited / ai_quota_exhausted); Lesen unter /debts/{id}/recommendations und /contacts/{id}/recommendations.
Finanzanalyse eines Kontakts (/contacts/{id}/finances), Kommunikationsprotokoll (/contacts/{id}/communications), Aktivitätsprotokoll über alle Objekte (/activities) und Kennzahlen der Forderungsübersicht (/reports/receivables).
Forderungen enthalten jetzt isTitled und inCourt (auch per PATCH änderbar), Zahlungen das Feld verified; Nachrichten akzeptieren den Typ sms.
Ereignisse debt.overdue, installment.due und installment.missed werden jetzt ausgelöst (einmal je Vorfall); neu sind installment_plan.updated, installment_plan.deleted, communication.created, residence_registry_inquiry.created und recommendation.created. debt.phase_changed kommt jetzt auch aus dem automatischen Mahnlauf und dem Briefversand.
Zustellprotokoll der Webhooks: Antworten werden auf 200 Zeichen gekürzt, sensible Header-Werte und Tokens entfernt.
Webhook-Endpunkte: neues Feld payloadFormat (json Standard, text = gleicher Body als text/plain, z. B. für die Signaturprüfung in Make).
CORS für /api/v1: jede Origin ohne Credentials (Bearer-Token), Preflight mit OPTIONS. Token- und Widerrufs-Endpunkt nur von den Redirect-Origins öffentlicher Apps.
Bankabgleich auf Rechnungen verlangt zusätzlich invoices:write, auf Belege receipts:write. Verarbeitete Ereignisse (/events) werden nach 30 Tagen gelöscht.
Kontakte: GET /contacts mit sort und open; importierte Kontakte und Rechnungen lösen dieselben Ereignisse aus (mit source: "import").
Das Dashboard nutzt für Kontakte, Forderungen, Zahlungen, Ratenpläne, Briefe, Mandanten, Recherche und KI dieselben v1-Endpunkte.
OAuth: PKCE (S256) ist jetzt für alle Apps Pflicht, auch für vertrauliche; Ausnahmen nur nach Prüfung durch DebtFlow. Apps zeigen pkceRequired.
OAuth: Parallele Erneuerungen mit demselben Refresh-Token innerhalb von 30 Sekunden erhalten dasselbe Token-Paar (Gnadenfrist), statt die Token-Kette zu widerrufen.
Die Zustimmungsseite /oauth/authorize lässt sich nicht mehr in fremde Seiten einbetten (frame-ancestors 'none').
Fehlermeldungen (message) auf Deutsch oder Englisch je nach Accept-Language (Standard Englisch), Header Content-Language; die Codes in error sind unverändert.
Kontakte haben das Feld language (de | en) für Mahnungen und Belege, Rechnungen und Angebote das Feld language (Belegsprache).

2026-11-01

API v1

REST-API unter /api/v1 mit OpenAPI-3.1-Beschreibung.
Anmeldung per API-Schlüssel (df_live_…) und OAuth 2.0 mit PKCE und Refresh-Tokens (dfo_…, dfr_…).
Einheitliches Fehlerformat, Cursor-Pagination, Idempotency-Key für POST, Rate-Limits mit X-RateLimit-*-Headern.
Webhooks mit Signatur DebtFlow-Signature und Ereigniskatalog.

Fragen zu Änderungen? Schreiben Sie an [email protected]. Sicherheitslücken bitte nach der Sicherheitsrichtlinie melden.