תיעוד API - Bank-Statement-Conversion

API של Bank Statement Conversion

הוסף המרת דפי בנק עם זרימת העלאה, סטטוס והורדה ברורה.

סקירה

ה-API של Bank Statement Conversion מיועד למפתחים שרוצים להוסיף המרה לאפליקציה שלהם. הוא מתעד את תהליך ההמרה הציבורי: אפשר לבדוק קיבולת חשבון, להעלות קבצים, לבדוק סטטוס משימה, ואז להוריד פלטים מוכנים עם האסימון שהוחזר.

המסמך הזה מוגבל בכוונה לתהליך ההמרה הציבורי.

התחלה מהירה

שלב 1

צור אסימון API

צור אסימון בלוח הבקרה ושלח אותו בתור Authorization: Bearer YOUR_API_TOKEN.

שלב 2

העלה קובץ

שלח POST אל /api/upload עם statement[],‏ format והגדרות המרה אופציונליות.

שלב 3

בדוק סטטוס משימה

השתמש ב-jobId שהוחזר עם /api/conversion-status/{jobId} עד שתצוגה מקדימה כוללת download_token.

שלב 4

הורד פלט

שלח GET אל /api/download/{downloadToken} ושמור את התגובה הבינארית כקובץ שהומר.

אימות

אימות באמצעות אסימון API

כל בקשות ה-API חייבות לכלול אסימון API לאימות. ניתן ליצור אסימונים בלוח הבקרה של החשבון תחת API Tokens.

איך ליצור אסימון API

  1. התחבר לחשבון
  2. עבור אל אזור API Tokens בלוח הבקרה
  3. לחץ על "Create New Token" והזן שם לאסימון
  4. העתק ושמור את האסימון בצורה מאובטחת. הוא יוצג פעם אחת בלבד.

שימוש באסימון 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 מרוחקים.

הגדרת טוקן חד-פעמית

  1. התחברו פעם אחת וצרו טוקן API בלוח הבקרה.
  2. השאירו את כל הרשאות ההמרה פעילות אלא אם אתם רוצים טוקן מוגבל.
  3. הגדירו את הטוקן כ-BSC_API_TOKEN בסביבת לקוח ה-MCP.
  4. בטלו את הטוקן מלוח הבקרה כאשר יש להפסיק גישה של הסוכן.

חיבור Codex, Claude, Cursor ולקוחות AI נוספים

כל לקוחות ה-AI התואמים MCP משתמשים באותה נקודת קצה מרוחקת וב-bearer token. שמרו את הטוקן במשתנה סביבה, לא בפרומפטים או בקוד מקור.

נקודת MCP מרוחקת
https://bank-statement-conversion.com/mcp/bank-statement-conversion
כותרת אימות
Authorization: Bearer YOUR_API_TOKEN
הגדרת Codex

הוסיפו את רשומת השרת הזו להגדרת 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"

הגדירו את הטוקן ב-shell או בסביבת המערכת, ואז הפעילו מחדש את לקוח ה-AI.

Token environment variablebash
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 כהקשר מוצר עבור סוכנים שתומכים בקובצי ידע.

הרשאות טוקן מוגדרות-תחום

account:statusconversion:uploadconversion:readconversion:download

נקודות קצה של התהליך

אלו נקודות הקצה היחידות הדרושות להוספת המרת מסמכים לאפליקציה שלך.

נקודת קצהשיטהתיאור
/api/user-statusGETבדיקה מקדימה אופציונלית לקרדיטים, מכסת דפים ותוכנית מנוי
/api/uploadPOSTהעלאת דפי בנק להמרה
/api/conversion-status/{jobId}GETבדיקת סטטוס של משימת המרה
/api/download/{downloadToken}GETהורדת המרה מוכנה באמצעות האסימון שהוחזר בתגובת הסטטוס

נקודת סטטוס חשבון

GET /api/user-status

השתמש בנקודת הקצה האופציונלית הזו לפני העלאה כאשר האפליקציה צריכה לוודא שלאסימון ה-API יש קרדיטים, מכסת דפים או גישה בתשלום.

שדות תגובה שימושיים

שדהסוגתיאור
remaining_creditsintegerקרדיטים זמינים להמרות מבוססות קרדיט.
remaining_daily_pagesintegerמכסת הדפים היומית שנותרה למשתמש המאומת.
remaining_premium_pagesintegerמכסת דפי הפרימיום החודשית שנותרה לתוכנית הפעילה.
plan_typestringתוכנית המנוי הפעילה עבור אסימון ה-API.

