סקירה
ה-API של Bank Statement Conversion מיועד למפתחים שרוצים להוסיף המרה לאפליקציה שלהם. הוא מתעד את תהליך ההמרה הציבורי: אפשר לבדוק קיבולת חשבון, להעלות קבצים, לבדוק סטטוס משימה, ואז להוריד פלטים מוכנים עם האסימון שהוחזר.
המסמך הזה מוגבל בכוונה לתהליך ההמרה הציבורי.
https://bank-statement-conversion.com/apiהתחלה מהירה
צור אסימון API
צור אסימון בלוח הבקרה ושלח אותו בתור Authorization: Bearer YOUR_API_TOKEN.
העלה קובץ
שלח POST אל /api/upload עם statement[], format והגדרות המרה אופציונליות.
בדוק סטטוס משימה
השתמש ב-jobId שהוחזר עם /api/conversion-status/{jobId} עד שתצוגה מקדימה כוללת download_token.
הורד פלט
שלח GET אל /api/download/{downloadToken} ושמור את התגובה הבינארית כקובץ שהומר.
אימות
אימות באמצעות אסימון API
כל בקשות ה-API חייבות לכלול אסימון API לאימות. ניתן ליצור אסימונים בלוח הבקרה של החשבון תחת API Tokens.
איך ליצור אסימון API
- התחבר לחשבון
- עבור אל אזור API Tokens בלוח הבקרה
- לחץ על "Create New Token" והזן שם לאסימון
- העתק ושמור את האסימון בצורה מאובטחת. הוא יוצג פעם אחת בלבד.
שימוש באסימון API
כלול את אסימון ה-API בכותרת Authorization של הבקשות:
Authorization: Bearer YOUR_API_TOKENסוכני AI
שימוש ב-API עם סוכני AI
כלי AI יכולים להשתלב באותו תהליך המרה ציבורי כמו מפתחים. השתמשו בסכמת OpenAPI, בקובצי גילוי LLM או בנקודת קצה של MCP כדי שסוכנים ידעו לאילו נקודות קצה לקרוא ואילו פעולות דורשות אישור.
גילוי לסוכנים
/api/openapi.json/llms.txt/llms-full.txt/mcp/bank-statement-conversion- השתמשו ב-
/api/openapi.jsonעבור כלים מודעי-סכמה כמו ChatGPT Actions או בוני סוכנים מותאמים. - השתמשו ב-
/llms.txtוב-/llms-full.txtכדי לתת לסוכנים הקשר מוצר ו-API קנוני. - השתמשו ב-
/mcp/bank-statement-conversionעבור לקוחות סוכנים תואמי MCP שתומכים בשרתי MCP מרוחקים.
הגדרת טוקן חד-פעמית
- התחברו פעם אחת וצרו טוקן API בלוח הבקרה.
- השאירו את כל הרשאות ההמרה פעילות אלא אם אתם רוצים טוקן מוגבל.
- הגדירו את הטוקן כ-BSC_API_TOKEN בסביבת לקוח ה-MCP.
- בטלו את הטוקן מלוח הבקרה כאשר יש להפסיק גישה של הסוכן.
חיבור Codex, Claude, Cursor ולקוחות AI נוספים
כל לקוחות ה-AI התואמים MCP משתמשים באותה נקודת קצה מרוחקת וב-bearer token. שמרו את הטוקן במשתנה סביבה, לא בפרומפטים או בקוד מקור.
https://bank-statement-conversion.com/mcp/bank-statement-conversionAuthorization: Bearer YOUR_API_TOKENהגדרת Codex
הוסיפו את רשומת השרת הזו להגדרת Codex.
[mcp_servers.bank_statement_conversion]
url = "https://bank-statement-conversion.com/mcp/bank-statement-conversion"
bearer_token_env_var = "BSC_API_TOKEN"הגדירו את הטוקן ב-shell או בסביבת המערכת, ואז הפעילו מחדש את לקוח ה-AI.
export BSC_API_TOKEN="YOUR_API_TOKEN_HERE"לקוחות AI נוספים
- Claude, Cursor ולקוחות MCP אחרים צריכים להשתמש באותה כתובת endpoint ובאותו Authorization bearer token.
- ChatGPT Actions ובוני סוכנים מותאמים צריכים להשתמש ב-/api/openapi.json במקום MCP כאשר נדרש schema של OpenAPI.
- השתמשו ב-/llms.txt וב-/llms-full.txt כהקשר מוצר עבור סוכנים שתומכים בקובצי ידע.
הרשאות טוקן מוגדרות-תחום
נקודות קצה של התהליך
אלו נקודות הקצה היחידות הדרושות להוספת המרת מסמכים לאפליקציה שלך.
| נקודת קצה | שיטה | תיאור |
|---|---|---|
/api/user-status | GET | בדיקה מקדימה אופציונלית לקרדיטים, מכסת דפים ותוכנית מנוי |
/api/upload | POST | העלאת דפי בנק להמרה |
/api/conversion-status/{jobId} | GET | בדיקת סטטוס של משימת המרה |
/api/download/{downloadToken} | GET | הורדת המרה מוכנה באמצעות האסימון שהוחזר בתגובת הסטטוס |
נקודת סטטוס חשבון
GET /api/user-status
השתמש בנקודת הקצה האופציונלית הזו לפני העלאה כאשר האפליקציה צריכה לוודא שלאסימון ה-API יש קרדיטים, מכסת דפים או גישה בתשלום.
שדות תגובה שימושיים
| שדה | סוג | תיאור |
|---|---|---|
remaining_credits | integer | קרדיטים זמינים להמרות מבוססות קרדיט. |
remaining_daily_pages | integer | מכסת הדפים היומית שנותרה למשתמש המאומת. |
remaining_premium_pages | integer | מכסת דפי הפרימיום החודשית שנותרה לתוכנית הפעילה. |
plan_type | string | תוכנית המנוי הפעילה עבור אסימון ה-API. |
דוגמת תגובה
{
"success": true,
"remaining_credits": 42,
"remaining_daily_pages": 100,
"remaining_premium_pages": 950,
"plan_type": "premium"
}נקודת העלאה
POST /api/upload
נקודת קצה זו מאפשרת להעלות דפי בנק להמרה. תהליך ההמרה אסינכרוני ותקבל מזהה משימה לבדיקת הסטטוס בהמשך.
פורמטי קלט נתמכים
| שימוש | פורמטים | סיומות | הערות |
|---|---|---|---|
| המרות רגילות | 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 מוכנים לבדיקת הבנק. |
פורמטי פלט נתמכים
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[]; ההפקה משתמשת בזרימת הקרדיטים, ההיסטוריה ואסימוני ההורדה הקיימת.
פתחו מחולל קובצי תשלוםהשתמשו ב-document_type=positive_pay_file עם format=positive_pay. העלו שורות המחאות מסוג CSV, XLS או XLSX בתור statement[] והעבירו positive_pay_settings עבור פרופילי Chase, TD, CSV כללי או רוחב קבוע.
פתחו את מחולל קובצי Positive Payפרמטרים לבקשה
| פרמטר | סוג | נדרש | תיאור |
|---|---|---|---|
format | string | כן | פורמט פלט. השתמש באחד מערכי 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"
}נקודת סטטוס
GET /api/conversion-status/{jobId}
נקודת קצה זו מאפשרת לבדוק את סטטוס משימת ההמרה. יש לבצע polling עד שהמשימה מסתיימת.
פרמטרים בנתיב
| פרמטר | סוג | תיאור |
|---|---|---|
jobId | string | מזהה המשימה שהוחזר מנקודת ההעלאה |
דוגמת תגובה בהמתנה
{
"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": []
}נקודת הורדה
GET /api/download/{downloadToken}
השתמש ב-download_token שהוחזר בתוך תגובת סטטוס שהושלמה. אל תבנה אסימוני הורדה בעצמך.
פרמטרים בנתיב
| פרמטר | סוג | תיאור |
|---|---|---|
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דוגמת כותרות תגובה
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 סטנדרטיים כדי לציין הצלחה או כישלון של בקשות.
| קוד סטטוס | תיאור |
|---|---|
| 200 OK | הבקשה הצליחה |
| 400 Bad Request | הבקשה לא תקינה או חסרים פרמטרים נדרשים |
| 401 Unauthorized | האימות נכשל או שהאסימון לא תקין |
| 403 Forbidden | למשתמש המאומת אין הרשאה לגשת למשאב |
| 422 Unprocessable Entity | אירעו שגיאות אימות נתונים |
| 500 Internal Server Error | אירעה שגיאה בשרת |
דוגמאות לתגובות שגיאה
{
"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, מגבלות קצב מוחלות לפי תוכנית המנוי:
- משתמשי פרימיום: 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}