SmartKontoauszug

REST-API

Kontoauszüge per API umwandeln

Die REST-API nimmt PDF-Kontoauszüge entgegen, liest die Buchungen aus und liefert sie in jedem Exportformat zurück. Sie nutzt dieselben Credits wie das Dashboard und eignet sich für Buchhaltungssoftware, Kanzlei-Workflows und eigene Skripte.

Zuletzt aktualisiert:

API-Schlüssel erstellen Endpunkte ansehen
Schritt 1

Schlüssel erstellen

Im Dashboard unter API legt der Teaminhaber einen Schlüssel an. Er wird einmal angezeigt und gilt für das Guthaben des Teams.

Schritt 2

PDF hochladen

Ein POST mit der PDF-Datei bucht einen Credit je Seite ab und liefert eine ID zurück. Mehrere Dateien gehen in einem Aufruf.

Schritt 3

Status abfragen und abholen

Sobald der Status extractionCompletedAt enthält, laden Sie den Export im gewünschten Format herunter.

Authentifizierung

Ein Header, kein Login

Jede Anfrage trägt den API-Schlüssel als Bearer-Token im Authorization-Header. Der Schlüssel gehört zum Team, das ihn erstellt hat: Hochgeladene Dokumente erscheinen im Dashboard des Teams, verbrauchte Credits kommen aus dessen Guthaben. Schlüssel erstellen und widerrufen Teaminhaber im Dashboard unter API; ein widerrufener Schlüssel funktioniert sofort nicht mehr. 

Authorization: Bearer ska_IHR_SCHLUESSEL

Basis-URL: https://smartkontoauszug.ch. Alle Antworten ausser den Downloads sind JSON. Zeitstempel sind ISO 8601 in UTC.

Endpunkte

Fünf Aufrufe für den ganzen Ablauf

Hochladen, Status abfragen, herunterladen, auflisten, löschen. Die Endpunkte sind dieselben, die das Dashboard verwendet; nur die Authentifizierung unterscheidet sich.

POST/api/v1/extractions

Dokumente hochladen

Nimmt eine oder mehrere PDF-Dateien als multipart/form-data entgegen, bucht einen Credit je Seite ab und startet die Umwandlung. Reicht das Guthaben nicht, antwortet der Endpunkt mit 400 und nennt in meta den Bedarf und das verfügbare Guthaben; es wird dann nichts abgebucht.

Parameter

filesBody, multipart/form-data
Eine PDF-Datei je Feld mit Content-Type application/pdf. Höchstens 20 Dateien, 10 MB je Datei, 25 MB insgesamt und 300 Seiten je Datei. Passwortgeschützte PDFs werden abgelehnt.

Anfrage 

curl -X POST https://smartkontoauszug.ch/api/v1/extractions \
  -H "Authorization: Bearer ska_IHR_SCHLUESSEL" \
  -F "files=@kontoauszug-2026-09.pdf;type=application/pdf"

Antwort

[
  { "id": "019a3f6c-7b2e-7c1d-9f3a-5d6e7f8a9b0c", "fileName": "kontoauszug-2026-09.pdf" }
]
GET/api/v1/extractions/{id}

Status abfragen

Liefert den Verarbeitungsstand eines Dokuments. Drei Zustände sind möglich: In Arbeit, solange weder extractionCompletedAt noch extractionFailedAt gesetzt ist. Fertig, sobald extractionCompletedAt einen Zeitstempel enthält. Fehlgeschlagen, wenn extractionFailedAt gesetzt ist; die Credits sind dann bereits gutgeschrieben.

Parameter

idPfad
Die ID aus der Upload-Antwort.

Anfrage 

curl https://smartkontoauszug.ch/api/v1/extractions/019a3f6c-7b2e-7c1d-9f3a-5d6e7f8a9b0c \
  -H "Authorization: Bearer ska_IHR_SCHLUESSEL"

Antwort

{
  "id": "019a3f6c-7b2e-7c1d-9f3a-5d6e7f8a9b0c",
  "fileName": "kontoauszug-2026-09.pdf",
  "totalPages": 3,
  "extractionStartedAt": "2026-10-30T09:12:04.000Z",
  "extractionFailedAt": null,
  "extractionCompletedAt": "2026-10-30T09:12:41.000Z",
  "errorReportedAt": null,
  "rating": null
}
GET/api/v1/extractions/{id}/download

Export herunterladen

Gibt die Buchungen im gewünschten Format als Datei zurück; der Dateiname steht im Content-Disposition-Header. Vor Abschluss der Umwandlung antwortet der Endpunkt mit 404.

Parameter

formatQuery, Pflicht
Einer der Werte CSV, Excel, XML, JSON.

Anfrage 

curl "https://smartkontoauszug.ch/api/v1/extractions/019a3f6c-7b2e-7c1d-9f3a-5d6e7f8a9b0c/download?format=CSV" \
  -H "Authorization: Bearer ska_IHR_SCHLUESSEL" \
  -o kontoauszug-2026-09.csv

Antwort

HTTP/1.1 200 OK
Content-Type: text/csv; charset=utf-8
Content-Disposition: attachment; filename="kontoauszug-2026-09.csv"
GET/api/v1/extractions

Dokumente auflisten

Listet die Dokumente des Teams aus den letzten sieben Tagen, neueste zuerst, inklusive der Uploads aus dem Dashboard. Zusätzlich zu den Statusfeldern enthält jeder Eintrag creditsUsed, statementDate und accountIban, sobald die Umwandlung fertig ist.

Parameter

limitQuery, optional
Höchstzahl der Einträge, positive ganze Zahl.

Anfrage 

