API Bank Statement Conversion
Προσθέστε μετατροπή με καθαρή ροή μεταφόρτωσης, κατάστασης και λήψης.
Επισκόπηση
Το API Bank Statement Conversion είναι για προγραμματιστές που θέλουν να προσθέσουν μετατροπή στη δική τους εφαρμογή. Περιγράφει τη δημόσια ροή: προαιρετικό έλεγχο χωρητικότητας λογαριασμού, μεταφόρτωση αρχείων, έλεγχο κατάστασης εργασίας και λήψη ολοκληρωμένων αποτελεσμάτων με το token που επιστρέφεται.
Αυτή η αναφορά περιορίζεται σκόπιμα στη δημόσια ροή μετατροπής.
https://bank-statement-conversion.com/apiΓρήγορη έναρξη
Δημιουργήστε API token
Δημιουργήστε token στον πίνακα ελέγχου και στείλτε το ως Authorization: Bearer YOUR_API_TOKEN.
Μεταφορτώστε αρχείο
Στείλτε POST στο /api/upload με statement[], format και προαιρετικές ρυθμίσεις.
Ελέγξτε κατάσταση εργασίας
Χρησιμοποιήστε το jobId με /api/conversion-status/{jobId} μέχρι το preview να περιλαμβάνει download_token.
Κατεβάστε το αποτέλεσμα
Στείλτε GET στο /api/download/{downloadToken} και αποθηκεύστε τη δυαδική απόκριση ως μετατρεπόμενο αρχείο.
Έλεγχος ταυτότητας
Έλεγχος ταυτότητας με API token
Όλα τα API αιτήματα πρέπει να περιλαμβάνουν API token για έλεγχο ταυτότητας. Τα tokens δημιουργούνται στον πίνακα λογαριασμού στην ενότητα API Tokens.
Πώς να δημιουργήσετε API token
- Συνδεθείτε στον λογαριασμό σας
- Μεταβείτε στην ενότητα API Tokens
- Κάντε κλικ στο "Create New Token" και δώστε όνομα
- Αντιγράψτε και αποθηκεύστε με ασφάλεια το token. Θα εμφανιστεί μόνο μία φορά.
Χρήση του API token
Συμπεριλάβετε το API token στο header Authorization των αιτημάτων:
Authorization: Bearer YOUR_API_TOKENAI agents
Χρήση του API με AI agents
Τα εργαλεία AI μπορούν να ενσωματωθούν στην ίδια δημόσια ροή μετατροπής με τους προγραμματιστές. Χρησιμοποιήστε το σχήμα OpenAPI, τα αρχεία ανακάλυψης LLM ή το endpoint MCP, ώστε οι πράκτορες να γνωρίζουν ποια endpoint μετατροπής να καλέσουν και ποιες ενέργειες χρειάζονται επιβεβαίωση.
Discovery για agents
/api/openapi.json/llms.txt/llms-full.txt/mcp/bank-statement-conversion- Χρησιμοποιήστε το
/api/openapi.jsonγια schema-aware εργαλεία όπως ChatGPT Actions ή custom agent builders. - Χρησιμοποιήστε τα
/llms.txtκαι/llms-full.txtγια να δώσετε στους agents το canonical product και API context. - Χρησιμοποιήστε το
/mcp/bank-statement-conversionγια MCP-compatible agent clients που υποστηρίζουν remote MCP servers.
Ρύθμιση token μία φορά
- Συνδεθείτε μία φορά και δημιουργήστε ένα API token στο dashboard.
- Κρατήστε όλα τα conversion abilities ενεργά εκτός αν θέλετε restricted token.
- Ορίστε το token ως BSC_API_TOKEN στο environment του MCP client.
- Ανακαλέστε το token από το dashboard όταν πρέπει να σταματήσει η πρόσβαση του agent.
Σύνδεση Codex, Claude, Cursor και άλλων AI clients
Όλοι οι MCP-compatible AI clients χρησιμοποιούν το ίδιο remote endpoint και bearer token. Κρατήστε το token σε environment variable, όχι σε prompts ή source code.
https://bank-statement-conversion.com/mcp/bank-statement-conversionAuthorization: Bearer YOUR_API_TOKENΡύθμιση Codex
Προσθέστε αυτή την εγγραφή server στο Codex config σας.
[mcp_servers.bank_statement_conversion]
url = "https://bank-statement-conversion.com/mcp/bank-statement-conversion"
bearer_token_env_var = "BSC_API_TOKEN"Ορίστε το token στο shell ή στο system environment και μετά επανεκκινήστε τον AI client.
export BSC_API_TOKEN="YOUR_API_TOKEN_HERE"Άλλοι AI clients
- Claude, Cursor και άλλοι MCP clients πρέπει να χρησιμοποιούν το ίδιο endpoint URL και Authorization bearer token.
- ChatGPT Actions και custom agent builders πρέπει να χρησιμοποιούν /api/openapi.json αντί για MCP όταν χρειάζονται OpenAPI schema.
- Χρησιμοποιήστε /llms.txt και /llms-full.txt ως product context για agents που υποστηρίζουν knowledge files.
Scoped token abilities
Endpoints ροής
Αυτά είναι τα μόνα endpoints που χρειάζονται για να προσθέσετε μετατροπή εγγράφων στην εφαρμογή σας.
| Endpoint | Μέθοδος | Περιγραφή |
|---|---|---|
/api/user-status | GET | Προαιρετικός προκαταρκτικός έλεγχος πιστώσεων, ορίου σελίδων και πλάνου |
/api/upload | POST | Μεταφόρτωση κινήσεων τραπεζικού λογαριασμού για μετατροπή |
/api/conversion-status/{jobId} | GET | Έλεγχος κατάστασης εργασίας μετατροπής |
/api/download/{downloadToken} | GET | Λήψη ολοκληρωμένης μετατροπής με το token από την απόκριση κατάστασης |
Endpoint κατάστασης λογαριασμού
GET /api/user-status
Χρησιμοποιήστε αυτό το προαιρετικό endpoint πριν τη μεταφόρτωση όταν η εφαρμογή πρέπει να επιβεβαιώσει πιστώσεις, όριο σελίδων ή πρόσβαση επί πληρωμή.
Χρήσιμα πεδία απόκρισης
| Πεδίο | Τύπος | Περιγραφή |
|---|---|---|
remaining_credits | integer | Διαθέσιμες πιστώσεις για μετατροπές με πιστώσεις. |
remaining_daily_pages | integer | Υπόλοιπο ημερήσιου ορίου σελίδων για τον πιστοποιημένο χρήστη. |
remaining_premium_pages | integer | Υπόλοιπο μηνιαίου premium ορίου σελίδων για το ενεργό πλάνο. |
plan_type | string | Το ενεργό πλάνο συνδρομής για το API token. |
Παράδειγμα απόκρισης
{
"success": true,
"remaining_credits": 42,
"remaining_daily_pages": 100,
"remaining_premium_pages": 950,
"plan_type": "premium"
}Endpoint μεταφόρτωσης
POST /api/upload
Αυτό το endpoint επιτρέπει μεταφόρτωση τραπεζικών κινήσεων για μετατροπή. Η διαδικασία είναι ασύγχρονη και επιστρέφει ID εργασίας για μετέπειτα έλεγχο.
Υποστηριζόμενα format εισόδου
| Χρήση | Format | Επεκτάσεις | Σημειώσεις |
|---|---|---|---|
| Τυπικές μετατροπές | 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 | Για τραπεζικές κινήσεις, τιμολόγια και αποδείξεις. |
| Καθαρισμός CSV | CSV, XLS, XLSX | .csv, .xls, .xlsx | Χρησιμοποιήστε μόνο όταν format είναι csv_clean. |
| Δημιουργία αρχείων πληρωμών | CSV, XLS, XLSX | .csv, .xls, .xlsx | Χρησιμοποιήστε το για σειρές πληρωμών CSV ή Excel που δημιουργούν αρχεία ACH/NACHA, CPA005, SEPA XML, BACS, ABA ή NZ για έλεγχο από την τράπεζα. |
Υποστηριζόμενα format εξόδου
document_type | Έγγραφο | Επιτρεπόμενες τιμές format |
|---|---|---|
bank_statement | Τραπεζική κίνηση | 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 | Τιμολόγιο | csvexceljsonqb_onlineqb_desktopubl_xmlubl_peppolxrechnung_ublzugferd_pdffactur_x_pdf |
receipt | Απόδειξη | csvexceljson |
payment_file | Αρχείο τραπεζικής πληρωμής | payment_nachapayment_cpa005payment_sepa_pain001payment_bacspayment_abapayment_nz |
Χρησιμοποιήστε document_type=payment_file με payment_nacha, payment_cpa005, payment_sepa_pain001, payment_bacs, payment_aba ή payment_nz. Ανεβάστε CSV, XLS ή XLSX ως statement[]· η δημιουργία χρησιμοποιεί το υπάρχον workflow credits, history και download-token.
Άνοιγμα γεννήτριας αρχείων πληρωμώνUse 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 generatorΠαράμετροι αιτήματος
| Παράμετρος | Τύπος | Απαιτείται | Περιγραφή |
|---|---|---|---|
format | string | Ναι | Format εξόδου. Χρησιμοποιήστε μία επιτρεπόμενη τιμή format για το επιλεγμένο document_type. |
document_type | string | Όχι | Κατηγορία εγγράφου: bank_statement, invoice, receipt ή payment_file. Προεπιλογή: bank_statement. |
statement | file array | Ναι | Αρχεία για μετατροπή. Στείλτε ένα ή περισσότερα αρχεία ως statement[]. |
conversion_mode | string | Όχι | Λειτουργία μετατροπής: precision ή fast. Προεπιλογή precision. |
separate_debit_credit | boolean | Όχι | Αν θα διαχωριστούν στήλες χρέωσης και πίστωσης. Προεπιλογή: false. |
combine_files | boolean | Όχι | Αν θα συνδυαστούν πολλά αρχεία σε ένα αποτέλεσμα. Προεπιλογή: false. |
Παράδειγμα απόκρισης
{
"stage": "pending",
"jobId": "5f3a7d8c-8a91-4a2e-9d3b-4c84f0636c12"
}Endpoint κατάστασης
GET /api/conversion-status/{jobId}
Αυτό το endpoint ελέγχει την κατάσταση εργασίας μετατροπής. Κάντε polling μέχρι να ολοκληρωθεί.
Παράμετροι διαδρομής
| Παράμετρος | Τύπος | Περιγραφή |
|---|---|---|
jobId | string | Το ID εργασίας που επιστρέφεται από το endpoint upload |
Παράδειγμα απόκρισης σε εκκρεμότητα
{
"stage": "processing",
"success": false,
"previews": []
}Παράδειγμα ολοκληρωμένης απόκρισης
{
"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
}Παράδειγμα αποτυχημένης απόκρισης
{
"stage": "complete",
"success": false,
"error": "An error occurred during the conversion process.",
"message": "The uploaded file could not be processed.",
"previews": []
}Endpoint λήψης
GET /api/download/{downloadToken}
Χρησιμοποιήστε το download_token από ολοκληρωμένη απόκριση κατάστασης. Μην δημιουργείτε tokens λήψης μόνοι σας.
Παράμετροι διαδρομής
| Παράμετρος | Τύπος | Περιγραφή |
|---|---|---|
downloadToken | string | Το download_token που επιστρέφεται για μετατρεπόμενο αρχείο στην απόκριση κατάστασης. |
Παράδειγμα αιτήματος
curl -L \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-o converted_statement.csv \
"https://bank-statement-conversion.com/api/download/Y8Jm7qVf9sR2kP6nL4xA0bT3cD5eF1gH"Παράδειγμα απόκρισης
200 OKΠαράδειγμα headers απόκρισης
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
}Χειρισμός σφαλμάτων
Το API χρησιμοποιεί τυπικούς HTTP status codes για επιτυχία ή αποτυχία αιτημάτων.
| Κωδικός κατάστασης | Περιγραφή |
|---|---|
| 200 OK | Το αίτημα ήταν επιτυχές |
| 400 Bad Request | Το αίτημα ήταν άκυρο ή λείπουν απαιτούμενες παράμετροι |
| 401 Unauthorized | Ο έλεγχος ταυτότητας απέτυχε ή το token είναι άκυρο |
| 403 Forbidden | Ο πιστοποιημένος χρήστης δεν έχει άδεια πρόσβασης στον πόρο |
| 422 Unprocessable Entity | Παρουσιάστηκαν σφάλματα επικύρωσης |
| 500 Internal Server Error | Παρουσιάστηκε σφάλμα στον server |
Παραδείγματα αποκρίσεων σφάλματος
{
"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."
}Όρια ρυθμού
Για δίκαιη χρήση του API, τα όρια εφαρμόζονται ανάλογα με το πλάνο συνδρομής:
- Premium χρήστες: 100 αιτήματα ανά λεπτό
- Μέγιστο μέγεθος αρχείου: 100MB ανά αρχείο
- Μέγιστο ανά αίτημα: 5 αρχεία
Παραδείγματα κώδικα
Πλήρη παραδείγματα ροής: μεταφόρτωση, έλεγχος, λήψη.
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}