דוגמת תגובה

תגובת JSONjson
העתק את המבנה הזה לפענוח בצד הלקוח ולטיפול בשגיאות.
{
  "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מיועד להמרות דפי בנק, חשבוניות וקבלות.
ניקוי 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 מוכנים לבדיקת הבנק.

פורמטי פלט נתמכים

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 המותרים המפורטים למעלה עבור 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
העתק את המבנה הזה לפענוח בצד הלקוח ולטיפול בשגיאות.
{
  "stage": "pending",
  "jobId": "5f3a7d8c-8a91-4a2e-9d3b-4c84f0636c12"
}

נקודת סטטוס

GET /api/conversion-status/{jobId}

נקודת קצה זו מאפשרת לבדוק את סטטוס משימת ההמרה. יש לבצע polling עד שהמשימה מסתיימת.

פרמטרים בנתיב

פרמטרסוגתיאור
jobIdstringמזהה המשימה שהוחזר מנקודת ההעלאה

דוגמת תגובה בהמתנה

תגובת JSONjson
העתק את המבנה הזה לפענוח בצד הלקוח ולטיפול בשגיאות.
{
  "stage": "processing",
  "success": false,
  "previews": []
}

דוגמת תגובה שהושלמה

תגובת JSONjson
העתק את המבנה הזה לפענוח בצד הלקוח ולטיפול בשגיאות.
{
  "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
העתק את המבנה הזה לפענוח בצד הלקוח ולטיפול בשגיאות.
{
  "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 שהוחזר בתוך תגובת סטטוס שהושלמה. אל תבנה אסימוני הורדה בעצמך.

פרמטרים בנתיב

פרמטרסוגתיאור
downloadTokenstringה-download_token שהוחזר עבור קובץ שהומר בתגובת הסטטוס.

דוגמת בקשה

הורדה עם cURLbash
הרץ מהטרמינל לאחר החלפת האסימון ואסימון ההורדה.
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. סיומת הקובץ תלויה בפורמט הפלט המבוקש, למשל .csv, .xlsx, .qbo, .ofx, .xml, .json, .ach, .txt או .aba.

דוגמת כותרות תגובה

כותרות תגובהhttp
נקודת ההורדה מחזירה זרם קובץ במקום גוף 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
}

טיפול בשגיאות

ה-API משתמש בקודי סטטוס HTTP סטנדרטיים כדי לציין הצלחה או כישלון של בקשות.

קוד סטטוסתיאור
200 OKהבקשה הצליחה
400 Bad Requestהבקשה לא תקינה או חסרים פרמטרים נדרשים
401 Unauthorizedהאימות נכשל או שהאסימון לא תקין
403 Forbiddenלמשתמש המאומת אין הרשאה לגשת למשאב
422 Unprocessable Entityאירעו שגיאות אימות נתונים
500 Internal Server Errorאירעה שגיאה בשרת

דוגמאות לתגובות שגיאה

401 לא מורשהjson
העתק את המבנה הזה לפענוח בצד הלקוח ולטיפול בשגיאות.
{
  "message": "Unauthenticated."
}
422 שגיאת אימותjson
העתק את המבנה הזה לפענוח בצד הלקוח ולטיפול בשגיאות.
{
  "message": "The given data was invalid.",
  "errors": {
    "statement": [
      "The statement field is required."
    ],
    "format": [
      "The selected format is invalid."
    ]
  }
}
403 קיבולת לא מספקתjson
העתק את המבנה הזה לפענוח בצד הלקוח ולטיפול בשגיאות.
{
  "success": false,
  "error": "Insufficient credits or page allowance for this conversion."
}

מגבלות קצב

כדי להבטיח שימוש הוגן ב-API, מגבלות קצב מוחלות לפי תוכנית המנוי:

  • משתמשי פרימיום: 100 בקשות בדקה
  • גודל קובץ מקסימלי: 100MB לכל קובץ
  • מספר קבצים מקסימלי בבקשה: 5

דוגמאות קוד

דוגמאות מקצה לקצה לתהליך ההמרה: העלאה, בדיקה ואז הורדה.

1. העלאה2. בדיקת סטטוס3. הורדה
JavaScript דוגמהjavascript
משתמש ב-axios וב-form-data כדי להעלות, לבדוק ולהוריד את הקובץ שהומר.
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}