توثيق API - Bank-Statement-Conversion
مرجع API

واجهة API من Bank Statement Conversion

أضف التحويل إلى برنامجك عبر مسار واضح للرفع والحالة والتنزيل.

المصادقة نقطة الرفع نقاط نهاية سير العمل
api.bsc / v1
عنوان URL الأساسي
https://bank-statement-conversion.com/api
نقاط نهاية سير العمل
POST/uploadنقطة الرفع
GET/conversion-status/{jobId}نقطة الحالة
GET/download/{downloadToken}نقطة التنزيل

نظرة عامة

واجهة Bank Statement Conversion API مخصصة للمطورين الذين يريدون إضافة التحويل إلى تطبيقاتهم. توثق مسار التحويل العام: يمكن التحقق من سعة الحساب، ثم رفع الملفات، ثم متابعة حالة المهمة، ثم تنزيل المخرجات المكتملة باستخدام الرمز المعاد.

تقتصر هذه المرجعية عمدًا على سير التحويل العام.

بدء سريع

الخطوة 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

وكلاء الذكاء الاصطناعي

استخدام 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 البعيدة.

إعداد الرمز مرة واحدة

  1. سجّل الدخول مرة واحدة وأنشئ رمز API في لوحة التحكم.
  2. اترك كل صلاحيات التحويل مفعّلة إلا إذا كنت تريد رمزًا مقيّدًا.
  3. اضبط الرمز باسم BSC_API_TOKEN في بيئة عميل MCP.
  4. ألغِ الرمز من لوحة التحكم عندما يجب إيقاف وصول الوكيل.

ربط Codex وClaude وCursor وعملاء الذكاء الاصطناعي الآخرين

كل عملاء الذكاء الاصطناعي المتوافقين مع MCP يستخدمون نفس endpoint البعيد ورمز bearer. احتفظ بالرمز في متغير بيئة، وليس داخل prompts أو الكود المصدري.

نقطة 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 أو بيئة النظام، ثم أعد تشغيل عميل الذكاء الاصطناعي.

Token environment variablebash
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 كسياق للمنتج مع الوكلاء الذين يدعمون ملفات المعرفة.

صلاحيات الرمز المحددة النطاق

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[].
separate_debit_creditbooleanلاهل يتم فصل أعمدة المدين والدائن. الافتراضي: false.
combine_filesbooleanلاهل يتم دمج عدة ملفات في مخرج واحد. الافتراضي: false.

مثال استجابة

استجابة JSONjson
انسخ هذا الشكل للمعالجة في العميل والتعامل مع الأخطاء.
{
  "stage": "pending",
  "jobId": "5f3a7d8c-8a91-4a2e-9d3b-4c84f0636c12"
}

نقطة الحالة

GET /api/conversion-status/{jobId}

تتيح لك نقطة النهاية هذه التحقق من حالة مهمة التحويل. يجب متابعتها حتى تكتمل المهمة.

معلمات المسار

المعلمةالنوعالوصف
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."
}

حدود المعدل

لضمان الاستخدام العادل للواجهة، تطبق حدود المعدل حسب خطة اشتراكك:

  • المستخدمون المميزون: 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}