Dokumentacja API - Bank-Statement-Conversion

API Bank Statement Conversion

Dodaj konwersję z prostym przepływem: przesyłanie, status i pobieranie.

Przegląd

API Bank Statement Conversion jest dla deweloperów, którzy chcą dodać konwersję do własnej aplikacji. Opisuje publiczny przepływ: opcjonalne sprawdzenie pojemności konta, przesłanie plików, odpytywanie statusu zadania i pobranie gotowych wyników zwróconym tokenem.

Ta dokumentacja jest celowo ograniczona do publicznego przepływu konwersji.

Szybki start

Krok 1

Utwórz token API

Wygeneruj token w panelu i wyślij go jako Authorization: Bearer YOUR_API_TOKEN.

Krok 2

Prześlij plik

Wyślij POST do /api/upload z statement[], format i opcjonalnymi ustawieniami.

Krok 3

Sprawdzaj status zadania

Użyj zwróconego jobId z /api/conversion-status/{jobId}, aż podgląd zawiera download_token.

Krok 4

Pobierz wynik

Wyślij GET do /api/download/{downloadToken} i zapisz odpowiedź binarną jako przekonwertowany plik.

Uwierzytelnianie

Uwierzytelnianie tokenem API

Każde żądanie API musi zawierać token API do uwierzytelnienia. Tokeny można tworzyć w panelu konta w sekcji API Tokens.

Jak utworzyć token API

  1. Zaloguj się na konto
  2. Przejdź do sekcji API Tokens w panelu
  3. Kliknij "Create New Token" i podaj nazwę tokena
  4. Skopiuj i bezpiecznie zapisz token. Zostanie pokazany tylko raz.

Używanie tokena API

Umieść token API w nagłówku Authorization żądań:

Authorization: Bearer YOUR_API_TOKEN

Agenci AI

Używanie API z agentami AI

Narzędzia AI mogą integrować się z tym samym publicznym przepływem konwersji co deweloperzy. Użyj schematu OpenAPI, plików odkrywania LLM albo endpointu MCP, aby agenci wiedzieli, które endpointy konwersji wywoływać i które akcje wymagają potwierdzenia.

Odkrywanie dla agentów

/api/openapi.json/llms.txt/llms-full.txt/mcp/bank-statement-conversion
  • Użyj /api/openapi.json dla narzędzi świadomych schematu, takich jak ChatGPT Actions lub własne kreatory agentów.
  • Użyj /llms.txt i /llms-full.txt, aby przekazać agentom kanoniczny kontekst produktu i API.
  • Użyj /mcp/bank-statement-conversion dla klientów agentów zgodnych z MCP, którzy obsługują zdalne serwery MCP.

Jednorazowa konfiguracja tokena

  1. Zaloguj się raz i utwórz token API w panelu.
  2. Pozostaw wszystkie uprawnienia konwersji włączone, chyba że chcesz token ograniczony.
  3. Ustaw token jako BSC_API_TOKEN w środowisku klienta MCP.
  4. Unieważnij token w panelu, gdy dostęp agenta ma zostać zakończony.

Połącz Codex, Claude, Cursor i innych klientów AI

Wszyscy klienci AI zgodni z MCP używają tego samego zdalnego endpointu i tokena bearer. Przechowuj token w zmiennej środowiskowej, nie w promptach ani kodzie źródłowym.

Zdalny endpoint MCP
https://bank-statement-conversion.com/mcp/bank-statement-conversion
Nagłówek uwierzytelniania
Authorization: Bearer YOUR_API_TOKEN
Konfiguracja Codex

Dodaj ten wpis serwera do konfiguracji Codex.

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"

Ustaw token w shellu lub środowisku systemowym, a następnie uruchom ponownie klienta AI.

Token environment variablebash
export BSC_API_TOKEN="YOUR_API_TOKEN_HERE"
Inni klienci AI
  • Claude, Cursor i inni klienci MCP powinni używać tego samego endpointu URL i tokena Authorization bearer.
  • ChatGPT Actions i własne kreatory agentów powinny używać /api/openapi.json zamiast MCP, gdy potrzebują schematu OpenAPI.
  • Użyj /llms.txt i /llms-full.txt jako kontekstu produktu dla agentów obsługujących pliki wiedzy.

