واجهة API من Bank Statement Conversion
أضف التحويل إلى برنامجك عبر مسار واضح للرفع والحالة والتنزيل.
https://bank-statement-conversion.com/api/uploadنقطة الرفع/conversion-status/{jobId}نقطة الحالة/download/{downloadToken}نقطة التنزيلنظرة عامة
واجهة Bank Statement Conversion API مخصصة للمطورين الذين يريدون إضافة التحويل إلى تطبيقاتهم. توثق مسار التحويل العام: يمكن التحقق من سعة الحساب، ثم رفع الملفات، ثم متابعة حالة المهمة، ثم تنزيل المخرجات المكتملة باستخدام الرمز المعاد.
تقتصر هذه المرجعية عمدًا على سير التحويل العام.
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وكلاء الذكاء الاصطناعي
استخدام API مع وكلاء الذكاء الاصطناعي
يمكن لأدوات الذكاء الاصطناعي التكامل مع سير التحويل العام نفسه الذي يستخدمه المطورون. استخدم مخطط 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 وعملاء الذكاء الاصطناعي الآخرين
كل عملاء الذكاء الاصطناعي المتوافقين مع MCP يستخدمون نفس endpoint البعيد ورمز bearer. احتفظ بالرمز في متغير بيئة، وليس داخل prompts أو الكود المصدري.
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 أو بيئة النظام، ثم أعد تشغيل عميل الذكاء الاصطناعي.
export BSC_API_TOKEN="YOUR_API_TOKEN_HERE"عملاء ذكاء اصطناعي آخرون
- يجب أن يستخدم Claude وCursor وعملاء MCP الآخرون نفس endpoint ونفس رمز Authorization bearer.
- يجب أن تستخدم ChatGPT Actions ومنشئات الوكلاء المخصصة /api/openapi.json بدل MCP عندما تحتاج إلى مخطط 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[]؛ يستخدم التوليد سير عمل الأرصدة والسجل ورموز التنزيل الحالي.
فتح مولد ملفات الدفع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 المسموحة أعلاه لنوع document_type المحدد. |
document_type | string | لا | فئة المستند: bank_statement أو invoice أو receipt أو payment_file. الافتراضي: bank_statement. |
statement | file array | نعم | الملفات المطلوب تحويلها. أرسل ملفا أو أكثر بصيغة statement[]. |
separate_debit_credit | boolean | لا | هل يتم فصل أعمدة المدين والدائن. الافتراضي: false. |
combine_files | boolean | لا | هل يتم دمج عدة ملفات في مخرج واحد. الافتراضي: false. |
مثال استجابة
{
"stage": "pending",
"jobId": "5f3a7d8c-8a91-4a2e-9d3b-4c84f0636c12"
}نقطة الحالة
GET /api/conversion-status/{jobId}
تتيح لك نقطة النهاية هذه التحقق من حالة مهمة التحويل. يجب متابعتها حتى تكتمل المهمة.
معلمات المسار
| المعلمة | النوع | الوصف |
|---|---|---|
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."
}حدود المعدل
لضمان الاستخدام العادل للواجهة، تطبق حدود المعدل حسب خطة اشتراكك:
- المستخدمون المميزون: 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}