Datenabruf: die offene Schnittstelle für den Anbieterwechsel
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.
200: Das OpenAPI-Dokument (JSON).429: Zu viele Anfragen (rate_limited);error.details.warte_snennt die Sekunden bis zum nächsten Versuch.
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.
202: Ein neuer Vollexport läuft:{ "job_id": "…" }.200: Es lief schon einer; seine Auftragsnummer:{ "job_id": "…" }.401: Kein oder ein ungültiger, widerrufener Schlüssel (not_authenticated).409: Ein zweiter Start im selben Augenblick (export_in_progress); in ein paar Sekunden erneut.429: Zu viele Anfragen (rate_limited);error.details.warte_snennt die Sekunden bis zum nächsten Versuch.
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.
200:{ "status": "running" },{ "status": "completed", "download_url": "…", "teile": [{ "teil": 1, "download_url": "…" }] },{ "status": "failed", "code": "…" }oder{ "status": "expired" }.401: Kein oder ein ungültiger, widerrufener Schlüssel (not_authenticated).404: Diese Auftragsnummer gehört nicht zu diesem Konto (not_found).429: Zu viele Anfragen (rate_limited);error.details.warte_snennt die Sekunden bis zum nächsten Versuch.
Ein Beispiel
Vollexport starten:
curl -X POST -H "Authorization: Bearer sfd_…" https://app.saldofest.de/v1/datenabruf/vollexportDie 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
- Die Schnittstelle gilt, solange das Konto besteht: während der Laufzeit, im Übergangszeitraum eines Wechsels und bis zur Löschung nach § 8 der AGB. Ein gesperrtes Konto öffnet auch der Schlüssel nicht.
- Höchstens 30 Anfragen je Minute und Adresse.
- Ein neuer Vollexport läuft je Konto nur einmal zur selben Zeit; die Zahl neuer Vollexporte je Stunde nennt der Aufruf oben, und sie gilt zusammen mit dem Knopf in der Anwendung.
- Die Schnittstelle liest; sie ändert nichts am Konto. Für alles andere beim Wechsel helfen wir auf Anfrage an support@saldofest.de (§ 7a Abs. 3 der AGB).