Uprawnienia tokena z zakresem

account:statusconversion:uploadconversion:readconversion:download

Endpointy przepływu

To jedyne endpointy potrzebne do dodania konwersji dokumentów do aplikacji.

EndpointMetodaOpis
/api/user-statusGETOpcjonalne sprawdzenie kredytów, limitu stron i planu subskrypcji
/api/uploadPOSTPrześlij wyciągi bankowe do konwersji
/api/conversion-status/{jobId}GETSprawdź status zadania konwersji
/api/download/{downloadToken}GETPobierz ukończoną konwersję tokenem zwróconym w odpowiedzi statusu

Endpoint statusu konta

GET /api/user-status

Użyj tego opcjonalnego endpointu przed przesłaniem, gdy aplikacja musi potwierdzić kredyty, limit stron lub płatny dostęp tokena API.

Przydatne pola odpowiedzi

PoleTypOpis
remaining_creditsintegerKredyty dostępne dla konwersji kredytowych.
remaining_daily_pagesintegerPozostały dzienny limit stron uwierzytelnionego użytkownika.
remaining_premium_pagesintegerPozostały miesięczny limit stron premium dla aktywnego planu.
plan_typestringEfektywny plan subskrypcji dla tokena API.

Przykładowa odpowiedź

Odpowiedź JSONjson
Skopiuj tę strukturę do parsowania po stronie klienta i obsługi błędów.
{
  "success": true,
  "remaining_credits": 42,
  "remaining_daily_pages": 100,
  "remaining_premium_pages": 950,
  "plan_type": "premium"
}

Endpoint przesyłania

POST /api/upload

Ten endpoint pozwala przesłać wyciągi bankowe do konwersji. Proces jest asynchroniczny i otrzymasz ID zadania do późniejszego sprawdzania statusu.

Obsługiwane formaty wejściowe

ZastosowanieFormatyRozszerzeniaUwagi
Standardowe konwersjePDF, 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, .camt053Dla wyciągów bankowych, faktur i paragonów.
Czyszczenie CSVCSV, XLS, XLSX.csv, .xls, .xlsxUżywaj tylko, gdy format to csv_clean.
Generowanie plików płatniczychCSV, XLS, XLSX.csv, .xls, .xlsxUżyj dla wierszy płatności CSV lub Excel, które generują pliki ACH/NACHA, CPA005, SEPA XML, BACS, ABA lub NZ do przeglądu bankowego.

Obsługiwane formaty wyjściowe

document_typeDokumentDozwolone wartości format
bank_statementWyciąg bankowy
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
invoiceFaktura
csvexceljsonqb_onlineqb_desktopubl_xmlubl_peppolxrechnung_ublzugferd_pdffactur_x_pdf
receiptParagon
csvexceljson
payment_fileBankowy plik płatniczy
payment_nachapayment_cpa005payment_sepa_pain001payment_bacspayment_abapayment_nz

Parametry żądania

ParametrTypWymaganeOpis
formatstringTakFormat wyjściowy. Użyj jednej z dozwolonych wartości format dla wybranego document_type.
document_typestringNieKategoria dokumentu: bank_statement, invoice, receipt lub payment_file. Domyślnie: bank_statement.
statementfile arrayTakPliki do konwersji. Wyślij jeden lub więcej plików jako statement[].
conversion_modestringNieTryb konwersji: precision lub fast. Domyślnie precision.
separate_debit_creditbooleanNieCzy rozdzielić kolumny debet i kredyt. Domyślnie: false.
combine_filesbooleanNieCzy połączyć wiele plików w jeden wynik. Domyślnie: false.

Przykładowa odpowiedź

Odpowiedź JSONjson
Skopiuj tę strukturę do parsowania po stronie klienta i obsługi błędów.
{
  "stage": "pending",
  "jobId": "5f3a7d8c-8a91-4a2e-9d3b-4c84f0636c12"
}

Endpoint statusu

