API-Dokumentation - Bank-Statement-Conversion
API-Referenz

Bank Statement Conversion API

Fügen Sie die Kontoauszugs-Konvertierung mit einem klaren Upload-, Status- und Download-Ablauf hinzu.

Authentifizierung Upload-Endpunkt Workflow-Endpunkte
api.bsc / v1
Basis-URL
https://bank-statement-conversion.com/api
Workflow-Endpunkte
POST/uploadUpload-Endpunkt
GET/conversion-status/{jobId}Status-Endpunkt
GET/download/{downloadToken}Download-Endpunkt

Überblick

Die Bank Statement Conversion API richtet sich an Entwickler, die Konvertierung in ihre eigene App integrieren möchten. Sie beschreibt den öffentlichen Ablauf: optional Kapazität prüfen, Dateien hochladen, Jobstatus abfragen und fertige Ergebnisse mit dem zurückgegebenen Token herunterladen.

Diese Referenz ist bewusst auf den öffentlichen Konvertierungsablauf beschränkt.

Schnellstart

Schritt 1

API-Token erstellen

Erstellen Sie ein Token im Dashboard und senden Sie es als Authorization: Bearer YOUR_API_TOKEN.

Schritt 2

Datei hochladen

Senden Sie POST an /api/upload mit statement[], format und optionalen Einstellungen.

Schritt 3

Jobstatus abfragen

Verwenden Sie die zurückgegebene jobId mit /api/conversion-status/{jobId}, bis eine Vorschau download_token enthält.

Schritt 4

Ergebnis herunterladen

Rufen Sie /api/download/{downloadToken} auf und speichern Sie die binäre Antwort als konvertierte Datei.

Authentifizierung

API-Token-Authentifizierung

Alle API-Anfragen müssen ein API-Token enthalten. Tokens können im Dashboard im Bereich API Tokens erstellt werden.

API-Token erstellen

  1. Melden Sie sich an
  2. Öffnen Sie den Bereich API Tokens im Dashboard
  3. Klicken Sie auf "Create New Token" und vergeben Sie einen Namen
  4. Kopieren und speichern Sie das Token sicher. Es wird nur einmal angezeigt.

API-Token verwenden

Fügen Sie das API-Token im Authorization-Header ein:

Authorization: Bearer YOUR_API_TOKEN

KI-Agenten

API mit KI-Agenten verwenden

KI-Tools können denselben öffentlichen Konvertierungsablauf wie Entwickler integrieren. Verwenden Sie das OpenAPI-Schema, LLM-Discovery-Dateien oder den MCP-Endpunkt, damit Agenten wissen, welche Konvertierungsendpunkte sie aufrufen sollen und welche Aktionen eine Bestätigung benötigen.

Agenten-Discovery

/api/openapi.json/llms.txt/llms-full.txt/mcp/bank-statement-conversion
  • Verwenden Sie /api/openapi.json für schemafähige Tools wie ChatGPT Actions oder eigene Agent Builder.
  • Verwenden Sie /llms.txt und /llms-full.txt, um Agenten den kanonischen Produkt- und API-Kontext zu geben.
  • Verwenden Sie /mcp/bank-statement-conversion für MCP-kompatible Agenten-Clients, die Remote-MCP-Server unterstützen.

Einmalige Token-Einrichtung

  1. Melden Sie sich einmal an und erstellen Sie im Dashboard ein API-Token.
  2. Lassen Sie alle Konvertierungsberechtigungen aktiviert, außer Sie möchten ein eingeschränktes Token.
  3. Setzen Sie das Token als BSC_API_TOKEN in der Umgebung des MCP-Clients.
  4. Widerrufen Sie das Token im Dashboard, wenn der Agentenzugriff enden soll.

Codex, Claude, Cursor und andere KI-Clients verbinden

Alle MCP-kompatiblen KI-Clients verwenden denselben Remote-Endpunkt und Bearer-Token. Speichern Sie das Token in einer Umgebungsvariable, nicht in Prompts oder Quellcode.

Remote-MCP-Endpunkt
https://bank-statement-conversion.com/mcp/bank-statement-conversion
Authentifizierungs-Header
Authorization: Bearer YOUR_API_TOKEN
Codex-Einrichtung

Fügen Sie diesen Servereintrag zu Ihrer Codex-Konfiguration hinzu.