curl "https://smartkontoauszug.ch/api/v1/extractions?limit=50" \
  -H "Authorization: Bearer ska_IHR_SCHLUESSEL"

Antwort

[
  {
    "id": "019a3f6c-7b2e-7c1d-9f3a-5d6e7f8a9b0c",
    "fileName": "kontoauszug-2026-09.pdf",
    "totalPages": 3,
    "creditsUsed": 3,
    "createdBy": "buchhaltung@example.com",
    "extractionCompletedAt": "2026-10-30T09:12:41.000Z",
    "statementDate": "2026-09-01",
    "accountIban": "DE02120300000000202051",
    "…": "…"
  }
]
DELETE/api/v1/extractions/{id}

Dokument löschen

Entfernt PDF und extrahierte Daten sofort statt nach sieben Tagen. Während der Verarbeitung ist das Löschen gesperrt und antwortet mit 403. Credits werden dabei nicht erstattet.

Parameter

idPfad
Die ID aus der Upload-Antwort.

Anfrage 

curl -X DELETE https://smartkontoauszug.ch/api/v1/extractions/019a3f6c-7b2e-7c1d-9f3a-5d6e7f8a9b0c \
  -H "Authorization: Bearer ska_IHR_SCHLUESSEL"

Antwort

HTTP/1.1 204 No Content

Fehler

Statuscodes und Fehlerformat

Fehler kommen als JSON mit statusCode und statusMessage. Validierungsfehler tragen zusätzlich ein Feld data mit einem Eintrag je Problem.

400Validierungsfehler
Fehlende Datei, falsches Format, zu viele Seiten, ungültige Parameter oder zu wenig Guthaben. Das Feld data listet jeden Fehler mit property und message; bei fehlendem Guthaben enthält meta die Werte required und available.
401Nicht authentifiziert
Der Authorization-Header fehlt, der Schlüssel ist unbekannt, widerrufen oder die erstellende Person hat das Team verlassen.
403Nicht erlaubt
Der Endpunkt ist nicht per API-Schlüssel erreichbar, oder ein Dokument soll während der Verarbeitung gelöscht werden.
404Nicht gefunden
Die ID gehört nicht zum Team, das Dokument wurde gelöscht, oder der Download wurde vor Abschluss der Umwandlung angefragt.
429Zu viele Anfragen
Mehr als 300 Anfragen pro Minute mit einem Schlüssel, oder wiederholt ungültige Schlüssel von derselben Adresse. Warten Sie kurz und wiederholen Sie die Anfrage.

Beispiel: zu wenig Guthaben 

{
  "statusCode": 400,
  "statusMessage": "Bad Request",
  "data": [
    {
      "property": "files",
      "message": "Sie haben nicht genügend Credits. …",
      "meta": { "required": 12, "available": 4 }
    }
  ]
}

Limits und Aufbewahrung

Was Sie einplanen sollten

Anfragen
300 pro Minute und Schlüssel
Upload
20 Dateien je Aufruf, 10 MB je Datei, 25 MB insgesamt, 300 Seiten je Datei.
Kosten
Ein Credit je Seite, CHF 0.25, wie im Dashboard. Fehlgeschlagene Umwandlungen werden automatisch gutgeschrieben.
Aufbewahrung
PDF und Daten werden nach sieben Tagen automatisch gelöscht, auf Wunsch früher per DELETE.

Häufige Fragen

Häufige Fragen zur API

Kostet die API extra?

Nein. Jede Seite kostet einen Credit, also CHF 0.25, genau wie im Dashboard. Es gibt keinen Aufpreis, keine Grundgebühr und kein Abo. Die 5 Gratis-Credits der Registrierung gelten auch für API-Aufrufe.

Welche Formate liefert die API?

Dieselben wie der Download im Dashboard: CSV (.csv), Excel (.xlsx), XML (.xml), JSON (.json). Das Format wählen Sie beim Abruf über den Parameter format.

Wie lange bleiben hochgeladene Dateien gespeichert?

Sieben Tage. Danach werden PDF und extrahierte Daten automatisch gelöscht. Wenn Sie die Daten nach dem Download sofort entfernen möchten, rufen Sie den DELETE-Endpunkt auf.

Gibt es Webhooks?

Noch nicht. Fragen Sie den Status per GET ab, am besten alle fünf Sekunden. Die Dauer hängt von der Seitenzahl ab; sobald extractionCompletedAt gesetzt ist, steht der Download bereit.

Wer kann API-Schlüssel erstellen?

Teaminhaber, im Dashboard unter API. Ein Schlüssel gehört zum Team: Hochgeladene Dokumente und verbrauchte Credits erscheinen dort wie Uploads aus dem Dashboard. Verlässt die Person, die den Schlüssel erstellt hat, das Team, erlischt der Schlüssel.

Was passiert, wenn eine Umwandlung fehlschlägt?

Die Credits für das Dokument werden automatisch gutgeschrieben. Der Status-Endpunkt liefert dann einen Zeitstempel in extractionFailedAt, und Sie können das Dokument erneut hochladen.

Welche Limits gelten?

Pro Schlüssel 300 Anfragen pro Minute. Pro Upload höchstens 20 Dateien, 10 MB je Datei, 25 MB insgesamt und 300 Seiten je Datei. Ein Team kann bis zu 10 aktive Schlüssel haben.

Den ersten Kontoauszug per API umwandeln

Konto anlegen, Schlüssel erstellen, PDF hochladen. Die ersten 5 Seiten sind gratis.

API-Schlüssel erstellen Preise ansehen
  • 5 Seiten kostenlos · kein Abo · DSG- & DSGVO-konform