GET /api/conversion-status/{jobId}

Ten endpoint pozwala sprawdzić status zadania konwersji. Odpytuj go, aż zadanie zostanie zakończone.

Parametry ścieżki

ParametrTypOpis
jobIdstringID zadania zwrócone przez endpoint uploadu

Przykładowa odpowiedź oczekująca

Odpowiedź JSONjson
Skopiuj tę strukturę do parsowania po stronie klienta i obsługi błędów.
{
  "stage": "processing",
  "success": false,
  "previews": []
}

Przykładowa odpowiedź ukończona

Odpowiedź JSONjson
Skopiuj tę strukturę do parsowania po stronie klienta i obsługi błędów.
{
  "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
}

Przykładowa odpowiedź nieudana

Odpowiedź JSONjson
Skopiuj tę strukturę do parsowania po stronie klienta i obsługi błędów.
{
  "stage": "complete",
  "success": false,
  "error": "An error occurred during the conversion process.",
  "message": "The uploaded file could not be processed.",
  "previews": []
}

Endpoint pobierania

GET /api/download/{downloadToken}

Użyj download_token zwróconego w ukończonej odpowiedzi statusu. Nie twórz tokenów pobierania samodzielnie.

Parametry ścieżki

ParametrTypOpis
downloadTokenstringdownload_token zwrócony dla przekonwertowanego pliku w odpowiedzi statusu.

Przykładowe żądanie

Pobierz przez cURLbash
Uruchom w terminalu po zastąpieniu tokena i tokena pobierania.
curl -L \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -o converted_statement.csv \
  "https://bank-statement-conversion.com/api/download/Y8Jm7qVf9sR2kP6nL4xA0bT3cD5eF1gH"

Przykładowa odpowiedź

200 OK
Zwraca przekonwertowany plik jako pobranie binarne z Content-Disposition: attachment. Rozszerzenie zależy od żądanego formatu, np. .csv, .xlsx, .qbo, .ofx, .xml, .json, .ach, .txt lub .aba.

Przykładowe nagłówki odpowiedzi

Nagłówki odpowiedzihttp
Endpoint pobierania zwraca strumień pliku zamiast ciała JSON.
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
}

Obsługa błędów

API używa standardowych kodów HTTP do wskazania powodzenia lub niepowodzenia żądań.

Kod statusuOpis
200 OKŻądanie zakończyło się powodzeniem
400 Bad RequestŻądanie było nieprawidłowe lub brakowało wymaganych parametrów
401 UnauthorizedUwierzytelnianie nie powiodło się lub token jest nieprawidłowy
403 ForbiddenUwierzytelniony użytkownik nie ma uprawnień do zasobu
422 Unprocessable EntityWystąpiły błędy walidacji
500 Internal Server ErrorWystąpił błąd serwera

Przykładowe odpowiedzi błędów

401 Brak autoryzacjijson
Skopiuj tę strukturę do parsowania po stronie klienta i obsługi błędów.
{
  "message": "Unauthenticated."
}
422 Błąd walidacjijson
Skopiuj tę strukturę do parsowania po stronie klienta i obsługi błędów.
{
  "message": "The given data was invalid.",
  "errors": {
    "statement": [
      "The statement field is required."
    ],
    "format": [
      "The selected format is invalid."
    ]
  }
}
403 Niewystarczająca pojemnośćjson
Skopiuj tę strukturę do parsowania po stronie klienta i obsługi błędów.
{
  "success": false,
  "error": "Insufficient credits or page allowance for this conversion."
}

Limity

Aby zapewnić uczciwe użycie API, limity zależą od planu subskrypcji:

  • Użytkownicy premium: 100 żądań na minutę
  • Maksymalny rozmiar pliku: 100MB na plik
  • Maksymalnie 5 plików na żądanie

Przykłady kodu

Przykłady end-to-end przepływu konwersji: przesłanie, odpytywanie, pobranie.

1. Prześlij2. Sprawdzaj status3. Pobierz
JavaScript przykładjavascript
Używa axios i form-data do przesyłania, odpytywania i pobierania pliku.
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}