Codex MCP configtoml
[mcp_servers.bank_statement_conversion]
url = "https://bank-statement-conversion.com/mcp/bank-statement-conversion"
bearer_token_env_var = "BSC_API_TOKEN"

Setzen Sie das Token in Ihrer Shell oder Systemumgebung und starten Sie den KI-Client neu.

Token environment variablebash
export BSC_API_TOKEN="YOUR_API_TOKEN_HERE"
Andere KI-Clients
  • Claude, Cursor und andere MCP-Clients sollten dieselbe Endpunkt-URL und denselben Authorization-Bearer-Token verwenden.
  • ChatGPT Actions und eigene Agent Builder sollten /api/openapi.json statt MCP verwenden, wenn sie ein OpenAPI-Schema benötigen.
  • Verwenden Sie /llms.txt und /llms-full.txt als Produktkontext für Agents, die Wissensdateien unterstützen.

Token-Berechtigungen mit Scope

account:statusconversion:uploadconversion:readconversion:download

Workflow-Endpunkte

Dies sind die einzigen Endpunkte, die Sie zum Hinzufügen der Dokumentkonvertierung benötigen.

EndpunktMethodeBeschreibung
/api/user-statusGETOptionale Vorabprüfung für Credits, Seitenkontingent und Abonnement
/api/uploadPOSTBankauszüge zur Konvertierung hochladen
/api/conversion-status/{jobId}GETStatus eines Konvertierungsjobs prüfen
/api/download/{downloadToken}GETFertige Konvertierung mit dem zurückgegebenen Token herunterladen

Kontostatus-Endpunkt

GET /api/user-status

Verwenden Sie diesen optionalen Endpunkt vor dem Upload, wenn Ihre App prüfen muss, ob das API-Token über Credits, Seitenkontingent oder bezahlten Zugriff verfügt.

Nützliche Antwortfelder

FeldTypBeschreibung
remaining_creditsintegerVerfügbare Credits für kreditbasierte Konvertierungen.
remaining_daily_pagesintegerVerbleibendes tägliches Seitenkontingent des authentifizierten Nutzers.
remaining_premium_pagesintegerVerbleibendes monatliches Premium-Seitenkontingent des aktiven Plans.
plan_typestringDer effektive Abonnementplan des API-Tokens.

Beispielantwort

JSON-Antwortjson
Kopieren Sie diese Struktur für clientseitiges Parsing und Fehlerbehandlung.
{
  "success": true,
  "remaining_credits": 42,
  "remaining_daily_pages": 100,
  "remaining_premium_pages": 950,
  "plan_type": "premium"
}

Upload-Endpunkt

POST /api/upload

Mit diesem Endpunkt laden Sie Bankauszüge zur Konvertierung hoch. Die Konvertierung läuft asynchron; Sie erhalten eine Job-ID für spätere Statusabfragen.

Unterstützte Eingabeformate

AnwendungsfallFormateErweiterungenHinweise
StandardkonvertierungenPDF, JPG/JPEG, PNG, TIFF/TIF, CSV, XLS/XLSX, OFX, QBO, QFX, 940, STA, MT940, MT940X, XML, CAMT.053.pdf, .jpg, .jpeg, .png, .tiff, .tif, .csv, .xls, .xlsx, .ofx, .qbo, .qfx, .940, .sta, .mt940, .mt940x, .xml, .camt053Für die Konvertierung von Bankauszügen, Rechnungen und Belegen.
CSV-BereinigungCSV, XLS, XLSX.csv, .xls, .xlsxNur verwenden, wenn format csv_clean ist.
Zahlungsdatei-GenerierungCSV, XLS, XLSX.csv, .xls, .xlsxFür CSV- oder Excel-Zahlungszeilen, die bankfertige ACH/NACHA-, CPA005-, SEPA XML-, BACS-, ABA- oder NZ-Zahlungsdateien erzeugen.

Unterstützte Ausgabeformate

document_typeDokumentZulässige format-Werte
bank_statementBankauszug
csvexceljsonqb_onlineqb_desktopxeroofxofx_legacyqfxmt940mt940_moneybirdcamt053camt053_legacycamt053_moneybirdcamt053_netsuitecamt053_sap_v2camt053_sap_v8camt053_business_centralcamt053_datevcamt053_afascamt053_twinfieldtally_xmlbai2bai2_netsuitebai2_sapbai2_bank_xsagesage_cloudsage_intacctmyobdatevdatev_accountingcsv_clean
invoiceRechnung
csvexceljsonqb_onlineqb_desktopubl_xmlubl_peppolxrechnung_ublzugferd_pdffactur_x_pdf
receiptBeleg
csvexceljson
payment_fileBankzahlungsdatei
payment_nachapayment_cpa005payment_sepa_pain001payment_bacspayment_abapayment_nz

