Saldofest · saldofest.de/datenabruf/

Datenabruf: die offene Schnittstelle für den Anbieterwechsel

Fassung 1 der Schnittstelle

Mit einem Schlüssel für den Datenabruf holen Sie oder ein Anbieter, dem Sie ihn geben, den Vollexport Ihres Kontos über eine offene Schnittstelle ab, ohne Anmeldung und ohne Kosten. Sie ist für den Wechsel zu einem anderen Anbieter und für die Übertragung Ihrer Daten in eigene Systeme gedacht (AGB § 7a; Art. 30 Abs. 2 der Verordnung (EU) 2023/2854). Jeder Kunde und jeder Anbieter, dem ein Kunde seinen Schlüssel gibt, bekommt dieselbe Schnittstelle: ohne Vertrag mit uns, ohne Freischaltung und ohne Entgelt.

Der Schlüssel

Den Schlüssel legt der Kontoinhaber in der Anwendung unter Einstellungen · Datenabruf über die Schnittstelle an; dafür fragt sie nach dem Passwort. Er beginnt mit sfd_ und wird genau einmal angezeigt; wir speichern nur eine Prüfsumme. Über jedes Anlegen benachrichtigen wir die Adresse des Kontos per E-Mail. Der Schlüssel gilt, bis Sie ihn widerrufen oder einen neuen anlegen. Ein neues oder zurückgesetztes Passwort widerruft ihn ebenfalls.

Jeder Aufruf außer der Beschreibung trägt ihn in der Kopfzeile Authorization: Bearer sfd_…. Wer den Schlüssel hat, kann den ganzen Vollexport holen: Geben Sie ihn nur weiter, wem Sie Ihre Daten anvertrauen, und widerrufen Sie ihn, wenn der Wechsel abgeschlossen ist.

Die Aufrufe

Adresse: https://app.saldofest.de. Antworten kommen als JSON; ein Fehler trägt error.code, error.message und eine Vorgangsnummer (error.request_id), die Sie uns bei Fragen nennen.

GET /v1/datenabruf: Beschreibung der Schnittstelle (OpenAPI 3.1)

Liefert diese Beschreibung als OpenAPI-Dokument, dazu jede Tabelle des Vollexports mit ihren Spalten (x-saldofest-vollexport). Ohne Schlüssel abrufbar.

POST /v1/datenabruf/vollexport: Vollexport starten

Startet den Vollexport des Kontos, dem der Schlüssel gehört: denselben wie der Knopf „Vollexport (ZIP)“ in der Anwendung. Läuft schon einer, kommt dessen Auftragsnummer zurück, und es entsteht kein zweiter. Höchstens 5 neue Vollexporte je Stunde und Konto, gezählt zusammen mit dem Knopf. Kein Rumpf nötig. Wie beim Knopf geht der Link zusätzlich per E-Mail an die Adresse des Kontos, wenn sie bestätigt ist.

GET /v1/datenabruf/vollexport/{job_id}: Stand eines Vollexports, fertige Teile laden

Fragt, wie weit ein Vollexport ist. Ist er fertig, steht je Teil eine Download-Adresse da, die 5 Minuten gilt; ein neuer Aufruf holt neue. Ein großes Konto kommt in mehreren Teilen (ZIP je Teil). Ein fertiger Vollexport liegt 7 Tage bereit, danach expired. Etwa alle 10 Sekunden fragen genügt.

Ein Beispiel

Vollexport starten:

curl -X POST -H "Authorization: Bearer sfd_…" https://app.saldofest.de/v1/datenabruf/vollexport

Die Antwort nennt die Auftragsnummer. Mit ihr fragen Sie, bis der Stand completed heißt:

curl -H "Authorization: Bearer sfd_…" https://app.saldofest.de/v1/datenabruf/vollexport/<job_id>

Dann laden Sie jeden Teil von seiner download_url. Jede Adresse gilt 5 Minuten; eine neue Abfrage gibt neue. Der fertige Vollexport liegt 7 Tage bereit.

Was Sie bekommen

Den Vollexport: eine ZIP-Datei je Teil mit Tabellen als CSV (UTF-8, Semikolon), Einstellungen als JSON, Buchungsstapeln im DATEV-Format (EXTF), Begleitblättern und Rechnungen als PDF und den Eingangsrechnungen im Original. Im Archiv beschreiben LIESMICH.txt und index.xml jede Tabelle und jede Spalte; welche Daten dazugehören und welche nicht, nennt Anlage 1 der AGB (Teil C) abschließend. Dieselbe Beschreibung für Programme liefert GET https://app.saldofest.de/v1/datenabruf als OpenAPI-Dokument.

Grenzen