Τεκμηρίωση API - Bank-Statement-Conversion

API Bank Statement Conversion

Προσθέστε μετατροπή με καθαρή ροή μεταφόρτωσης, κατάστασης και λήψης.

Επισκόπηση

Το API Bank Statement Conversion είναι για προγραμματιστές που θέλουν να προσθέσουν μετατροπή στη δική τους εφαρμογή. Περιγράφει τη δημόσια ροή: προαιρετικό έλεγχο χωρητικότητας λογαριασμού, μεταφόρτωση αρχείων, έλεγχο κατάστασης εργασίας και λήψη ολοκληρωμένων αποτελεσμάτων με το token που επιστρέφεται.

Αυτή η αναφορά περιορίζεται σκόπιμα στη δημόσια ροή μετατροπής.

Γρήγορη έναρξη

Βήμα 1

Δημιουργήστε API token

Δημιουργήστε token στον πίνακα ελέγχου και στείλτε το ως Authorization: Bearer YOUR_API_TOKEN.

Βήμα 2

Μεταφορτώστε αρχείο

Στείλτε POST στο /api/upload με statement[], format και προαιρετικές ρυθμίσεις.

Βήμα 3

Ελέγξτε κατάσταση εργασίας

Χρησιμοποιήστε το jobId με /api/conversion-status/{jobId} μέχρι το preview να περιλαμβάνει download_token.

Βήμα 4

Κατεβάστε το αποτέλεσμα

Στείλτε GET στο /api/download/{downloadToken} και αποθηκεύστε τη δυαδική απόκριση ως μετατρεπόμενο αρχείο.

Έλεγχος ταυτότητας

Έλεγχος ταυτότητας με API token

Όλα τα API αιτήματα πρέπει να περιλαμβάνουν API token για έλεγχο ταυτότητας. Τα tokens δημιουργούνται στον πίνακα λογαριασμού στην ενότητα API Tokens.

Πώς να δημιουργήσετε API token

  1. Συνδεθείτε στον λογαριασμό σας
  2. Μεταβείτε στην ενότητα API Tokens
  3. Κάντε κλικ στο "Create New Token" και δώστε όνομα
  4. Αντιγράψτε και αποθηκεύστε με ασφάλεια το token. Θα εμφανιστεί μόνο μία φορά.

Χρήση του API token

Συμπεριλάβετε το API token στο header Authorization των αιτημάτων:

Authorization: Bearer YOUR_API_TOKEN

AI 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 μία φορά

  1. Συνδεθείτε μία φορά και δημιουργήστε ένα API token στο dashboard.
  2. Κρατήστε όλα τα conversion abilities ενεργά εκτός αν θέλετε restricted token.
  3. Ορίστε το token ως BSC_API_TOKEN στο environment του MCP client.
  4. Ανακαλέστε το token από το dashboard όταν πρέπει να σταματήσει η πρόσβαση του agent.

Σύνδεση Codex, Claude, Cursor και άλλων AI clients

Όλοι οι MCP-compatible AI clients χρησιμοποιούν το ίδιο remote endpoint και bearer token. Κρατήστε το token σε environment variable, όχι σε prompts ή source code.

Remote MCP endpoint
https://bank-statement-conversion.com/mcp/bank-statement-conversion
Authentication header
Authorization: Bearer YOUR_API_TOKEN
Ρύθμιση Codex

Προσθέστε αυτή την εγγραφή server στο Codex config σας.

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"

Ορίστε το token στο shell ή στο system environment και μετά επανεκκινήστε τον AI client.

Token environment variablebash
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

account:statusconversion:uploadconversion:readconversion:download

Endpoints ροής

Αυτά είναι τα μόνα endpoints που χρειάζονται για να προσθέσετε μετατροπή εγγράφων στην εφαρμογή σας.

EndpointΜέθοδοςΠεριγραφή
/api/user-statusGETΠροαιρετικός προκαταρκτικός έλεγχος πιστώσεων, ορίου σελίδων και πλάνου
/api/uploadPOSTΜεταφόρτωση κινήσεων τραπεζικού λογαριασμού για μετατροπή
/api/conversion-status/{jobId}GETΈλεγχος κατάστασης εργασίας μετατροπής
/api/download/{downloadToken}GETΛήψη ολοκληρωμένης μετατροπής με το token από την απόκριση κατάστασης

Endpoint κατάστασης λογαριασμού

GET /api/user-status

Χρησιμοποιήστε αυτό το προαιρετικό endpoint πριν τη μεταφόρτωση όταν η εφαρμογή πρέπει να επιβεβαιώσει πιστώσεις, όριο σελίδων ή πρόσβαση επί πληρωμή.

Χρήσιμα πεδία απόκρισης

ΠεδίοΤύποςΠεριγραφή
remaining_creditsintegerΔιαθέσιμες πιστώσεις για μετατροπές με πιστώσεις.
remaining_daily_pagesintegerΥπόλοιπο ημερήσιου ορίου σελίδων για τον πιστοποιημένο χρήστη.
remaining_premium_pagesintegerΥπόλοιπο μηνιαίου premium ορίου σελίδων για το ενεργό πλάνο.
plan_typestringΤο ενεργό πλάνο συνδρομής για το API token.

Παράδειγμα απόκρισης