Anfrageparameter

ParameterTypErforderlichBeschreibung
formatstringJaAusgabeformat. Verwenden Sie einen der oben aufgeführten zulässigen format-Werte für den gewählten document_type.
document_typestringNeinDokumentkategorie: bank_statement, invoice, receipt oder payment_file. Standard: bank_statement.
statementfile arrayJaZu konvertierende Dateien. Senden Sie eine oder mehrere Dateien als statement[].
separate_debit_creditbooleanNeinOb Soll- und Haben-Spalten getrennt werden. Standard: false.
combine_filesbooleanNeinOb mehrere Dateien zu einer Ausgabe kombiniert werden. Standard: false.

Beispielantwort

JSON-Antwortjson
Kopieren Sie diese Struktur für clientseitiges Parsing und Fehlerbehandlung.
{
  "stage": "pending",
  "jobId": "5f3a7d8c-8a91-4a2e-9d3b-4c84f0636c12"
}

Status-Endpunkt

GET /api/conversion-status/{jobId}

Mit diesem Endpunkt prüfen Sie den Status eines Konvertierungsjobs. Fragen Sie ihn ab, bis der Job abgeschlossen ist.

Pfadparameter

ParameterTypBeschreibung
jobIdstringDie vom Upload-Endpunkt zurückgegebene Job-ID

Beispielantwort: ausstehend

JSON-Antwortjson
Kopieren Sie diese Struktur für clientseitiges Parsing und Fehlerbehandlung.
{
  "stage": "processing",
  "success": false,
  "previews": []
}

Beispielantwort: abgeschlossen

JSON-Antwortjson
Kopieren Sie diese Struktur für clientseitiges Parsing und Fehlerbehandlung.
{
  "success": true,
  "previews": [
    {
      "file_name": "bank_statement.pdf",
      "format": "CSV",
      "download_token": "Y8Jm7qVf9sR2kP6nL4xA0bT3cD5eF1gH",
      "partial_conversion": false,
      "credits_used": 1
    }
  ],
  "failed_files": [],
  "remaining_credits": 41,
  "remaining_premium_pages": 949,
  "remaining_daily_pages": 99
}

Beispielantwort: fehlgeschlagen

JSON-Antwortjson
Kopieren Sie diese Struktur für clientseitiges Parsing und Fehlerbehandlung.
{
  "stage": "complete",
  "success": false,
  "error": "An error occurred during the conversion process.",
  "message": "The uploaded file could not be processed.",
  "previews": []
}

Download-Endpunkt

GET /api/download/{downloadToken}

Verwenden Sie den download_token aus einer abgeschlossenen Statusantwort. Erstellen Sie Download-Tokens nicht selbst.

Pfadparameter

ParameterTypBeschreibung
downloadTokenstringDer download_token, der für eine konvertierte Datei in der Statusantwort zurückgegeben wird.

Beispielanfrage

Download mit cURLbash
Im Terminal ausführen, nachdem Token und Download-Token ersetzt wurden.
curl -L \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -o converted_statement.csv \
  "https://bank-statement-conversion.com/api/download/Y8Jm7qVf9sR2kP6nL4xA0bT3cD5eF1gH"

Beispielantwort

200 OK
Gibt die konvertierte Datei als binären Download mit Content-Disposition: attachment zurück. Die Dateiendung hängt vom gewünschten Ausgabeformat ab, z. B. .csv, .xlsx, .qbo, .ofx, .xml, .json, .ach, .txt oder .aba.

Beispiel-Antwortheader

Antwortheaderhttp
Der Download-Endpunkt gibt einen Dateistream statt eines JSON-Bodys zurück.
HTTP/1.1 200 OK
Content-Type: text/csv
Content-Disposition: attachment; filename="bank-statement.csv"
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
}

Fehlerbehandlung

Die API verwendet HTTP-Statuscodes, um Erfolg oder Fehler einer Anfrage anzugeben.

