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.
https://bank-statement-conversion.com/apiSzybki start
Utwórz token API
Wygeneruj token w panelu i wyślij go jako Authorization: Bearer YOUR_API_TOKEN.
Prześlij plik
Wyślij POST do /api/upload z statement[], format i opcjonalnymi ustawieniami.
Sprawdzaj status zadania
Użyj zwróconego jobId z /api/conversion-status/{jobId}, aż podgląd zawiera download_token.
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
- Zaloguj się na konto
- Przejdź do sekcji API Tokens w panelu
- Kliknij "Create New Token" i podaj nazwę tokena
- 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_TOKENAgenci 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.jsondla narzędzi świadomych schematu, takich jak ChatGPT Actions lub własne kreatory agentów. - Użyj
/llms.txti/llms-full.txt, aby przekazać agentom kanoniczny kontekst produktu i API. - Użyj
/mcp/bank-statement-conversiondla klientów agentów zgodnych z MCP, którzy obsługują zdalne serwery MCP.
Jednorazowa konfiguracja tokena
- Zaloguj się raz i utwórz token API w panelu.
- Pozostaw wszystkie uprawnienia konwersji włączone, chyba że chcesz token ograniczony.
- Ustaw token jako BSC_API_TOKEN w środowisku klienta MCP.
- 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.
https://bank-statement-conversion.com/mcp/bank-statement-conversionAuthorization: Bearer YOUR_API_TOKENKonfiguracja Codex
Dodaj ten wpis serwera do konfiguracji Codex.
[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.
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
Endpointy przepływu
To jedyne endpointy potrzebne do dodania konwersji dokumentów do aplikacji.
| Endpoint | Metoda | Opis |
|---|---|---|
/api/user-status | GET | Opcjonalne sprawdzenie kredytów, limitu stron i planu subskrypcji |
/api/upload | POST | Prześlij wyciągi bankowe do konwersji |
/api/conversion-status/{jobId} | GET | Sprawdź status zadania konwersji |
/api/download/{downloadToken} | GET | Pobierz 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
| Pole | Typ | Opis |
|---|---|---|
remaining_credits | integer | Kredyty dostępne dla konwersji kredytowych. |
remaining_daily_pages | integer | Pozostały dzienny limit stron uwierzytelnionego użytkownika. |
remaining_premium_pages | integer | Pozostały miesięczny limit stron premium dla aktywnego planu. |
plan_type | string | Efektywny plan subskrypcji dla tokena API. |
Przykładowa odpowiedź
{
"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
| Zastosowanie | Formaty | Rozszerzenia | Uwagi |
|---|---|---|---|
| Standardowe konwersje | PDF, 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, .camt053 | Dla wyciągów bankowych, faktur i paragonów. |
| Czyszczenie CSV | CSV, XLS, XLSX | .csv, .xls, .xlsx | Używaj tylko, gdy format to csv_clean. |
| Generowanie plików płatniczych | CSV, XLS, XLSX | .csv, .xls, .xlsx | Uż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_type | Dokument | Dozwolone wartości format |
|---|---|---|
bank_statement | Wycią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 |
invoice | Faktura | csvexceljsonqb_onlineqb_desktopubl_xmlubl_peppolxrechnung_ublzugferd_pdffactur_x_pdf |
receipt | Paragon | csvexceljson |
payment_file | Bankowy plik płatniczy | payment_nachapayment_cpa005payment_sepa_pain001payment_bacspayment_abapayment_nz |
Użyj document_type=payment_file z payment_nacha, payment_cpa005, payment_sepa_pain001, payment_bacs, payment_aba lub payment_nz. Prześlij CSV, XLS lub XLSX jako statement[]; generowanie używa istniejącego przepływu kredytów, historii i tokenów pobierania.
Otwórz generator plików płatniczychUse document_type=positive_pay_file with format=positive_pay. Upload CSV, XLS, or XLSX check rows as statement[] and pass positive_pay_settings for Chase, TD, generic CSV, or fixed-width profiles.
Open Positive Pay file generatorParametry żądania
| Parametr | Typ | Wymagane | Opis |
|---|---|---|---|
format | string | Tak | Format wyjściowy. Użyj jednej z dozwolonych wartości format dla wybranego document_type. |
document_type | string | Nie | Kategoria dokumentu: bank_statement, invoice, receipt lub payment_file. Domyślnie: bank_statement. |
statement | file array | Tak | Pliki do konwersji. Wyślij jeden lub więcej plików jako statement[]. |
conversion_mode | string | Nie | Tryb konwersji: precision lub fast. Domyślnie precision. |
separate_debit_credit | boolean | Nie | Czy rozdzielić kolumny debet i kredyt. Domyślnie: false. |
combine_files | boolean | Nie | Czy połączyć wiele plików w jeden wynik. Domyślnie: false. |
Przykładowa odpowiedź
{
"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
| Parametr | Typ | Opis |
|---|---|---|
jobId | string | ID zadania zwrócone przez endpoint uploadu |
Przykładowa odpowiedź oczekująca
{
"stage": "processing",
"success": false,
"previews": []
}Przykładowa odpowiedź ukończona
{
"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
{
"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
| Parametr | Typ | Opis |
|---|---|---|
downloadToken | string | download_token zwrócony dla przekonwertowanego pliku w odpowiedzi statusu. |
Przykładowe żądanie
curl -L \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-o converted_statement.csv \
"https://bank-statement-conversion.com/api/download/Y8Jm7qVf9sR2kP6nL4xA0bT3cD5eF1gH"Przykładowa odpowiedź
200 OKPrzykładowe nagłówki odpowiedzi
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 statusu | Opis |
|---|---|
| 200 OK | Żądanie zakończyło się powodzeniem |
| 400 Bad Request | Żądanie było nieprawidłowe lub brakowało wymaganych parametrów |
| 401 Unauthorized | Uwierzytelnianie nie powiodło się lub token jest nieprawidłowy |
| 403 Forbidden | Uwierzytelniony użytkownik nie ma uprawnień do zasobu |
| 422 Unprocessable Entity | Wystąpiły błędy walidacji |
| 500 Internal Server Error | Wystąpił błąd serwera |
Przykładowe odpowiedzi błędów
{
"message": "Unauthenticated."
}{
"message": "The given data was invalid.",
"errors": {
"statement": [
"The statement field is required."
],
"format": [
"The selected format is invalid."
]
}
}{
"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.
npm install axios form-dataPython: pip install requestsPHP: PHP cURL extension enabledcURL: curl and jq installedGo: Go 1.20+Ruby: gem install multipart-postC#: .NET 7+npm install axios form-data1// 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}