Απόκριση JSONjson
Αντιγράψτε αυτήν τη δομή για parsing στον client και χειρισμό σφαλμάτων.
{
  "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Για τραπεζικές κινήσεις, τιμολόγια και αποδείξεις.
Καθαρισμός CSVCSV, 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

Παράμετροι αιτήματος

ΠαράμετροςΤύποςΑπαιτείταιΠεριγραφή
formatstringΝαιFormat εξόδου. Χρησιμοποιήστε μία επιτρεπόμενη τιμή format για το επιλεγμένο document_type.
document_typestringΌχιΚατηγορία εγγράφου: bank_statement, invoice, receipt ή payment_file. Προεπιλογή: bank_statement.
statementfile arrayΝαιΑρχεία για μετατροπή. Στείλτε ένα ή περισσότερα αρχεία ως statement[].
conversion_modestringΌχιΛειτουργία μετατροπής: precision ή fast. Προεπιλογή precision.
separate_debit_creditbooleanΌχιΑν θα διαχωριστούν στήλες χρέωσης και πίστωσης. Προεπιλογή: false.
combine_filesbooleanΌχιΑν θα συνδυαστούν πολλά αρχεία σε ένα αποτέλεσμα. Προεπιλογή: false.

Παράδειγμα απόκρισης

Απόκριση JSONjson
Αντιγράψτε αυτήν τη δομή για parsing στον client και χειρισμό σφαλμάτων.
{
  "stage": "pending",
  "jobId": "5f3a7d8c-8a91-4a2e-9d3b-4c84f0636c12"
}

Endpoint κατάστασης

GET /api/conversion-status/{jobId}

Αυτό το endpoint ελέγχει την κατάσταση εργασίας μετατροπής. Κάντε polling μέχρι να ολοκληρωθεί.

Παράμετροι διαδρομής

ΠαράμετροςΤύποςΠεριγραφή
jobIdstringΤο ID εργασίας που επιστρέφεται από το endpoint upload

Παράδειγμα απόκρισης σε εκκρεμότητα

Απόκριση JSONjson
Αντιγράψτε αυτήν τη δομή για parsing στον client και χειρισμό σφαλμάτων.
{
  "stage": "processing",
  "success": false,
  "previews": []
}

Παράδειγμα ολοκληρωμένης απόκρισης

Απόκριση JSONjson
Αντιγράψτε αυτήν τη δομή για parsing στον client και χειρισμό σφαλμάτων.
{
  "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
}

Παράδειγμα αποτυχημένης απόκρισης

Απόκριση JSONjson
Αντιγράψτε αυτήν τη δομή για parsing στον client και χειρισμό σφαλμάτων.
{
  "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 λήψης μόνοι σας.

Παράμετροι διαδρομής

ΠαράμετροςΤύποςΠεριγραφή
downloadTokenstringΤο download_token που επιστρέφεται για μετατρεπόμενο αρχείο στην απόκριση κατάστασης.

Παράδειγμα αιτήματος

Λήψη με cURLbash
Εκτελέστε στο terminal αφού αντικαταστήσετε token και download token.
curl -L \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -o converted_statement.csv \
  "https://bank-statement-conversion.com/api/download/Y8Jm7qVf9sR2kP6nL4xA0bT3cD5eF1gH"

Παράδειγμα απόκρισης

200 OK
Επιστρέφει το μετατρεπόμενο αρχείο ως δυαδική λήψη με Content-Disposition: attachment. Η επέκταση εξαρτάται από το ζητούμενο format, όπως .csv, .xlsx, .qbo, .ofx, .xml, .json, .ach, .txt ή .aba.

Παράδειγμα headers απόκρισης

Headers απόκρισηςhttp
Το endpoint λήψης επιστρέφει stream αρχείου αντί για JSON body.
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

Παραδείγματα αποκρίσεων σφάλματος

401 Μη εξουσιοδοτημένοjson
Αντιγράψτε αυτήν τη δομή για parsing στον client και χειρισμό σφαλμάτων.
{
  "message": "Unauthenticated."
}
422 Σφάλμα επικύρωσηςjson
Αντιγράψτε αυτήν τη δομή για parsing στον client και χειρισμό σφαλμάτων.
{
  "message": "The given data was invalid.",
  "errors": {
    "statement": [
      "The statement field is required."
    ],
    "format": [
      "The selected format is invalid."
    ]
  }
}
403 Ανεπαρκής χωρητικότηταjson
Αντιγράψτε αυτήν τη δομή για parsing στον client και χειρισμό σφαλμάτων.
{
  "success": false,
  "error": "Insufficient credits or page allowance for this conversion."
}

Όρια ρυθμού

Για δίκαιη χρήση του API, τα όρια εφαρμόζονται ανάλογα με το πλάνο συνδρομής:

  • Premium χρήστες: 100 αιτήματα ανά λεπτό
  • Μέγιστο μέγεθος αρχείου: 100MB ανά αρχείο
  • Μέγιστο ανά αίτημα: 5 αρχεία

Παραδείγματα κώδικα

Πλήρη παραδείγματα ροής: μεταφόρτωση, έλεγχος, λήψη.

1. Μεταφόρτωση2. Έλεγχος κατάστασης3. Λήψη
JavaScript παράδειγμαjavascript
Χρησιμοποιεί axios και form-data για μεταφόρτωση, polling και λήψη του αρχείου.
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}