StatuscodeBeschreibung
200 OKDie Anfrage war erfolgreich
400 Bad RequestDie Anfrage war ungültig oder erforderliche Parameter fehlen
401 UnauthorizedAuthentifizierung fehlgeschlagen oder Token ungültig
403 ForbiddenDer authentifizierte Nutzer darf nicht auf die Ressource zugreifen
422 Unprocessable EntityValidierungsfehler sind aufgetreten
500 Internal Server ErrorAuf dem Server ist ein Fehler aufgetreten

Beispiel-Fehlerantworten

401 Nicht autorisiertjson
Kopieren Sie diese Struktur für clientseitiges Parsing und Fehlerbehandlung.
{
  "message": "Unauthenticated."
}
422 Validierungsfehlerjson
Kopieren Sie diese Struktur für clientseitiges Parsing und Fehlerbehandlung.
{
  "message": "The given data was invalid.",
  "errors": {
    "statement": [
      "The statement field is required."
    ],
    "format": [
      "The selected format is invalid."
    ]
  }
}
403 Unzureichende Kapazitätjson
Kopieren Sie diese Struktur für clientseitiges Parsing und Fehlerbehandlung.
{
  "success": false,
  "error": "Insufficient credits or page allowance for this conversion."
}

Limits

Für faire Nutzung gelten Limits abhängig von Ihrem Abonnement:

  • Premium-Nutzer: 100 Anfragen pro Minute
  • Maximale Dateigröße: 100 MB pro Datei
  • Maximal 5 Dateien pro Anfrage

Codebeispiele

Durchgehende Beispiele für den Ablauf: hochladen, abfragen, herunterladen.

1. Hochladen2. Status abfragen3. Herunterladen
JavaScript Beispieljavascript
Verwendet axios und form-data zum Hochladen, Abfragen und Herunterladen der konvertierten Datei.
1// Upload a bank statement file
2const axios = require('axios');
3const FormData = require('form-data');
4const fs = require('fs');
5
6// Your API token from the dashboard
7const API_TOKEN = 'your_api_token_here';
8
9// Create a form data object
10const formData = new FormData();
11formData.append('document_type', 'bank_statement');
12formData.append('format', 'csv');
13formData.append('statement[]', fs.createReadStream('bank_statement.pdf'));
14formData.append('separate_debit_credit', 'true');
15formData.append('combine_files', 'false');
16
17// Make the API request
18const BASE_URL = 'https://bank-statement-conversion.com/api';
19
20axios.post(`${BASE_URL}/upload`, formData, {
21  headers: {
22    'Authorization': `Bearer ${API_TOKEN}`,
23    ...formData.getHeaders()
24  }
25})
26.then(response => {
27  const jobId = response.data.jobId;
28  console.log(`Conversion job started with ID: ${jobId}`);
29
30  // Poll for job status
31  checkJobStatus(jobId);
32})
33.catch(error => {
34  console.error('Error uploading file:', error.response ? error.response.data : error.message);
35});
36
37// Function to check job status
38function checkJobStatus(jobId) {
39  axios.get(`${BASE_URL}/conversion-status/${jobId}`, {
40    headers: {
41      'Authorization': `Bearer ${API_TOKEN}`
42    }
43  })
44  .then(response => {
45    const data = response.data;
46    console.log('Job stage:', data.stage);
47
48    if (data.success && data.previews && data.previews.length > 0) {
49      const downloadToken = data.previews[0].download_token;
50      downloadFile(`${BASE_URL}/download/${downloadToken}`);
51    } else if (data.stage === 'pending' || data.stage === 'processing') {
52      // Check again after 5 seconds
53      setTimeout(() => checkJobStatus(jobId), 5000);
54    } else {
55      console.error('Conversion failed:', data.error || data.message || data);
56    }
57  })
58  .catch(error => {
59    console.error('Error checking job status:', error.response ? error.response.data : error.message);
60  });
61}
62
63// Function to download the converted file
64function downloadFile(url) {
65  const outputPath = 'converted_statement.csv';
66
67  axios({
68    method: 'get',
69    url: url,
70    responseType: 'stream',
71    headers: {
72      'Authorization': `Bearer ${API_TOKEN}`
73    }
74  })
75  .then(response => {
76    response.data.pipe(fs.createWriteStream(outputPath));
77    console.log(`File downloaded to ${outputPath}`);
78  })
79  .catch(error => {
80    console.error('Error downloading file:', error.message);
81  });
82}